引子：一个"小应用"引发的思考

需求不复杂——掷骰子、抛硬币、生成指定范围的随机数，再加上历史记录。我顺手用 HarmonyOS 的 ArkTS 写了一个，结果发现这个看似简单的应用，恰好把 ArkUI 几个核心机制都串起来了：状态管理、自定义构建器、组件通信、数据持久化。

完整效果

技术栈与环境

• 开发框架：HarmonyOS ArkTS (ArkUI)
• 开发工具：DevEco Studio 5.0+
• 目标平台：HarmonyOS NEXT
• 语言：TypeScript 的超集 ArkTS

应用整体架构

打开代码，第一眼看到的是四个 Tab：骰子、硬币、随机数、历史。这四个功能模块通过底部导航栏切换，每个模块独立构建。这种结构在移动端很常见，但 ArkTS 的实现方式和 React Native 或 Flutter 有明显区别。

// 底部 Tab 定义
private tabs: TabItem[] = [
  { key: 'dice', icon: '🎲', label: '骰子' },
  { key: 'coin', icon: '🪙', label: '硬币' },
  { key: 'rand', icon: '🎯', label: '随机数' },
  { key: 'history', icon: '📜', label: '历史' }
];

这里用了一个简单的对象数组来管理 Tab 状态，配合 ForEach 渲染。看起来没什么特别的，但 ArkTS 的 ForEach 和 React 的 map 有一个关键区别：ArkTS 的 ForEach 第二个参数是 item generator，第三个参数是 key generator（可选）。如果数据项会变化（比如列表增删），一定要提供稳定的 key，否则渲染会出问题。

为什么选择四个独立 Tab 而不是一个长页面？

朋友最初的建议是"做成一个长页面，上下滑动"。但考虑到实际使用场景——桌游过程中用户可能频繁切换骰子和硬币功能，滑动操作效率太低。底部 Tab 导航让用户可以一键切换，这是移动端交互的最佳实践。

更重要的是，从技术角度看，四个 Tab 对应四个 @Builder 方法，每个方法内部的逻辑完全独立。如果合并成一个长页面，状态管理会变得混乱——比如掷完骰子后，页面滚动位置会重置，用户体验很差。

状态管理：@State 装饰器的使用哲学

整个应用的核心状态都集中在 Index 组件上：

@State tab: string = 'dice';
@State theme: ThemeType = ThemeType.DARK;
@State diceType: string = 'd6';
@State diceCount: number = 1;
@State results: number[] = [];
@State total: number = 0;
@State rolling: boolean = false;
@State showResult: boolean = false;
@State history: RollResult[] = [];
@State coinResult: string = '';
@State randMin: number = 1;
@State randMax: number = 100;
@State randResult: number = 0;

ArkTS 的 @State 装饰器和 React 的 useState 有本质区别。React 的 useState 是函数式的，每次调用都会返回新的状态值；而 ArkTS 的 @State 是声明式的，直接绑定到组件的属性上。这意味着：

1. 状态变更自动触发重新渲染：修改 @State 变量后，框架会自动重新执行 build() 方法中受影响的部分
2. 状态是响应式的：不是整个组件重新渲染，而是只更新绑定了该状态的 UI 部分

但这里有个容易踩的坑：状态提升（State Hoisting）。我把所有状态都放在 Index 组件里，是因为这些状态需要在多个子 Tab 之间共享。如果把 history 放在 HistoryTab 里，DiceTab 掷完骰子后就无法更新历史记录了。

不过，当应用变复杂时，这种"把所有状态堆在顶层"的做法会变得难以维护。ArkTS 提供了 @State、@Prop、@Link、@Provide/@Consume 等多种状态管理方案，选择哪种取决于数据的流向：

• @State：组件内部状态，父组件不可直接修改
• @Prop：父组件向子组件单向传递数据
• @Link：父子组件双向绑定
• @Provide/@Consume：跨层级组件通信

对于这个小应用，@State 就够了。但如果要做成生产级应用，建议拆分组件，用 @Link 或 @Provide/@Consume 来管理状态流。

状态更新的性能陷阱

ArkTS 的状态更新是批量处理的。如果在同一个事件循环中多次修改 @State，框架会合并这些更新，只触发一次重新渲染。这在大多数情况下是好事，但有时会导致中间状态丢失。

比如在 doRoll 方法中，我需要先设置 rolling = true，再设置 showResult = false。如果这两行代码紧挨着，框架可能只渲染一次，用户就看不到"投掷中"的状态了。解决方案是用 setTimeout 把它们分开，或者用 @State 的回调机制（如果框架支持的话）。

骰子滚动动画：setTimeout 的妙用

骰子投掷的动画效果是这个应用最有趣的部分：

private async doRoll(): Promise<void> {
  this.rolling = true;
  this.showResult = false;
  const sides = this.cd().sides;
  const count = this.diceCount;
  let c = 0;
  const total = 12;

  const tick = (): void => {
    const tmp: number[] = [];
    for (let i = 0; i < count; i++) {
      tmp.push(Math.floor(Math.random() * sides) + 1);
    }
    this.results = tmp;
    let s = 0;
    for (let i = 0; i < tmp.length; i++) s += tmp[i];
    this.total = s;
    c++;

    if (c < total) {
      setTimeout(tick, 40 + c * 10);
    } else {
      const fr = rollDice(sides, count);
      this.results = fr;
      let fs = 0;
      for (let i = 0; i < fr.length; i++) fs += fr[i];
      this.total = fs;
      this.showResult = true;
      this.rolling = false;

      if (this.db) {
        this.db.add(createRollResult(this.diceType, fr));
        this.history = this.db.getHistory();
      }
    }
  };
  tick();
}

这段代码用递归 setTimeout 模拟了骰子滚动效果。每次 tick 都生成一组随机数，更新 UI，然后设置下一次 tick 的延迟。延迟时间是 40 + c * 10 毫秒，意味着随着滚动次数增加，速度会逐渐变慢——这和真实骰子的物理特性很像。

为什么用 setTimeout 而不是动画框架？

ArkTS 的动画系统（animation 属性、animateTo 等）适合做平滑的过渡动画，但骰子滚动这种"快速切换内容"的效果，用 setTimeout 更直接。每次 tick 都重新生成随机数并赋值给 @State，框架会自动触发重新渲染，用户就看到了骰子面不断变化的效果。

性能考量：

12 次 tick，每次间隔 40-150ms，总耗时大约 1-2 秒。对于这种轻量级动画，setTimeout 的性能完全够用。如果要做更复杂的动画（比如 3D 旋转），建议用 ArkTS 的 @ohos.animator API。

最后一步的处理：

注意 else 分支里的逻辑：动画结束后，调用 rollDice(sides, count) 生成最终结果，然后保存到数据库。这里有个细节——rollDice 函数是在 ../model/Dice 中定义的，它返回的是一个确定的结果，而不是随机数。这样做的好处是可以在测试时 mock 这个函数，确保结果可预测。

递归 setTimeout vs setInterval

这里用递归 setTimeout 而不是 setInterval，是有原因的。setInterval 的执行时间不固定——如果上一次 tick 的执行时间超过了间隔时间，下一次 tick 会立即执行，导致动画卡顿。而 setTimeout 是在上一次执行完成后才开始计时，保证了动画的流畅性。

更重要的是，递归 setTimeout 可以动态调整间隔时间（40 + c * 10），而 setInterval 的间隔是固定的。这种"先快后慢"的动画效果，用 setInterval 很难实现。

随机数生成的公平性

代码中用 Math.floor(Math.random() * sides) + 1 来生成随机数。这个公式是标准的均匀分布随机数生成方法，对于骰子应用来说是公平的。但需要注意的是，Math.random() 的随机性取决于浏览器的实现，在某些极端情况下可能不够"随机"。对于游戏应用来说这完全够用，但如果涉及密码学或安全场景，应该用 crypto.getRandomValues()。

主题系统：深色模式的实现

应用支持深色主题，通过 getThemeColors 函数获取当前主题的颜色配置：

private gc(): ThemeColors { return getThemeColors(this.theme); }

然后在 UI 中通过 this.gc().primary、this.gc().text 等方式引用颜色。这种模式的好处是：

1. 主题切换方便：只需修改 this.theme 的值，整个应用的颜色就会自动更新
2. 颜色一致性：所有颜色都从同一个配置对象获取，避免了硬编码颜色值散落在代码各处
3. 可维护性：新增主题只需在 Theme.ts 中添加配置，不需要修改 UI 代码

但这里有个问题：当前实现是通过 this.theme 状态来控制主题，而 ThemeType 只有 DARK 一种值。如果要支持浅色模式，需要：

1. 在 Theme.ts 中添加 LIGHT 主题的配置
2. 添加切换主题的 UI 控件（比如设置页面）
3. 考虑跟随系统主题（使用 @ohos.app.ability.Configuration API）

颜色透明度的处理

代码中用 this.gc().primary + '20' 来添加透明度。这依赖于颜色值是 6 位十六进制字符串。如果主题配置返回的是其他格式（比如 rgb() 或 rgba()），这种拼接就会失效。建议统一使用十六进制格式，或者提供一个专门的函数来处理颜色透明度。

// 更安全的颜色透明度处理
function withAlpha(hexColor: string, alpha: number): string {
  const alphaHex = Math.round(alpha * 255).toString(16).padStart(2, '0');
  return hexColor + alphaHex;
}

// 使用示例
.backgroundColor(withAlpha(this.gc().primary, 0.12))

这样不仅更安全，而且代码意图也更清晰——看到 withAlpha 就知道是在处理透明度，而不是字符串拼接。

数据持久化：DiceDatabase 的设计

应用使用 DiceDatabase 类来保存历史记录：

private db: DiceDatabase | null = null;
private ctx: common.UIAbilityContext | null = null;

private async init(): Promise<void> {
  this.ctx = getContext(this) as common.UIAbilityContext;
  this.db = new DiceDatabase(this.ctx);
  await this.db.init();
  this.history = this.db.getHistory();
}

DiceDatabase 封装了底层的存储逻辑（可能是 Preferences API 或关系型数据库）。这里有几个设计要点：

1. 异步初始化：数据库初始化是异步操作，需要在 aboutToAppear 生命周期中调用
2. 空值保护：db 和 ctx 都可能为 null，所以在使用前要检查
3. 数据同步：每次掷完骰子后，调用 this.db.add() 保存结果，然后重新获取历史列表

Preferences API vs 关系型数据库

对于这种简单的键值对存储，HarmonyOS 的 Preferences API 就够了。Preferences 适合存储少量配置数据，API 简单，性能好。但如果要支持复杂查询（比如按日期筛选、统计分析），建议用关系型数据库 RDB。

特性	Preferences	关系型数据库 (RDB)
数据结构	键值对	表、行、列
查询能力	按 key 获取	SQL 查询
性能	读写快	复杂查询慢
适用场景	配置、少量数据	大量结构化数据
数据上限	约 1MB	无硬性限制

在这个应用中，历史记录可能会增长到几百条。如果用 Preferences，每次获取历史记录都需要读取整个数据集，性能会下降。而 RDB 支持分页查询，可以只获取最近的 N 条记录。

数据库初始化的时序问题

aboutToAppear 是组件即将出现时调用的生命周期方法，但数据库初始化是异步的。如果用户在初始化完成前就点击了"投掷"按钮，db 还是 null，会导致崩溃。需要添加 loading 状态或禁用按钮，直到初始化完成。

@State dbReady: boolean = false;

private async init(): Promise<void> {
  this.ctx = getContext(this) as common.UIAbilityContext;
  this.db = new DiceDatabase(this.ctx);
  await this.db.init();
  this.history = this.db.getHistory();
  this.dbReady = true;  // 标记初始化完成
}

// 在 UI 中禁用按钮
Row() {
  Text('🎲 投掷').fontSize(FontSize.xl).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
}
.width('80%').height(56).justifyContent(FlexAlign.Center)
.backgroundColor(this.rolling || !this.dbReady ? this.gc().border : this.gc().primary)
.borderRadius(BorderRadius.xl)
.opacity(this.dbReady ? 1 : 0.5)  // 未就绪时降低透明度
.onClick(() => { if (this.dbReady && !this.rolling) this.doRoll(); })

这样既保证了安全性，又给用户明确的视觉反馈。

自定义构建器：@Builder 的组件化实践

应用大量使用了 @Builder 装饰器来定义可复用的 UI 片段：

@Builder DiceTab() { ... }
@Builder CoinTab() { ... }
@Builder RandTab() { ... }
@Builder HistoryTab() { ... }

@Builder 是 ArkTS 中实现组件化的重要机制。它和 @Component 的区别在于：

• @Component 是独立的组件，有自己的状态和生命周期
• @Builder 是 UI 片段，通常用于复用布局逻辑，没有独立的状态

在这个应用中，@Builder 的使用很合理——每个 Tab 的 UI 逻辑相对独立，但又共享 Index 组件的状态。如果用 @Component 来实现，就需要通过 @Link 或 @Prop 把状态传递下去，增加了复杂度。

什么时候用 @Builder，什么时候用 @Component？

这是一个常见的决策问题。根据我的经验，可以从以下几个维度考虑：

1. 状态需求：如果 UI 片段需要独立的状态，用 @Component；如果只是展示数据，用 @Builder
2. 复用性：如果要在多处复用同一套 UI，用 @Component；如果只在一个地方用，用 @Builder
3. 通信复杂度：如果需要和父组件频繁通信，用 @Builder（直接访问父组件状态）；如果通信少，用 @Component（通过 @Prop/@Link）
4. 性能：@Component 有独立的渲染上下文，性能开销稍大；@Builder 共享父组件的渲染上下文，性能更好

@Builder 的局限性

@Builder 不能有自己的 @State，这意味着它不能响应内部状态变化。如果需要在 Builder 内部维护状态，要么把状态提升到父组件，要么改用 @Component。

此外，@Builder 的参数传递方式和函数类似，不支持双向绑定。如果需要双向绑定，必须用 @Component 配合 @Link。

踩坑记录

在开发过程中，遇到了几个值得注意的问题：

坑 1：ForEach 的性能问题

ArkTS 的 ForEach 在数据量大时可能有性能问题。比如历史记录列表，如果用户掷了几百次骰子，ForEach 每次都会重新渲染整个列表。解决方案是使用 List 组件的懒加载特性，只渲染可见区域的元素。

// 优化前：ForEach 渲染所有项
ForEach(this.history, (r: RollResult) => {
  ListItem() { ... }
})

// 优化后：List 懒加载
List() {
  ForEach(this.history, (r: RollResult) => {
    ListItem() { ... }
  })
}
.width('100%').layoutWeight(1).scrollBar(BarState.Off)

List 组件会自动处理懒加载，只渲染用户可见的列表项，大幅提升了滚动性能。

坑 2：状态更新的时机

在 doRoll 方法中，我用 setTimeout 来延迟状态更新。但 ArkTS 的状态更新是异步的，如果在同一个事件循环中多次修改 @State，框架可能会合并这些更新，导致中间状态丢失。测试时要确保每次 tick 都能正确触发重新渲染。

坑 3：颜色透明度的字符串拼接

代码中用 this.gc().primary + '20' 来添加透明度。这依赖于颜色值是 6 位十六进制字符串。如果主题配置返回的是其他格式（比如 rgb() 或 rgba()），这种拼接就会失效。建议统一使用十六进制格式，或者提供一个专门的函数来处理颜色透明度。

坑 4：数据库初始化的时序

aboutToAppear 是组件即将出现时调用的生命周期方法，但数据库初始化是异步的。如果用户在初始化完成前就点击了"投掷"按钮，db 还是 null，会导致崩溃。需要添加 loading 状态或禁用按钮，直到初始化完成。

代码改进建议

虽然这个应用功能完整，但还有一些可以优化的地方：

1. 状态管理优化

把所有状态都放在 Index 组件里，随着功能增加会变得难以维护。建议：

• 把每个 Tab 的状态封装到独立的组件中
• 用 @Provide/@Consume 来共享需要跨组件访问的状态（比如 history）

2. 错误处理

当前代码几乎没有错误处理。比如数据库操作失败时，应该给用户友好的提示，而不是静默失败。

private async clr(): Promise<void> {
  if (this.db) {
    try {
      await this.db.clear();
      this.history = [];
    } catch (error) {
      // 这里应该弹出 Toast 提示用户
      console.error('清空历史失败:', error);
    }
  }
}

3. 无障碍支持

应用没有添加无障碍属性（ariaLabel 等），这对视障用户不友好。HarmonyOS 的无障碍框架很完善，建议添加。

Text('🎲 投掷').fontSize(FontSize.xl).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
.ariaLabel('投掷骰子')

4. 单元测试

rollDice 和 createRollResult 这些纯函数很容易测试，但 UI 逻辑的测试需要 DevEco Studio 的测试框架支持。建议为业务逻辑编写单元测试，确保核心功能的正确性。

替代方案对比

在实现类似功能时，有几种替代方案值得考虑：

方案 1：使用 @ohos.animator 实现动画

如果要实现更流畅的 3D 骰子动画，可以用 @ohos.animator API。它提供了更精细的动画控制，比如插值器、时间曲线等。但 API 复杂度更高，对于简单的滚动效果来说有些杀鸡用牛刀。

方案 2：使用 Tabs 组件

ArkTS 内置了 Tabs 组件，专门用于实现 Tab 导航。它提供了滑动切换、指示器等特性，比手写 Tab 导航更方便。但 Tabs 组件的自定义程度有限，如果需要特殊的 Tab 样式，还是得自己实现。

方案 3：使用 @State 装饰器的不同变体

ArkTS 5.0 引入了 @Observed/@ObjectLink 装饰器，用于处理嵌套对象的状态管理。如果 RollResult 对象内部有需要响应式更新的属性，可以用这套方案。但对于当前应用，@State 就够了。

总结

这个随机数应用虽然功能简单，但涉及了 ArkTS 开发的多个核心知识点：状态管理、自定义构建器、异步操作、数据持久化、主题系统。在实际开发中，这些知识点会反复出现，只是复杂度不同。

对于 ArkTS 新手，建议从类似的小项目入手，逐步理解框架的设计哲学。ArkTS 的声明式 UI 和 React 有相似之处，但状态管理和生命周期有明显区别，需要花时间适应。

对于有经验的开发者，重点是理解 ArkTS 的约束——它不是 TypeScript 的简单扩展，而是一个有自己规则的框架。遵循框架的最佳实践，才能写出可维护、高性能的代码。

适用边界：这个应用适合用作 ArkTS 入门学习项目，涵盖了 UI 开发、状态管理、数据持久化等核心知识点。但如果要上架应用商店，还需要补充错误处理、无障碍支持、性能优化、用户引导等内容。建议在此基础上逐步扩展，而不是一次性做完所有功能。