鸿蒙 ArkTS 实战：Coffee Brew Timer 从咖啡萃取计时到咖啡冲煮应用完整解析

前言

咖啡萃取计时 是一个典型的鸿蒙 ArkTS 单页工具应用。它围绕“根据水量和咖啡粉克数计算粉水比，并按闷蒸、注水、等待、完成推进萃取阶段。”这个真实需求，把参数输入、业务公式、状态反馈和结果展示集中在一个页面中。

本文直接基于 Coffee Brew Timer 的源码展开，重点分析@State 状态建模、Slider 参数输入、Toggle 开关状态、ForEach 列表渲染、方法封装公式和条件样式反馈。

工具类页面最重要的是让用户知道：输入从哪里来，公式怎么算，结果为什么可信。

图示说明：本文拆解的页面包含标题摘要区、核心结果区、参数控制区和业务说明区，适合用来学习 ArkTS 声明式 UI 的数据流。

一、项目场景

1.1 业务目标

根据水量和咖啡粉克数计算粉水比，并按闷蒸、注水、等待、完成推进萃取阶段。

1.2 用户路径

1. 打开页面后先查看默认参数。
2. 通过滑杆、按钮、开关或列表调整输入。
3. 页面立刻根据状态重新计算结果。
4. 用户根据结果完成分摊、记录、估算或决策。

1.3 技术目标

二、页面入口

2.1 组件骨架

@Entry@Componentstruct Index{build(){Column(){Text('咖啡萃取计时')}}}

2.2 单页结构价值

咖啡萃取计时 的主要状态是 seconds、waterMl、coffeeG、phase。这些字段全部参与页面展示或公式计算，集中在一个组件中，能够让数据流保持足够直观。

2.3 页面分区

三、状态建模

3.1 State 字段

3.2 状态声明

@Entry@Componentstruct Index{@Stateseconds:number=30;// 当前阶段秒数，默认 30 秒@StatewaterMl:number=240;// 水量，默认 240ml@StatecoffeeG:number=15;// 咖啡粉，默认 15g@Statephase:string='闷蒸';// 当前阶段，默认闷蒸}

3.3 状态边界

这些字段都贴近业务语义。数值字段用于计算，布尔字段用于开关或模式，字符串字段用于阶段展示，索引字段用于列表选择。

状态字段不是越多越好，而是要刚好覆盖用户能够改变的内容。

四、业务数据

4.1 静态配置

无数组字段：页面围绕粉水比和阶段推进完成萃取计时

4.2 ForEach 渲染

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

4.3 选中态表达

.backgroundColor(this.selected===index?'#92400E':'#FFFFFF').fontColor(this.selected===index?'#FFFFFF':'#92400E')

通过索引把列表、详情和颜色绑定起来，是小型工具页面保持简洁的关键。

五、输入控件

5.1 Slider 数值输入

Slider 适合调节金额、人数、体重、页数、天数、温度、月份等连续或阶梯参数。

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

5.2 Toggle 开关

Toggle 适合雨天、手气模式、开关模式等二值状态。

Toggle({type:ToggleType.Switch,isOn:this.enabled}).onChange((on:boolean)=>{this.enabled=on})

5.3 Button 动作

Button 用于完成一项、重置、下一阶段、保存记录等离散动作。

Button('执行').backgroundColor('#92400E').onClick(()=>{this.count+=1})

六、交互行为

6.1 动作列表

1. Slider 调整 waterMl
2. Slider 调整 coffeeG
3. ratio 方法计算粉水比
4. 下一阶段按钮调用 nextPhase 并增加 30 秒

6.2 关键源码

ratio():number{returnMath.round(this.waterMl/this.coffeeG)}nextPhase():void{this.phase=this.phase==='闷蒸'?'注水':this.phase==='注水'?'等待':'完成'this.seconds+=30}

6.3 反馈闭环

• Slider 调整 waterMl
• Slider 调整 coffeeG
• ratio 方法计算粉水比
• 下一阶段按钮调用 nextPhase 并增加 30 秒

这些动作共同形成一个闭环：用户改变输入，状态字段更新，公式重新计算，界面立刻反馈结果。

七、公式解析

7.1 核心公式

ratio=round(waterMl/coffeeG);next phase:闷蒸->注水->等待->完成

7.2 方法封装

当公式涉及多步计算、条件分支或循环时，封装成方法能让 build 方法更干净。

privatecalc():number{returnMath.round(1)}

7.3 结果渲染

Text('结果：'+String(value)).fontSize(40).fontWeight(FontWeight.Bold).fontColor('#92400E')

结果旁边要保留单位，例如元、kg、ml、页、天、周、mmHg 或月，避免用户误读。

八、视觉设计

8.1 大数字呈现

咖啡萃取计时 的结果区域适合使用大数字，让用户在第一眼就看到当前计算值。

8.2 图形容器

Stack、Circle、Rect 可以强化仪表盘感。

Stack(){Circle().width(200).height(200).fill('#F8FAFC')Text('核心结果')}

8.3 条件颜色

.fontColor(this.warning?'#DC2626':'#92400E')

8.4 文案提示

Text(this.done?'已完成':'待处理')

条件文案能把公式结果翻译成用户更容易理解的状态。

九、布局策略

9.1 左右结构

左右结构适合左侧展示核心结果，右侧展示参数控制。

9.2 上下结构

上下结构适合先看标题和结果，再逐项调整参数。

9.3 信息层级

十、调试路径

10.1 手动验证

1. 检查默认状态是否与源码一致。
2. 调整每个 Slider、Toggle 或 Button。
3. 确认公式结果即时刷新。
4. 测试边界值和分支逻辑。

10.2 日志辅助

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

10.3 问题定位

十一、工程扩展

11.1 历史记录

可以保存每次分摊、记录、计算或估值结果，方便后续复盘。

interfaceHistoryItem{title:stringinput:stringresult:stringcreatedAt:string}

11.2 本地缓存

工具类页面常会重复使用同一组参数，把最近一次状态保存下来可以提升效率。

11.3 分享结果

{"tool":"咖啡萃取计时","state":"seconds、waterMl、coffeeG、phase","result":"calculated"}

十二、体验优化

12.1 单位清晰

金额、百分比、公斤、毫升、页数、天数、周数、血压和月份都要紧跟结果展示。

12.2 范围合理

Slider 的最小值、最大值和步长要贴近真实场景，过宽会降低调整效率。

12.3 反馈直接

输入变化后，结果应立即刷新；用户不需要额外点击提交才能看到计算结果。

十三、完整片段

13.1 状态骨架

@Entry@Componentstruct Index{@Stateseconds:number=30;// 当前阶段秒数，默认 30 秒@StatewaterMl:number=240;// 水量，默认 240ml@StatecoffeeG:number=15;// 咖啡粉，默认 15g@Statephase:string='闷蒸';// 当前阶段，默认闷蒸}

13.2 数据配置

// 无数组字段：页面围绕粉水比和阶段推进完成萃取计时privateprimaryColor:string='#92400E'

13.3 交互代码

ratio():number{returnMath.round(this.waterMl/this.coffeeG)}nextPhase():void{this.phase=this.phase==='闷蒸'?'注水':this.phase==='注水'?'等待':'完成'this.seconds+=30}

13.4 样式代码

Text('核心结果').fontSize(28).fontWeight(FontWeight.Bold).fontColor('#92400E')

十四、复用价值

14.1 状态复用

• number 用于金额、体重、时间、页数和月份。
• boolean 用于模式开关和条件判断。
• string 用于阶段状态。
• 数组用于 SKU、数量和固定选项。

14.2 公式复用

咖啡萃取计时 的公式写法可以迁移到更多分摊、估算、统计、进度和记录页面。

14.3 组件复用

结果卡片、参数滑杆、列表项、状态标签和说明文案都可以抽成通用组件。

十五、发布级拆解

15.1 场景先行

文章开头先说清楚 咖啡萃取计时 解决什么问题，再进入 ArkTS 代码，读者更容易理解公式意义。

15.2 状态为线索

围绕 seconds、waterMl、coffeeG、phase 展开讲解，可以把页面输入、计算和结果串起来。

15.3 公式落地

公式ratio = round(waterMl / coffeeG); next phase: 闷蒸 -> 注水 -> 等待 -> 完成是本项目的核心技术点，应同时解释输入来源、计算过程和输出展示。

十六、总结

Coffee Brew Timer 用简洁的 ArkTS 页面完成了 咖啡冲煮 场景。它围绕 seconds、waterMl、coffeeG、phase 建模，结合 无数组字段：页面围绕粉水比和阶段推进完成萃取计时 组织输入，并通过ratio = round(waterMl / coffeeG); next phase: 闷蒸 -> 注水 -> 等待 -> 完成把业务规则转换成即时可见的结果。

这类鸿蒙小工具的关键在于：状态清楚、公式透明、反馈及时、边界稳定。理解这个项目后，再开发小费分摊、健康趋势、仓储清单、冲煮计时、天气建议、红包分配、阅读进度、孕周估算、血压记录或资产折旧页面都会更顺手。

相关资源：

• HarmonyOS 开发者官网
• ArkTS 语言指南
• ArkUI 开发框架