一、引言

在鸿蒙 ArkTS 布局系统中，.width('100%') 是最常用的属性之一，几乎每个页面都会用到。但你真的理解它的含义吗？

许多开发者从 CSS 背景转到 ArkTS 时，会天然地认为 width('100%') 就是「占满父容器」。这个理解在大方向上没错，但在细节上——尤其是当父容器带有 padding、或者父容器本身也没有明确宽度时——行为可能和直觉完全不同。

本文通过三个层层递进的场景（基线对照 → 固定宽度父容器 → padding 陷阱），帮你彻底吃透 width('100%') 的本质。

---

二、核心心法：一句话记住

在深入代码之前，请先记住这一句话，它是理解一切问题的钥匙：

width('100%') 永远等于「父容器内容区的宽度」，不是屏幕宽度，也不是父容器总宽度。

「内容区」指的是父容器总宽度减去左右 padding 之后剩下的区域。这一点与 CSS 的 width: 100% 完全一致——但 ArkUI 在 border 的处理上有所不同，我们会在第三篇中详细讨论。

---

三、场景①：有 / 无 width(‘100%’) 的基线对照

3.1 实验目的

最朴素的对比：在一个 Row 中放置两个子 Column，一个不给 .width()，一个给 .width('100%')，观察它们的宽度差异。

3.2 完整代码

// ──────────────────────────────────────
// 场景 ①：基线对照
// ──────────────────────────────────────
Row() {
  // ● 左侧：无 .width()
  Column() {
    Column() {
      Text('无 width')
        .fontSize(11).fontColor('#fff')
    }
    .padding({ top: 12, bottom: 12, left: 8, right: 8 })
    .backgroundColor('#FF6B6B')
    .borderRadius(6)
    // ★ 注意：没有 .width() → 宽度由内容决定
  }
  .alignItems(HorizontalAlign.Start)
  .margin({ right: 6 })

  // ● 右侧：有 .width('100%')
  Column() {
    Column() {
      Text('.width(\'100%\')')
        .fontSize(11).fontColor('#fff')
    }
    .width('100%')       // ★ 关键：填充父容器可用宽度
    .padding({ top: 12, bottom: 12, left: 8, right: 8 })
    .backgroundColor('#4ECDC4')
    .borderRadius(6)
  }
  .layoutWeight(1)       // 让此 Column 占据 Row 剩余空间
  .alignItems(HorizontalAlign.Start)
}
.width('100%')
.padding(12)
.backgroundColor('#F0F0F0')
.borderRadius(8)

3.3 运行结果分析

子组件	宽度行为	视觉效果
左侧：无 .width()	宽度 = 内容宽度（文字「无 width」的宽度 + 左右 padding 16vp）	红色条很窄，仅包裹文字
右侧：.width('100%')	宽度 = 父容器（Row）分配给它的可用宽度	青色条填满剩余空间

3.4 深入解读

没有 .width() 时，组件的宽度由什么决定？

ArkUI 中，Column 组件的默认宽度行为是 「宽度由内容撑开」——也就是所谓的 shrink-to-fit。Column 会先测量所有子组件中宽度最大的那个，然后以此作为自己的宽度。如果 Column 的所有子组件的宽度都明确（比如都设置了固定宽度或 '100%'），那么 Column 的宽度就等于这些子组件的最大宽度。

但这里有一个微妙之处：如果 Column 外面还包了一层 Column 或 Row，且外层设置了 alignItems(HorizontalAlign.Start)，那么内层 Column 即使不设 .width()，也可能被外层约束到子组件宽度 = 内容宽度。

右侧为什么需要 layoutWeight(1)？

如果去掉右侧外层的 .layoutWeight(1)，你会发现即使里面的 Column 设了 .width('100%')，右侧的整体宽度也并没有撑满整个 Row。这是因为：

1. Row 的布局算法是：先给每个子组件分配「固有宽度」（由子组件的内容或显式宽度决定）
2. 如果子组件没有设置 layoutWeight，Row 不会给它分配额外空间
3. 没有分配到额外空间的子组件，即使其内部 Column 设了 width('100%')，这个「100%」的基准也只有它的固有宽度那么大

这引出了一个重要结论：width('100%') 只保证「相对于当前分配到的可用宽度填满」，但不保证「去争取更大的可用宽度」。 要争取更大的可用宽度，需要 layoutWeight 或父容器的 stretch 行为。

---

四、场景②：在固定宽度父容器中

4.1 实验目的

显式设置父容器的宽度为 200vp，然后观察子 Column 的 width('100%') 是否等于 200vp。

4.2 完整代码

// ──────────────────────────────────────
// 场景 ②：固定宽度父容器
// ──────────────────────────────────────
Column() {
  // 子 Column
  Column() {
    Text('子 Column · width(\'100%\')')
      .fontSize(12).fontColor('#fff')
      .textAlign(TextAlign.Center)
      .width('100%')
      .lineHeight(40)
  }
  .width('100%')           // ★ 子 Column = 200vp
  .backgroundColor('#FF9800')
  .borderRadius(6)

  Text('← 橙色 = 子 Column，宽度正好 200vp')
    .fontSize(11).fontColor('#FF9800')
    .margin({ top: 4 })
}
.width(200)                // ★ 父容器固定 200vp 宽
.padding(8)
.backgroundColor('#FFF3E0')
.borderRadius(8)

4.3 运行结果分析

父容器的宽度被显式设为 200vp，padding 为 8vp（左右共 16vp）。
子 Column 的 width('100%') = 200vp − 16vp = 184vp。

是的，你没有看错——这里的「100%」并不是 200vp，而是 184vp。padding 已经被扣除了。

4.4 与 CSS 的对比

如果你熟悉 CSS，这个行为其实完全等同于：

.parent {
  width: 200px;
  padding: 8px;
  box-sizing: content-box; /* 默认值 */
}
.child {
  width: 100%; /* = 200px - 16px = 184px */
}

但有一个重要区别：CSS 的 box-sizing: border-box 可以让 width: 100% 包含 padding 和 border 的尺寸，而 ArkUI 没有 box-sizing 属性。在 ArkUI 中，width('100%') 始终指内容区的 100%，padding 和 border 都位于内容区之外（或之内，border 在内部，详见第三篇）。

---

五、场景③：父容器有 padding 时 width(‘100%’) 的行为（常见陷阱）

5.1 实验目的

这是日常开发中最容易踩坑的场景。父容器设置了 padding，子组件设了 width('100%')——子组件会不会溢出？

5.2 完整代码

// ──────────────────────────────────────
// 场景 ③：父容器有 padding
// ──────────────────────────────────────
Column() {
  // 父容器
  Column() {
    // ★ 子 Column width('100%')
    Column() {
      Text('子 · width(\'100%\')')
        .fontSize(12).fontColor('#fff')
        .textAlign(TextAlign.Center)
        .width('100%')
        .lineHeight(36)
    }
    .width('100%')
    .backgroundColor('#7B68EE')
    .borderRadius(6)

    Text('← 子 Column 宽度 = 父内容区宽度，正好在 padding 内侧')
      .fontSize(11).fontColor('#7B68EE')
      .margin({ top: 4 })
  }
  .width('100%')           // 父容器的宽度 = 屏幕宽度 - 2×16（Scroll padding）
  .padding(16)             // ★ 父有 padding=16
  .backgroundColor('#F0F0FF')
  .borderRadius(8)
}

5.3 为什么说这是「陷阱」？

很多从其他 UI 框架转过来的开发者，对 padding 的理解是：padding 是组件内部的「留白」，子组件应该自动避开 padding 区域。这在大多数现代 UI 框架中都是成立的，ArkUI 也不例外。

但「陷阱」在于：

1. 初学者常犯的错误：在父容器上设了 padding(16)，然后在子组件上也设 width('100%') 并在子组件上加 margin(10)，结果子组件超出了父容器的视觉边界。
2. padding 的叠加效应：如果页面最外层 Scroll 有 padding(16)，父 Column 又有 padding(16)，子 Column 还有 padding(8)——每层都在扣减可用宽度，最终内容区的宽度可能比你想象的小得多。

5.4 宽度传递的数学公式

设：

• 屏幕宽度 = S
• Scroll 左右 padding = P_scroll
• Column 父容器左右 padding = P_parent
• Column 子容器左右 padding = P_child

则该子容器内部的实际可用宽度为：

W = S - 2 × P_scroll - 2 × P_parent - 2 × P_child

假设 S = 360vp，P_scroll = 16，P_parent = 16，P_child = 0：

W = 360 - 32 - 32 = 296vp

这就是为什么在布局调试时，你设置的 width('100%') 的组件宽度看起来总是「差了那么一点」——那是因为 padding 吃掉了一部分。

5.5 防御性编程建议

为了避免 padding 导致的布局意外，建议遵循以下原则：

1. 最外层 Scroll/Column 统一管理页面级 padding，内部组件不要再重复加同方向的 padding。
2. 使用 layoutWeight 替代 width('100%') 进行弹性填充，特别是在 Row 中。
3. 调试时可以先给组件加一个显眼的 backgroundColor，直观地看到它的实际宽度。
4. 善用 DevEco Studio 的 Inspector 工具，查看组件的布局盒模型。

---

六、第一篇总结

编号	场景	核心结论
①	有/无 width(‘100%’) 基线对照	无 width → 内容宽度；有 width(‘100%’) → 填满父内容区
②	固定宽度父容器	width(‘100%’) = 父固定宽 − 父 padding
③	父容器有 padding	padding 扣减可用宽度，子组件自动适应，不会溢出

一句话记住：width('100%') 的对象永远是「父容器的内容区」，padding 已经被扣除。