前言

尺寸数字散落在页面里，短期看不出问题，等视觉规范调整时会非常痛苦。HarmonyOS7 页面里即使暂时不接资源文件，也应该先给核心尺寸命名。

这篇单独聊 通用间距 这个场景。重点不是堆 API，而是给核心尺寸命名，让页面后续迁到资源或主题 token 时有清晰路径。

为什么这个问题经常被写乱

资源尺寸别到处写数字 这类内容很容易被写成“代码能跑就算讲完了”，但对初学者来说，这恰恰是最不够的地方。真正让人卡住的，往往不是某个组件名记不住，而是不知道这段代码为什么要这样拆、状态为什么要这样放、以后需求变化时应该从哪里改。

所以这篇文章不只想给你一个能跑的例子，更想把背后的判断过程讲清楚。你只要把这个判断过程吃透，后面自己改页面、补需求、查问题时，心里会稳很多。

场景：视觉规范调整时全项目找数字

页面刚开始写的时候，8、12、16 直接写在 modifier 里确实最快。问题会在第二轮视觉调整时出现：设计师说卡片内边距从 12 调到 16，列表间距从 10 调到 12，你在代码里搜索 12，会搜出字体、圆角、间距、图标尺寸一大堆。改还是不改，全靠猜。

尺寸 token 的价值就在这里。它不是为了把每个数字都抽出来，而是给“有设计语义的数字”命名，比如页面边距、卡片内边距、列表间距、按钮高度。名字一旦稳定，后面迁到资源文件或主题系统都顺很多。

给尺寸命名，等于把设计意图写进代码。以后改规范时，改的是意图，不是到处碰运气。

哪些数字值得命名

裸数字	推荐命名	用途	是否建议抽取
16	pagePadding	页面左右留白	是
12	cardPadding	卡片内部间距	是
8	itemGap	图文或列表间距	是
40	buttonHeight	主按钮高度	是
1	borderWidth	分割线宽度	看复用频率
3	无	某个特殊微调	不一定

实操步骤

1. 先从单个页面抽出 5 到 8 个核心尺寸，不要一开始就做庞大设计系统。
2. 同类布局只用同一个 token，比如所有卡片内边距都用 cardPadding。
3. 命名体现用途，不要写 size12、radius8 这种数字搬家。
4. 页面稳定后，再把跨页面复用的 token 迁到资源或公共主题对象。

5. 代码评审时重点看新增裸数字是否有明确理由。

先把页面目标想清楚

在真正写代码之前，先别急着盯着 API。更有用的做法是先想清楚：这个页面到底想解决什么问题，用户最在意的反馈是什么，哪些状态必须一直保持一致。

当你先把这条主线想明白，再回头看组件和状态设计，很多选择都会顺理成章。对小白来说，这一步尤其重要，因为它能帮你从“照着抄”慢慢过渡到“看得懂、改得动”。

完整示例：页面内尺寸 token

@Entry
@Component
struct SizeTokenPage {
  private pagePadding: number = 16
  private sectionGap: number = 14
  private cardPadding: number = 12
  private itemGap: number = 8
  private cardRadius: number = 8
  private buttonHeight: number = 40

  @Builder
  InfoCard(title: string, desc: string, badge: string) {
    Column({ space: this.itemGap }) {
      Row({ space: this.itemGap }) {
        Text(badge)
          .fontSize(12)
          .fontColor('#FFFFFF')
          .backgroundColor('#0A59F7')
          .borderRadius(4)
          .padding({ left: 6, right: 6, top: 2, bottom: 2 })

        Text(title)
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .layoutWeight(1)
      }.width('100%')

      Text(desc)
        .fontSize(14)
        .fontColor('#666666')
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
    }
    .alignItems(HorizontalAlign.Start)
    .width('100%')
    .padding(this.cardPadding)
    .backgroundColor('#FFFFFF')
    .borderRadius(this.cardRadius)
  }

  build() {
    Column({ space: this.sectionGap }) {
      Text('资源尺寸示例')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)

      this.InfoCard('命名后的尺寸更好维护', '后续如果视觉规范调整，只需要先改这一组 token。', '推荐')
      this.InfoCard('卡片间距保持一致', '同类模块不要凭手感写数字，统一尺寸会让页面更稳。', '规范')

      Button('应用当前规范')
        .height(this.buttonHeight)
        .width('100%')
    }
    .padding(this.pagePadding)
    .backgroundColor('#F5F7FA')
    .height('100%')
  }
}

把关键代码一段段拆开

pagePadding、cardPadding、sectionGap 这些名字体现的是布局语义。设计师说“页面边距改大一点”，你能直接找到 pagePadding；如果变量叫 size16，它和裸数字没有本质区别。

InfoCard() 复用了卡片内边距和圆角，但没有把所有细小数字都抽走。比如徽标左右 padding 的 6，如果只在这一处使用，可以先保留。抽象的目的不是消灭数字，而是降低未来调整成本。

buttonHeight 单独命名，是因为按钮高度通常会跨页面复用，也容易受规范影响。像主按钮、小按钮、吸底按钮这些尺寸，越早统一越省事。

容易踩坑的点

• 把 12 改名成 size12，只是换了个地方写裸数字。
• 页面里既有 cardPadding，又随手写新的 14 当卡片 padding。
• 所有数字都抽 token，导致代码读起来像查字典。
• 字体大小、间距、圆角混用同一个变量。
• 资源 token 还没稳定就跨模块强推，后面改动影响面过大。

优化建议

先页面内命名，再跨页面沉淀，是更稳的路径。等多个页面都出现 pagePadding、cardPadding、buttonHeight，再迁到统一资源或主题 token。这样抽出来的是被验证过的规范，而不是提前设计的一堆空概念。

折叠屏和平板适配时，页面边距可能会跟断点变化。此时 token 可以从固定数字升级为方法，比如 getPagePadding()，但不要过早复杂化。手机单栏页面先把语义命名做好，就已经能解决大部分维护问题。

尺寸命名要表达设计意图

抽尺寸不是把 12 改成 size12。如果变量名仍然只是在复述数字，那以后视觉规范调整时，开发还是不知道它代表卡片内边距、列表间距还是徽标微调。

示例里的 pagePadding、cardPadding、buttonHeight 都带有用途。设计师说“页面边距加大”，你能直接找到 pagePadding；如果所有变量都叫 size16、space12，维护价值就很有限。

写在最后

也不要一开始就消灭所有裸数字。只在某个徽标里用一次的微调值，可以先保留；页面主间距、按钮高度、卡片圆角这类会反复出现的值，才值得优先命名。等多个页面都复用稳定后，再迁到资源文件或统一主题对象。