鸿蒙 ArkTS 实战：Neck Shoulder Relaxer 从健康状态到交互卡片完整解析

前言

颈肩放松助手 是一个面向 健康管理与家庭安全 的鸿蒙 ArkTS 小应用。围绕久坐分钟、放松动作和完成数量构建颈肩放松提醒。 本文基于 entry/src/main/ets/pages/Index.ets 的真实源码结构展开，重点分析 数据模型、@State 状态、业务方法、Builder 卡片 和页面布局，形成可直接发布的技术解析。

图示说明：页面以健康提醒、训练记录、家庭安全或装备维护为主题，通过卡片和按钮把状态变化呈现出来。

一、应用定位与业务闭环

1.1 场景定位

Neck Shoulder Relaxer 的核心是把一个具体健康或家庭安全场景做成可操作的单页工具。用户可以记录信息、完成动作、查看反馈，并通过列表卡片复盘历史或当前状态。

业务环节	页面表现	ArkTS 实现
数据记录	输入与卡片	@State + ForEach
动作完成	按钮点击	private 方法
状态反馈	文案和计数	派生计算
安全提醒	开关或提示文本	布尔状态
历史复盘	列表卡片	Builder 复用

1.2 文章拆解路径

1. 分析接口和状态，确认页面数据结构。
2. 分析方法，确认业务动作如何更新状态。
3. 分析 Builder，确认列表卡片如何复用。
4. 分析布局，确认页面如何承载健康信息。

实现原则：健康类工具必须让用户知道当前状态、下一步动作和操作结果，不能只展示静态文本。

二、工程结构与入口页面

2.1 文件位置

核心页面位于 entry/src/main/ets/pages/Index.ets。

Neck Shoulder Relaxer
├── AppScope
├── entry
│   └── src
│       └── main
│           ├── ets
│           │   └── pages
│           │       └── Index.ets
│           └── module.json5
├── hvigor
└── oh-package.json5

2.2 页面入口结构

@Entry
@Component
struct Index {
  build() {
    Column() {
      // 健康卡片与操作区
    }
  }
}

2.3 技术组成

技术点	作用	价值
ArkTS	类型与业务逻辑	组织健康数据
ArkUI	声明式 UI	构建卡片界面
@State	响应式状态	驱动刷新
@Builder	组件片段	复用卡片样式
Hvigor	构建系统	编译运行

三、数据模型设计

3.1 接口清单

源码中的接口包括：$iface。

interface RelaxAction {
  id: number;
  title?: string;
  name?: string;
  done?: boolean;
  note?: string;
}

接口字段对应页面中的卡片标题、动作状态、备注说明或健康指标。

3.2 字段语义

字段类型	常见字段	用途
标识字段	id	列表 key
标题字段	itle、
ame	卡片主信息
数值字段	minutes、count、mileage	统计或训练量
状态字段	done、offline、privacyLock	控制交互表现
文案字段	message、
ote、contact	输出反馈

3.3 建模价值

健康和安全类应用关注的是“记录是否完整、动作是否完成、风险是否可见”。接口建模能让这些状态在页面中稳定表达。

四、@State 状态拆解

4.1 状态清单

源码中的状态包括：$state。

@State records: RelaxAction[] = [];
@State draftText: string = '';
@State message: string = '';
@State enabled: boolean = true;

4.2 状态分类

状态类别	示例	说明
记录状态	$primaryState	保存动作或历史条目
输入状态	draft、
ameDraft、symptomDraft	接收文本
数值状态	useMinutes、screenHours、sittingMinutes	健康指标
开关状态
eminderOn、privacyLock、offline	控制功能模式
反馈状态	message、sleepNote、
eport	提示结果

4.3 状态更新方式

private updateItem(id: number): void {
  this.records = this.records.map((item: RelaxAction) => {
    return item.id === id ? { ...item, done: true } : item;
  });
}

五、核心方法解析

5.1 方法清单

源码中的核心方法包括：$method。

方法类型	作用	示例
新增方法	添加记录	ddRecord、ddGear
完成方法	标记动作完成	inish、doneAction
统计方法	计算数量或总量	otal、doneCount
反馈方法	输出报告或消息	exportReport
卡片方法	渲染列表项	card

5.2 新增记录

private addRecord(): void {
  const text = this.draftText.trim();
  if (text.length === 0) {
    return;
  }
  this.records = [{ id: Date.now(), title: text, done: false }, ...this.records];
  this.draftText = '';
}

5.3 完成动作

private finish(id: number): void {
  this.records = this.records.map((item: RelaxAction) => {
    return item.id === id ? { ...item, done: true } : item;
  });
}

5.4 统计方法

private doneCount(): number {
  return this.records.filter((item: RelaxAction) => item.done).length;
}

六、Builder 卡片复用

6.1 Builder 清单

源码中的 Builder 组件包括：$builder。

@Builder
private card(item: RelaxAction) {
  Column() {
    Text(item.title ?? item.name ?? '记录')
      .fontSize(16)
      .fontWeight(FontWeight.Bold)
  }
  .padding(14)
  .backgroundColor('#FFFFFF')
  .borderRadius(8)
}

6.2 复用价值

组件	作用
card	统一记录卡片
动作按钮	承载完成或推进动作
状态文案	显示提示结果
统计区域	展示完成数量或总量

6.3 边界控制

Builder 只负责 UI，不直接处理复杂状态逻辑。业务动作仍放在 private 方法里。

七、页面布局结构

7.1 常见布局

Scroll() {
  Column() {
    // 标题区
    // 状态区
    // 操作区
    // 卡片列表
  }
  .padding(16)
}

7.2 信息分区

区域	内容	价值
标题区	应用名称和说明	明确使用场景
状态区	当前指标和提醒	形成判断依据
操作区	输入框和按钮	记录新数据
列表区	历史或动作卡片	支持复盘
反馈区	消息和报告	确认结果

7.3 列表渲染

ForEach(this.records, (item: RelaxAction) => {
  this.card(item)
}, (item: RelaxAction) => item.id.toString())

八、交互链路

8.1 输入链路

TextInput({ text: this.draftText })
  .onChange((value: string) => {
    this.draftText = value;
  })

8.2 按钮链路

Button('记录')
  .onClick(() => {
    this.addRecord();
  })

8.3 反馈链路

private setMessage(text: string): void {
  this.message = text;
}

关键点：输入、方法、状态、UI 四个环节要单向流动，避免在 UI 片段中混入过多业务判断。

九、健康与安全场景表达

9.1 状态层级

状态	页面表达
正常	绿色或普通卡片
需要关注	橙色提示
已完成	完成文案或勾选状态
隐私保护	开关和锁定提示
离线可用	离线标识和联系人信息

9.2 数据可信度

健康记录要避免无效输入。实际扩展时应增加数字范围、必填字段和日期校验。

9.3 反馈及时性

用户完成动作后，页面应立即改变卡片状态或消息文案，减少不确定感。

十、运行与调试

10.1 DevEco Studio 运行

# 打开项目目录
# 同步依赖
# 选择 entry 模块运行

10.2 Hvigor 构建

hvigorw clean
hvigorw assembleHap

10.3 调试点

调试项	判断标准
状态变化	点击后 @State 是否更新
卡片刷新	列表是否重新渲染
输入校验	空值是否被拦截
反馈文案	消息是否更新
构建输出	HAP 是否正常生成

十一、可维护性分析

11.1 文件规模

当前 Index.ets 约 53 行，适合作为单页小工具示例。后续可以拆分卡片、输入区和统计区。

11.2 状态收敛

能计算的值不必单独保存，避免源数据和统计结果不一致。

private totalCount(): number {
  return this.records.length;
}

11.3 可测试逻辑

统计方法和状态转换方法可以单独抽离，便于后续做单元测试。

十二、扩展方向

12.1 本地存储

interface StoredHealthRecord {
  id: number;
  type: string;
  payload: string;
  updatedAt: number;
}

12.2 提醒通知

护眼、疫苗、康复、装备保养都适合增加系统提醒。

12.3 导出与分享

康复训练、疫苗记录和血压类数据可以导出为就诊记录或家庭共享清单。

十三、同类模板抽象

13.1 数据模板

interface ActionItem {
  id: number;
  title: string;
  done: boolean;
}

13.2 状态模板

@State actions: ActionItem[] = [];
@State message: string = '';

13.3 卡片模板

@Builder
private actionCard(item: ActionItem) {
  Row() {
    Text(item.title).layoutWeight(1)
    Text(item.done ? '已完成' : '待完成')
  }
  .padding(12)
}

十四、实现亮点

14.1 数据模型明确

Neck Shoulder Relaxer 使用 $iface 组织业务对象，保证列表卡片和操作方法有明确数据来源。

14.2 状态链路短

$state 直接驱动页面，交互链路清晰，调试成本低。

14.3 组件结构稳定

$builder 封装卡片或列表项，保持页面风格一致。

十五、总结

Neck Shoulder Relaxer 是一个典型的鸿蒙 ArkTS 健康与家庭安全类小工具。它通过 $iface 建模业务对象，通过 $state 保存页面状态，通过 $method 完成记录、统计、完成和反馈，再通过 $builder 渲染可复用卡片。

这类应用的重点是把小场景做闭环：记录入口要明确，状态反馈要及时，历史信息要可复盘。掌握这个结构后，可以继续扩展提醒、持久化、导出和多设备同步等能力。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！

---

相关资源：

• HarmonyOS Developer
• ArkTS 语言基础
• ArkUI 声明式开发
• DevEco Studio
• Stage 模型应用包结构
• HarmonyOS 应用开发指南