企业官网建设流程全解析

1. 先搞清楚 width()/height() 到底是什么

1.1 最基础用法：从一段最普通的代码说起

在鸿蒙开发里，width() 和 height() 是 ArkUI 声明式UI中最常用的两个通用属性。很多人刚上手的时候觉得这没什么好讲的，不就是给组件设个宽高吗？但实际上，这两个API背后的规则比你想象的要复杂得多。我先放一段最常见的代码：

@Entry @Component struct Index { build() { Column() { Text('Hello HarmonyOS') .width(200) .height(100) .backgroundColor('#ff4757') .fontSize(20) .textAlign(TextAlign.Center) } .width('100%') .height('100%') } }

这段代码很简单，但已经有几个值得注意的点：

• width(200)和height(100)的单位默认是 vp（virtual pixel，虚拟像素），不是 px，也不是 dp。
• '100%'表示相对父容器尺寸的百分比，而不是相对屏幕。
• 调用顺序上，width()和height()在链式调用中位置不限，但一旦和其他约束属性一起用，优先级规则就会生效。

这个 API 解决的核心问题是：让开发者可以用简短、直观的方式声明组件的尺寸意图。但它并不像表面看起来那么简单——单位选错、百分比语义理解偏差、与约束属性的冲突，都是新手必然踩的坑。

先说结论：width()/height() 是尺寸声明的入口，但不是唯一入口。你的组件最终尺寸由 width/height、constraintSize、layoutWeight、aspectRatio 以及父容器的布局规则共同决定。光盯着这两个API，很容易写出“看起来没问题但一运行就变形”的界面。

1.2 四种取值方式，用错很麻烦

width()和height()的参数类型是Length，也就是string | number | Resource。实际开发中常见的四种写法：

这里面最常见的坑是第三种写法。有人从接口拿到一个字符串数字，直接塞进去，发现没问题；但一旦接入屏幕密度变化或深色模式，尺寸就乱了。原因是字符串形式的'200'虽然在大多数场景等效于200，但它不会走编译期的单位换算和校验逻辑，出了问题也更难定位。

Resource 写法是鸿蒙推荐的正式做法，尤其适合需要全局统一管理尺寸的场景。在resources/base/element/float.json里定义好数值：

{ "float": [ { "name": "card_width", "value": "160vp" } ] }

然后在代码里用$r('app.float.card_width')引用。这样做的优势是：多设备适配时，可以在resources/dark、resources/tablet等不同限定符目录下提供不同的值，不需要改业务代码。

还有一个小细节：width('200vp')这种带单位的字符串是合法的，vp、px、%、lp都支持。lp是鸿蒙新版引入的逻辑像素单位，和 vp 的换算关系在不同设备上会动态调整，主要用于超大屏和折叠屏的适配，日常项目用 vp 就够。

2. 尺寸设置的底层逻辑：为什么直接写数字经常不对

2.1 vp 与 px：你写的是逻辑像素，不是物理像素

很多从 Android 转过来的开发者会有个疑问：鸿蒙的 vp 和 Android 的 dp 是不是一回事？答案是不完全一样。

vp（virtual pixel）是鸿蒙的逻辑像素单位，设计初衷是为了让 UI 在不同像素密度的设备上保持一致的物理尺寸感。在 160ppi 的屏幕上，1vp = 1px；在 320ppi 的屏幕上，1vp = 2px。

但和 Android dp 不同的是，鸿蒙的 vp 还参与了横竖屏切换时的密度补偿。同一个width(200)，在默认竖屏和横屏状态下的实际物理像素可能不同，这是为了让用户在旋转设备时看到的元素比例不至于失衡。这也是为什么你有时会发现，横屏后组件的视觉尺寸和竖屏时不太一样——不是 bug，是特性。

如果你确实需要以物理像素为单位设置尺寸，可以用px2vp()做转换：

import { display } from '@kit.ArkUI'; let displayInfo = display.getDefaultDisplaySync(); let vpWidth = px2vp(displayInfo.width);

不过绝大多数场景不需要这么做。记住一条原则：业务代码里尽量只用 vp 和百分比，不要直接写 px。否则同一套代码在不同分辨率的设备上会出现明显的视觉差异，QA 提的“界面变形”问题大概率就是这么来的。

2.2 百分比背后的父容器计算规则

width('50%')是相对父容器内容区宽度来算的，听起来很简单，但有几个容易被忽略的细节：

第一，父容器如果是Column，子组件的width('100%')指的是 Column 的内容区宽度，不是 Column 自身的宽度。如果 Column 设置了 padding，那么“100%”会减去左右 padding 再计算。也就是说，Column().padding(10)里面的子组件width('100%')，实际宽度是父容器宽度减 20vp。

第二，百分比在部分场景下会失效。比如在Scroll里，如果子组件用height('100%')，这个百分比参照的不一定是 Scroll 的可视区域高度，而是 Scroll 的内容总高度。内容一旦超过一屏，height('100%')就会变得不可预测。这是新手最容易困惑的地方。

第三，width('100%')加上父容器的alignItems设置会产生视觉上的“不居中”错觉。比如 Column 默认alignItems: HorizontalAlign.Center，子组件宽度 100% 时是撑满的，没问题；但如果你把某个子组件改成width('80%')，它会居中显示，如果 Column 的 alignItems 被设置成了 Start，又会靠左。百分比是相对于父容器算的，但位置还要看对齐方式，两个因素叠加，经常会算出和设计稿不一致的效果。

我的建议是：百分比写可以，但一定要清楚父容器的宽度来源。父容器如果是Row/Column且没有明确宽度，那它的宽度可能由内容撑开，这时候子组件的百分比就没有明确参照物，会出现运行时警告甚至布局异常。

2.3 与 layoutWeight、aspectRatio 的竞争关系

一个组件最终显示的尺寸，并不是 width()/height() 说了算。ArkUI 的布局系统有一套隐性的优先级规则。搞清楚这套规则，才能真正驾驭尺寸控制。

优先级的核心逻辑是：显式约束 > 比例约束 > 权重分配。

举个例子：

Row() { Text('A') .width(100) .layoutWeight(1) Text('B') .width(100) .layoutWeight(2) } .width(300)

这段代码里，两个 Text 的width(100)是不是还生效？答案是不完全。layoutWeight的优先级高于显式 width，Row 会先把两个 Text 的固定宽度需求加起来（100+100），余下的 100vp 按权重分配，A 拿到约 33vp，B 拿到约 67vp。最终 A 宽度约 133vp，B 约 167vp。

再比如aspectRatio（宽高比）和 width/height 的关系。设置了aspectRatio(1)之后，如果你只写width(100)，系统会自动算 height=100，不需要你手动补height()。但如果你同时写了width(100)和height(50)，再设置aspectRatio(1)，最终效果取决于哪个属性后设置以及父容器的约束策略，通常 width/height 会被 aspectRatio 覆盖，产生一个正方形而不是你写的长方形。

这里有一个实用的规律：如果你希望某个组件强制保持宽高比，只给一个方向上的尺寸，再配 aspectRatio，另一个方向不要写。写多了反而会让系统进入内部协商，结果不可控。

还有一个constraintSize，它用来限定宽高的最大最小值。它的优先级高于普通 width/height，但低于父容器的强制约束。意思是：你设置了.constraintSize({ minWidth: 100, maxWidth: 200 })之后，再写.width(300)，最终宽度会被压到 200，而不是 300。

把这些属性放一起排序，我的经验是：

1. 父容器强制布局约束（比如 Flex 主轴方向上的尺寸分配）
2. constraintSize（min/max 限制）
3. aspectRatio（比例约束）
4. layoutWeight（权重分配）
5. width()/height()（显式声明）

这个排序不是官方文档原话，是我在实际项目中反复验证得到的行为归纳。理解这套优先级，你在遇到“我明明写了 width 为什么不变”这类问题时，就能快速定位是哪一层约束在干扰。

3. 实战场景拆解：几个高频场景的处理方法

3.1 图片等比缩放：只用 width/height 是不够的

图片是 ArkUI 里尺寸问题最集中的组件之一。你从服务端拿到的图片可能是 1000x600 的横图，也可能是 500x800 的竖图，但 UI 要求在一个固定大小的卡片里展示，还不能变形。

最原始的做法是：

Image(this.imgUrl) .width(160) .height(160)

这样写的问题在于，图片会被强制拉伸填满 160x160 的区域，比例失调，看起来非常业余。原因是Image默认的objectFit是ImageFit.Cover，它会裁剪填满，不是等比缩放。

正确的写法是结合objectFit与适当地设置宽高：

Image(this.imgUrl) .width(160) .height(160) .objectFit(ImageFit.Contain)

Contain的效果是：在保持图片原始宽高比的前提下，将图片完整展示在 160x160 的区域内，可能会有留白。如果要保持原始比例且不需要固定宽高，可以直接只写一边：

Image(this.imgUrl) .width(160) .aspectRatio(1)

这句话的意思是：宽度 160，宽高比 1:1，高度自动算出来。图片原始比例是 3:2 也没关系，aspectRatio(1)会强制区域变成正方形，配合objectFit(Cover)就是居中裁剪的方形缩略图，和微信头像的裁剪逻辑一致。

还有一种场景是需要图片宽度跟随屏幕，高度按比例自适应。比如一个封面图，希望它宽度占满容器，高度根据图片比例自动撑开，这样不会出现先空白再跳变的问题：

Image(this.coverUrl) .width('100%') .aspectRatio(this.coverRatio) // 由后端接口返回或本地图片解码后计算 .objectFit(ImageFit.Fill)

这里的coverRatio需要你先拿到图片的宽高比。如果一开始不知道，可以用createImagePacker或ImageDecoder去解一下图片信息，常见做法是：

import { image } from '@kit.ImageKit'; let source = image.createImageSource(this.coverUrl); let info = source.getImageInfoSync(); this.coverRatio = info.size.width / info.size.height;

不要试图用onAreaChange去量图片高度再反向设置，那样会经历两轮布局，性能差而且容易闪烁。直接拿到比例一次设置到位，是最稳定的方案。

3.2 动态测量组件的真实高度

有时候你需要在运行时知道某个组件的实际宽高。比如要做一个手势拖动画布，需要知道容器区域的大小；或者要做吸顶效果，需要知道列表头的高度。

常见的做法是使用onAreaChange回调：

@State containerHeight: number = 0; Column() { // 内容... } .onAreaChange((oldValue: Area, newValue: Area) => { this.containerHeight = Number(newValue.height); })

onAreaChange返回的Area对象里包含width和height。这里要注意两点：

第一，newValue的单位是 vp，可以直接参与布局计算，不需要再转换。但如果你要传给 Canvas 画图，通常需要转成 px，因为 Canvas 默认坐标体系是 px。

第二，onAreaChange的触发时机比你想的要频繁。不仅仅是尺寸变化时触发，当组件的位置、安全区、Insets 发生变化时也可能触发。如果回调里有复杂的计算，性能会肉眼可见地变差。

更精确的做法是用onSizeChange：

Column() { // 内容... } .onSizeChange((oldWidth: number, oldHeight: number, newWidth: number, newHeight: number) => { this.containerHeight = newHeight; })

这个 API 只在尺寸真正改变时触发一次，不带位置信息，适合绝大多数“量高度”的场景。它的参数直接就是数字，不需要再解构 Area。

还有一个小技巧：如果你在onSizeChange里拿到了高度，需要把这个高度同步给其他组件，比如兄弟节点的布局，记得用@State或@Link驱动。直接改本地变量不会触发 UI 更新，这个坑很多人踩过。

3.3 列表项高度自适应与性能的平衡

在List组件里，每个列表项的高度策略直接影响到滚动流畅度和视觉表现。最常见的需求是：卡片高度根据内容自适应，而不是固定。

很多人第一反应是：

ListItem() { Column() { Text(this.title) Text(this.desc) } .width('100%') }

这样写，如果desc内容有长有短，卡片高度就是动态的，这没问题。但问题出在性能上。List的懒加载机制下，高度自适应意味着每个 item 都需要在布局阶段动态测量，这会在快速滚动时造成卡顿，尤其是 item 内部还有多层嵌套的时候。

一个实用的优化方案是：在数据层面预先计算并缓存高度。比如卡片内最多三行标题、五行描述，你可以根据文案长度和字体大小预估高度，然后通过ListItem的height属性设置固定高度：

List({ space: 12 }) { ForEach(this.messages, (item: MessageModel) => { ListItem() { MessageCard({ item: item }) } .height(item.estimatedHeight) }) }

这里estimatedHeight在数据加载时就算好，List不再需要逐个测量，滚动性能大幅提升。付出的代价是：如果文案长度变化超过预期，高度可能不精确，出现内容截断。解决方案是设一个安全边距，多预留 10~20vp。

还要注意，List的滚动容器本身默认情况下高度是不确定的。如果你给List设置了.height('100%')，但它外层是一个Scroll，那这个 100% 可能会失效，List 会尝试把所有内容都撑开，懒加载特性就没了。遇到这种情况，要么去掉外层 Scroll，让 List 自己滚动；要么给 List 固定高度或layoutWeight(1)让它填满剩余空间。

4. 常见坑与排查技巧

4.1 100% 不生效的几种典型情况

我自己在实际开发中遇到过无数次“明明写了 100% 但组件宽度不对”的情况。总结下来，最常见的三个原因：

原因一：父容器宽度不确定。如果父容器本身没有确定宽度，它是由子组件撑开的，那么子组件的width('100%')就会进入循环依赖，系统会选择忽略百分比，退回到自适应内容宽度。典型场景是：外层是Row，里面放了一个Text，Text 写了width('100%')，Row 自己没有宽度。这时候 Text 的 100% 没有任何意义。

解决办法是：给父容器一个确定的宽度来源，比如.width('100%')或.layoutWeight(1)。

原因二：百分比的参照对象不是你想的那个。在RelativeContainer或Grid里，width('100%')的参照规则各不相同。Grid的一行里，子组件的百分比是相对所在列宽还是相对 Grid 总宽？答案是，Grid的 item 通常不建议用百分比宽度，因为列宽已经由columnsTemplate决定了，你再写百分比会叠加在一个不明确的参照物上。

原因三：Scroll 嵌套导致的百分比失效。Scroll方向上的百分比对应的是内容区总尺寸，不是可视区尺寸。也就是说，Scroll里子组件height('100%')在内容超高时会失效，变成内容高度而不是可视高度。如果你需要占满一屏，用layoutWeight(1)或flexGrow(1)更可靠。

排查这类问题的思路是：先确认父容器链路上的每一层是否有确定尺寸，再确认有没有使用Scroll，最后检查有没有constraintSize或aspectRatio在干扰。用一个debugBorder()给组件加上边框，就能直观看到每层实际占了多少空间。

4.2 onAreaChange 的触发频率问题

onAreaChange好用，但也容易被滥用。这个回调在设计上是低频的，但实际运行时会因为各种原因被频繁触发，最常见的三个诱因：

• 组件内部有动画，动画过程中尺寸持续变化，回调持续触发。
• 字体缩放或系统设置变化，导致所有组件尺寸重新计算。
• 父容器尺寸变化后，子组件完成二次布局，可能触发多轮 onAreaChange。

在回调里做this.currentHeight = newValue.height这种简单赋值没问题，但千万别在里面做this.someList = complexCompute()这种高开销操作，否则每一帧都在跑一遍计算，列表会卡到没法用。

更稳妥的做法是加一个防抖：

private timer: number = -1; .onAreaChange((oldValue: Area, newValue: Area) => { if (this.timer !== -1) { clearTimeout(this.timer); } this.timer = setTimeout(() => { this.containerHeight = Number(newValue.height); }, 100); })

这样即使回调连续触发多次，也只在最后一次触发后 100ms 更新一次状态，性能影响降到最低。配合onSizeChange使用效果更好，因为onSizeChange本身只关心尺寸，不会因为位置变化就触发。

4.3 嵌套滚动与高度计算冲突

有滚动需求的时候，很多人习惯性地在外层包一个Scroll，里面再放List或者Column，然后发现高度怎么设置都不对。这里我分享一个排查套路。

先看这个例子：

Scroll() { Column() { List() { ForEach(this.items, (item: string) => { ListItem() { Text(item).height(80) } }) } .width('100%') } } .scrollable(ScrollDirection.Vertical)

这段代码的典型症状是：List的高度只显示一屏，无法滚动查看全部内容。原因是List放在Scroll里面时，如果 List 没有明确高度，它会尝试使用父容器给它的可用高度，而这个可用高度被Scroll默认限制为了可视区域高度。

解决方案有两种。第一种是给List一个显式的高度，比如估算所有 item 高度之和，但这样做数据量一大就废了。第二种更推荐的做法是放弃嵌套，把List作为唯一滚动容器：

Column() { // 顶部固定内容 Text('Header').height(50) // 列表占据剩余空间，内部滚动 List({ space: 8 }) { ForEach(this.items, (item: string) => { ListItem() { Text(item).height(80) } }) } .layoutWeight(1) .width('100%') }

用layoutWeight(1)让 List 填满剩余空间，滚动由 List 自身管理，性能最优。如果确实需要外层 Scroll 来带动多个区块滚动，那就把 List 换成Column+ForEach，放弃懒加载，在数据量可控（几十条以内）时这个方案完全够用。

4.4 结论不重要，重要的是排查方法

写了这么久，我最想分享的一个体会是：width()/height() 这两个 API 本身并不复杂，复杂的是它们所处的布局体系。遇到尺寸问题时，不要只盯着当前组件看，要沿着父容器链条向上找。先确认父容器的尺寸来源，再确认有没有 Scroll、Flex 这类会改变测量规则的容器，最后再检查本组件的约束属性组合。

我个人的排查顺序是：

1. 给组件加.debugBorder(true)，看实际渲染范围。
2. 逐层检查父容器的宽度、高度来源。
3. 排查 Scroll、List、Grid 等滚动容器的特殊行为。
4. 检查 constraintSize、aspectRatio、layoutWeight 三个干扰项。
5. 最后才回头确认 width()/height() 的参数类型和单位。

按照这个顺序，绝大多数尺寸问题都能在几分钟内定位。别一上来就怀疑框架有 bug，绝大多数情况下都是我们对布局模型的理解差了那么一点点。鸿蒙这套声明式布局在尺寸控制上已经做得相当完善，剩下的功夫都在细节里。