鸿蒙 ArkTS 实战：老人用药记录的余药天数、补药提醒与启停状态设计

前言

老人用药记录是一个基于 ArkTS 和 ArkUI 声明式 UI 的鸿蒙示例项目，入口页面集中在 entry/src/main/ets/pages/Index.ets。
本文结合 家庭用药管理 场景，拆解当前代码中的状态字段、计算函数、滑块输入、按钮切换和结果展示。
文章严格围绕项目已经实现的内容展开，代码里出现的能力会展开分析，代码里尚未出现的能力不会描述成已经完成。
这类单页工具非常适合学习鸿蒙应用开发，因为它把数据输入、业务计算和 UI 刷新放在一个清晰闭环里。

图示：在 DevEco Studio 中查看 老人用药记录 项目，可以从页面入口、状态字段和计算函数三个层面理解实现。

一、项目定位与实现边界

1.1 业务场景

老人用药记录面向 家庭用药管理，项目价值在于把日常生活里的计算问题转成可交互页面。
用户不需要理解底层公式，只需要调整几个输入项，就能看到清晰的结果反馈。
从技术角度看，这种项目能很好地展示 ArkTS 状态字段和 ArkUI 组件之间的绑定关系。

1.2 当前代码范围

当前实现已经包含多个 @State 字段、业务计算函数、滑块输入、按钮切换和结果文本。
它是一个完整的首屏工具，而不是只有静态文案的展示页。

1.3 阅读路线

阅读代码时可以按三层展开：先看状态字段代表什么，再看函数如何计算，最后看 UI 如何显示结果。
这种路线能让页面逻辑从上到下保持清楚。

维度	当前表现	阅读重点
业务主题	老人用药记录	围绕 家庭用药管理 理解页面
入口组件	Index	关注装饰器和 build 函数
状态机制	@State	观察字段变化如何刷新 UI
验证方式	操作首屏	查看结果文本与状态反馈

二、工程入口解析

2.1 入口装饰器

@Entry 说明 Index 是页面入口，@Component 说明它是可以被 ArkUI 渲染的声明式组件。
入口明确后，所有首屏状态、函数和交互都可以在同一个文件中定位。

2.2 页面构建函数

build() 函数负责描述页面结构。
当前页面通过 Column、Row、Text、Slider 和 Button 组织出输入区域与结果区域。

2.3 资源与样式

样式通过字号、字重、背景色、边距和圆角呈现。
这些视觉属性虽然不直接影响计算，但会影响用户是否能快速理解页面重点。

三、状态字段设计

3.1 字段清单

当前页面的关键状态字段如下：

• pillsLeft：参与 老人用药记录 的输入、计算或展示。
• dosesPerDay：参与 老人用药记录 的输入、计算或展示。
• daysOfSupply：参与 老人用药记录 的输入、计算或展示。
• remindBefore：参与 老人用药记录 的输入、计算或展示。
• active：参与 老人用药记录 的输入、计算或展示。
  状态字段就是这个页面的数据模型，也是调试时最先需要观察的对象。

3.2 响应式刷新

当滑块或按钮修改 @State 字段后，绑定这些字段的 UI 会自动重新渲染。
这种响应式刷新让开发者不需要手动查找文本节点再改值。

3.3 命名与语义

状态命名和业务语义保持一致，会让维护成本明显降低。
在 老人用药记录 中，字段名直接对应用户输入项或结果计算项，阅读体验比较直接。

状态类别	代表字段	页面作用
主输入	pillsLeft	影响核心计算
数值输入	Slider 绑定字段	接收用户调整
布尔状态	按钮切换字段	控制可选费用或记录状态
派生结果	函数返回值	输出最终结果

四、核心计算与业务表达

4.1 计算规则

• daysRemain 在每日剂量大于 0 时使用剩余药片除以每日剂量，并向下取整。
• refillSoon 读取余药天数，并与提前提醒阈值比较。
• active 用布尔状态表达当前记录处于服药中还是暂停记录。
• Slider 的最小值和最大值约束了药片、剂量、备药和提醒范围。
  这些规则把页面从输入表单推进到真正的业务工具。

4.2 边界处理

边界处理决定工具是否可信。
每日剂量设置了最小值 1，同时函数中仍保留 dosesPerDay <= 0 判断，避免余药天数计算异常。

4.3 结果解释

结果解释需要贴近用户语言。
老人用药记录不是为了展示公式本身，而是为了让用户快速知道当前输入对应什么结果。

五、布局结构拆解

5.1 根容器

根容器使用宽高百分比占满屏幕，为首屏展示提供稳定基础。
在移动端页面中，根容器是否铺满会直接影响内容的视觉完整性。

5.2 内容分区

内容区域按照信息优先级组织：主结果靠前，输入项集中在卡片中，辅助结果放在下方。
这种结构适合生活工具类应用，用户能先看到结论，再调整参数。

5.3 尺寸约束

尺寸约束能减少页面刷新时的跳动。
滑块、按钮、结果文本和卡片保持稳定尺寸，交互体验会更自然。

1. 先确认根容器铺满屏幕。
2. 再确认主结果在首屏有足够权重。
3. 最后检查输入卡片和按钮是否易于操作。

六、交互链路分析

6.1 用户动作

用户动作主要来自滑块拖动和按钮点击。
滑块负责修改数值型状态，按钮负责切换布尔型状态。

6.2 事件回调

事件回调保持短小，基本都是 Math.round 后赋值，或对布尔字段取反。
这种写法便于调试，也能减少事件函数里混入过多业务分支。

6.3 界面更新

界面更新来自状态绑定和函数重新计算。
当输入变化后，顶部结果、说明文案和辅助结果会跟着刷新。

七、代码片段精读

7.1 状态入口

@State pillsLeft: number = 36
@State dosesPerDay: number = 3
@State daysOfSupply: number = 12
@State remindBefore: number = 3
@State active: boolean = true

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

daysRemain(): number {
  if (this.dosesPerDay <= 0) {
    return 0
  }
  return Math.floor(this.pillsLeft / this.dosesPerDay)
}

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

7.2 函数规则

refillSoon(): string {
  const left = this.daysRemain()
  if (left <= this.remindBefore) {
    return '需要补药'
  }
  return '状态正常'
}

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

Slider({ value: this.pillsLeft, min: 0, max: 180, step: 1 })
  .onChange((v: number) => {
    this.pillsLeft = Math.round(v)
  })

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

7.3 输入控件

Slider({ value: this.dosesPerDay, min: 1, max: 6, step: 1 })
  .onChange((v: number) => {
    this.dosesPerDay = Math.round(v)
  })

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

Button(this.active ? '服药中' : '暂停记录')
  .height(44)
  .width('100%')
  .onClick(() => {
    this.active = !this.active
  })

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

7.4 展示反馈

Text(this.daysRemain().toString() + '天')
  .fontSize(32)
  .fontWeight(FontWeight.Bold)
  .fontColor('#FFFFFF')
  .backgroundColor('#DC2626')

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

{
  "scenario": "senior medication log",
  "entry": "pages/Index",
  "calculation": "remaining days"
}

这段代码对应页面中的一个清晰职责：状态入口、计算规则、输入控件或结果展示。

八、视觉层次与用户感知

8.1 主信息

主信息应当是用户打开页面后最先看到的内容。
在 老人用药记录 中，主信息就是当前计算结果或当前提醒状态。

8.2 辅助信息

辅助信息用于解释主结果，比如状态提示、押金分摊或参数标签。
辅助信息不需要过度强调，保持清晰可读即可。

8.3 颜色职责

强调色可以围绕 #DC2626 组织，用于结果、按钮和关键状态。
颜色要承担语义职责，帮助用户区分重要信息和普通说明。

九、运行调试流程

9.1 环境确认

运行前需要确认 DevEco Studio、SDK、模拟器或真机连接正常。
工程编译通过后，再进入页面验证初始状态和交互反馈。

9.2 首屏验证

首屏验证包括：默认数值是否显示、滑块是否可拖动、按钮是否切换、结果是否同步变化。
这些动作都能直接证明状态驱动链路是否完整。

9.3 异常定位

异常定位可以先查事件，再查状态，最后查 UI 绑定。
如果事件触发但结果不变，通常需要检查计算函数是否引用了正确字段。

验证步骤	操作	观察点
1	打开工程	入口文件是否存在
2	运行页面	默认结果是否正常
3	调整滑块	结果是否实时变化
4	点击按钮	布尔状态是否切换

十、扩展结构设计

10.1 组件拆分

组件拆分可以从滑块输入行开始。
当多个输入项结构相似时，抽成复用组件能显著减少重复代码。

10.2 数据保存

数据保存能提升真实使用价值。
老人用药记录可以保存上一次输入、默认配置和历史记录，让用户下次打开时继续使用。

10.3 多页面演进

多页面演进可以围绕记录、设置和详情展开。
首屏保持核心计算，其他页面承载历史数据和规则配置。

• 输入项相似时适合抽成复用组件。
• 结果说明复杂时适合拆成独立展示区。
• 历史记录增加后适合引入本地存储。
• 设置项变多后适合拆出单独页面。

十一、工程质量复盘

11.1 稳定性

稳定性来自输入范围、计算兜底和明确反馈。
当前滑块都设置了合理范围，核心函数也对关键边界做了处理。

11.2 可维护性

可维护性来自函数边界。
把计算逻辑放在独立函数里，能让 UI 组件树更专注于展示。

11.3 体验一致性

体验一致性来自统一的控件节奏。
同类输入都使用滑块，同类切换都使用按钮，用户理解成本会降低。

单页工具的核心不是页面有多少控件，而是输入变化之后是否能得到清楚、可靠、可解释的结果。

ArkTS 的状态驱动写法，让业务公式和界面反馈之间形成了很短的路径。

十二、同类项目迁移方法

12.1 复用结构

同类项目可以复用当前单页结构。
保留入口、状态、计算、输入卡片和结果展示，再替换业务字段即可快速形成新工具。

12.2 替换业务字段

替换字段时要同步替换文案、函数和范围。
业务词汇、输入单位和结果解释必须保持一致，否则页面会显得割裂。

12.3 保持反馈闭环

反馈闭环是迁移时最应该保留的部分。
用户每次操作之后，都应该看到明确结果变化。

十三、总结

13.1 技术收获

老人用药记录展示了鸿蒙单页工具的完整开发路径：状态定义、输入控制、函数计算和 UI 展示。
这个路径虽然不复杂，但非常适合沉淀可复用的页面开发方法。

13.2 实践价值

实践价值在于真实可运行。
读者可以打开项目，直接对照滑块、按钮和结果文本理解代码。

13.3 工程落点

工程落点是继续保持当前结构的清晰度。

---

相关链接：

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