鸿蒙 ArkTS 实战：Community Storage Box 从社区寄存柜到社区寄存应用完整解析

前言

社区寄存柜 是一个典型的鸿蒙 ArkTS 生活服务类单页应用。它围绕“社区寄存柜展示 6 号柜、寄存时长、取件码隐藏与显示切换，并支持增加寄存小时数。”这个具体业务展开，用较少的状态字段完成了选择、确认、推进、计费或展示隐藏等常见交互。

这篇文章会从项目真实源码出发，拆解 Community Storage Box 的状态设计、数组渲染、条件样式、按钮事件和业务计算方式。重点不是泛泛介绍语法，而是看一个可运行页面如何把业务动作落到 ArkTS 代码中。

生活服务类页面最需要的是清楚、稳定、可感知：用户点一下，界面就应该立刻告诉他结果。

图示说明：本文围绕页面中的标题区、选择区、状态区和操作区展开，所有示例都对应项目中的真实交互模式。

一、项目背景与使用场景

1.1 业务背景

社区寄存柜展示 6 号柜、寄存时长、取件码隐藏与显示切换，并支持增加寄存小时数。

这类场景很适合用鸿蒙声明式 UI 实现，因为它们通常有明确的当前状态、固定的业务选项，以及一个或两个能够推进流程的按钮。

1.2 用户路径

用户进入页面后的典型路径是：

1. 先查看标题、对象、时间或当前金额。
2. 在列表、网格、标签或流程中选择目标项。
3. 点击按钮完成确认、推进、增加数量或更新状态。
4. 在当前页面看到结果变化。

1.3 页面目标

目标	页面表现	技术实现
识别业务	标题和摘要信息	Text
选择对象	卡片、标签、列表	ForEach
展示结果	状态、金额、进度	@State 绑定
推动动作	确认、增加、更新	Button / Toggle

二、页面入口与基础结构

2.1 Entry 组件

项目页面以 @Entry 和 @Component 标识入口组件，build 方法负责组织完整 UI。

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('社区寄存柜')
    }
  }
}

2.2 为什么适合单页实现

社区寄存柜 的业务闭环很短，核心状态只有 3 个：box、hours、hidden。单页实现能让开发者直接看到状态字段如何影响界面。

2.3 页面区域划分

区域	内容	设计目的
顶部区域	标题、业务对象、当前数值	建立上下文
主体区域	选项、流程、图形区域	承载主要交互
说明区域	地址、备注、时间、提醒	补充业务信息
底部动作	确认、推进、增加	完成状态变化

三、状态字段设计

3.1 State 字段

字段	类型	含义
box	number	当前柜号，默认 6 号柜
hours	number	寄存小时数，默认 4 小时
hidden	boolean	取件码是否隐藏

这些字段都是界面变化的来源。只要字段被更新，ArkTS 声明式 UI 会自动刷新依赖它的组件。

3.2 状态声明代码

@Entry
@Component
struct Index {
  @State box: number = 6; // 当前柜号，默认 6 号柜
  @State hours: number = 4; // 寄存小时数，默认 4 小时
  @State hidden: boolean = true; // 取件码是否隐藏
}

3.3 字段粒度

box、hours、hidden 的粒度比较克制，没有把静态文案也做成状态。这种写法适合小型业务页面，既直观又不会制造额外复杂度。

能用普通字段表达的静态配置，就不必放进响应式状态里。

四、业务数组与数据映射

4.1 静态业务数据

无数组字段：页面围绕柜号、取件码和寄存时长构成单条寄存记录

这些数据与页面的选择项、说明项或流程节点直接对应，是文章分析这个项目时最重要的项目差异来源。

4.2 ForEach 循环渲染

ForEach(this.items, (item: string, index: number) => {
  Text(item)
    .fontSize(16)
    .fontWeight(FontWeight.Bold)
    .onClick(() => {
      this.current = index
    })
})

4.3 索引驱动详情

索引状态可以同时驱动标题、备注、价格、状态和高亮样式：

Text(this.items[this.current])
Text(this.notes[this.current])
.backgroundColor(this.current === index ? '#0F766E' : '#FFFFFF')

这也是 社区寄存柜 页面保持简洁的关键。

五、布局设计与视觉层级

5.1 主容器选择

页面通常以 Column 或 Row 作为主容器。Column 适合从上到下展示流程，Row 适合左侧导航、右侧详情的结构。

Column() {
  Text('社区寄存柜')
  Blank()
  Button('主要操作')
}
.width('100%')
.height('100%')

5.2 视觉层级表

信息类型	推荐样式	在项目中的作用
标题	大字号加粗	快速识别业务
状态	主题色加粗	强调当前结果
备注	灰色中小字号	承载辅助说明
按钮	主题色背景	引导下一步操作

5.3 主题色

该项目使用 #0F766E 作为主色。主色集中出现在选中态、按钮、数字和关键状态上，让页面的操作重点更明确。

Text('关键状态')
  .fontSize(20)
  .fontWeight(FontWeight.Bold)
  .fontColor('#0F766E')

六、交互行为拆解

6.1 主要动作

1. 显示/隐藏按钮切换 hidden
2. +1 小时按钮让 hours 递增
3. 取件码根据 hidden 展示星号或真实数字

6.2 项目中的关键代码

Text(this.hidden ? '******' : '582913')
Button(this.hidden ? '显示码' : '隐藏码').onClick(() => { this.hidden = !this.hidden })
Button('+1小时').onClick(() => { this.hours += 1 })

6.3 反馈闭环

• 显示/隐藏按钮切换 hidden
• +1 小时按钮让 hours 递增
• 取件码根据 hidden 展示星号或真实数字

这些动作都在当前页面完成，不需要跳转或弹窗。对于生活服务类小工具来说，这种直接反馈是体验稳定的关键。

七、业务计算与状态推进

7.1 计算表达式

codeText = hidden ? '******' : '582913'

7.2 展示计算结果

计算结果可以直接展示在 Text 中：

Text('当前结果：' + String(result))
  .fontSize(24)
  .fontWeight(FontWeight.Bold)
  .fontColor('#0F766E')

7.3 边界条件

如果是流程推进类操作，需要控制最大值：

if (this.current < max) {
  this.current += 1
}

如果是布尔确认类操作，则要避免重复逻辑产生歧义：

this.confirmed = true

八、ArkTS 组件细节

8.1 Text 组件

Text 负责承载标题、说明、状态、金额和提醒。它是这类业务页面中出现最多的组件。

Text('社区寄存柜')
  .fontSize(26)
  .fontWeight(FontWeight.Bold)

8.2 Button 组件

Button 与业务动作直接绑定。按钮文字应描述结果，而不是描述内部实现。

Button('确认')
  .backgroundColor('#0F766E')
  .onClick(() => {
    this.done = true
  })

8.3 条件样式

条件样式让用户看出当前项、完成项和待处理项：

.fontColor(this.current === index ? '#FFFFFF' : '#0F766E')
.backgroundColor(this.current === index ? '#0F766E' : '#FFFFFF')

8.4 图形与示意区域

Stack、Circle、Rect 可以构造图形区域、照片区域、取件码区域或视觉焦点。

Stack() {
  Rect().width('100%').height(220).fill('#F8FAFC')
  Text('业务卡片')
}

九、代码可维护性

9.1 状态与静态数据分离

社区寄存柜 将变化字段放在 @State 中，将静态选项放在 private 数组中。这是非常清楚的职责分离。

9.2 业务命名清晰

字段名 box、hours、hidden 都能直接对应业务含义。后续排查点击问题时，可以很快定位到更新逻辑。

9.3 拆分 Builder 的时机

当列表项、卡片或状态节点变复杂时，可以抽出 builder 方法：

@Builder
private StatusCard(title: string, active: boolean) {
  Text(title)
    .fontColor(active ? '#FFFFFF' : '#0F766E')
}

十、调试方法

10.1 点击路径验证

调试时按以下路径走一遍：

1. 初始页面是否显示默认状态。
2. 点击选项后高亮是否变化。
3. 按钮点击后数值或文案是否更新。
4. 到达边界后是否保持稳定。

10.2 日志输出

Button('调试动作')
  .onClick(() => {
    console.info('state changed')
  })

10.3 常见问题

问题	可能原因	解决方式
列表点击无效	onClick 没有更新状态	检查赋值字段
高亮不跟随	条件判断字段错误	对齐 index 与状态
数字不变化	Text 未读取 @State	改为读取状态字段
状态越界	缺少最大值判断	增加 if 限制

十一、业务扩展设计

11.1 本地缓存

社区寄存柜 可以将当前选择和操作结果保存到本地，方便下次继续处理。

interface Snapshot {
  selected: number
  updatedAt: string
}

11.2 服务端同步

接入服务端后，可以把状态字段作为订单、工单或预约记录的一部分。

{
  "business": "社区寄存柜",
  "stateFields": "box、hours、hidden",
  "theme": "社区寄存"
}

11.3 历史记录

对于服务类应用，历史记录可以帮助用户查看上一次预约、上一次费用和当前处理进度。

十二、体验优化

12.1 减少误触

移动端操作时，列表项和按钮应保持足够高度，尤其是外勤、门店、社区服务场景。

12.2 提升可读性

关键数字、状态和当前选择要用加粗或主题色强调，辅助说明使用较浅颜色。

12.3 保持反馈一致

同一页面中，选中态、确认态和按钮主色最好保持一致，降低用户理解成本。

十三、完整实现片段

13.1 状态骨架

@Entry
@Component
struct Index {
  @State box: number = 6; // 当前柜号，默认 6 号柜
  @State hours: number = 4; // 寄存小时数，默认 4 小时
  @State hidden: boolean = true; // 取件码是否隐藏
}

13.2 数据配置

// 无数组字段：页面围绕柜号、取件码和寄存时长构成单条寄存记录
private primaryColor: string = '#0F766E'

13.3 交互代码

Text(this.hidden ? '******' : '582913')
Button(this.hidden ? '显示码' : '隐藏码').onClick(() => { this.hidden = !this.hidden })
Button('+1小时').onClick(() => { this.hours += 1 })

13.4 样式示例

Text('业务状态')
  .fontSize(18)
  .fontWeight(FontWeight.Bold)
  .fontColor('#0F766E')

十四、同类页面复用价值

14.1 可以复用的模式

• number 状态表示当前选项或流程节点。
• boolean 状态表示确认、在线、上传、显示隐藏等二值状态。
• 数组字段承载固定业务清单。
• 按钮事件只做一个明确状态变化。

14.2 可以迁移的场景

社区寄存柜 的写法可以迁移到门店预约、社区登记、上门服务、租借寄存、维修售后等多种页面。

14.3 工程化升级方向

当页面数量增多时，可以抽出主题色、卡片样式、状态节点和列表项组件，让不同业务保持统一体验。

十五、学习价值

15.1 对 ArkTS 初学者

这个项目适合练习 @State、ForEach、条件表达式和 onClick 事件。

15.2 对业务开发者

它展示了如何把一个真实服务流程拆成状态、数组和动作，而不是只停留在静态页面。

15.3 对后续项目

理解 社区寄存柜 后，再做预约、工单、订单、清单、计费页面时，会更容易设计清楚的数据流。

总结

Community Storage Box 用简洁的 ArkTS 页面完成了 社区寄存 场景的核心功能。它把 box、hours、hidden 作为响应式状态，把 无数组字段：页面围绕柜号、取件码和寄存时长构成单条寄存记录 作为业务数据来源，再通过按钮、列表和条件样式组成完整交互。

从这个项目可以学到，鸿蒙应用开发并不一定从复杂架构开始。只要把业务对象、当前状态、用户动作、反馈结果四件事写清楚，一个小页面也能具备很好的可读性和扩展性。
、

相关链接：

• HarmonyOS 应用开发指南
• ArkTS 快速入门
• ArkUI 声明式开发