鸿蒙 ArkTS 实战：Free Shipping Cart Calc 从免运费购物车到购物结算应用完整解析

前言

免运费购物车 是一个典型的鸿蒙 ArkTS 轻量工具页面。它围绕“通过购物车金额、免运费门槛和优惠券金额计算实付结果与还差多少满免门槛。”这个明确需求，把参数输入、公式计算、状态反馈和结果展示集中在一个页面中。

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

小工具的体验重点不是功能堆叠，而是输入变化后结果能被立刻理解。

图示说明：页面由标题摘要、结果展示、参数控制和说明文案组成，适合学习 ArkTS 声明式 UI 的状态流。

一、项目场景

1.1 业务目标

通过购物车金额、免运费门槛和优惠券金额计算实付结果与还差多少满免门槛。

1.2 用户路径

1. 打开页面查看默认参数。
2. 通过滑杆、开关、按钮或标签调整输入。
3. 页面立即根据状态重新计算结果。
4. 用户根据结果完成判断、估算或计划。

1.3 技术目标

目标	页面体现	ArkTS 实现
参数输入	金额、重量、比例、天数等	Slider / Toggle / ForEach
状态保存	当前数值和模式	@State
公式计算	到手价、体积重、心率、温度等	方法封装
结果反馈	大数字、状态文案、颜色	Text / Stack / 条件样式

二、页面入口

2.1 组件骨架

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('免运费购物车')
    }
  }
}

2.2 单页结构价值

免运费购物车 的核心状态是 cart、threshold、coupon。这些字段都直接影响计算结果或展示文案，集中在一个组件里能让数据流保持清楚。

2.3 页面分区

区域	作用	常见组件
顶部	标题和摘要结果	Row、Text
中部	大数字或列表	Stack、Circle、ForEach
底部	参数和操作	Slider、Button、Toggle

三、状态建模

3.1 State 字段

字段	类型	说明
cart	number	购物车金额，默认 128
threshold	number	免运费门槛，默认 199
coupon	number	优惠券金额，默认 20

3.2 状态声明

@Entry
@Component
struct Index {
  @State cart: number = 128; // 购物车金额，默认 128
  @State threshold: number = 199; // 免运费门槛，默认 199
  @State coupon: number = 20; // 优惠券金额，默认 20
}

3.3 状态边界

这些字段都贴近用户能够改变的业务输入。数值字段用于计算，布尔字段用于模式切换，索引字段用于固定选项。

状态设计清楚，公式才容易解释；公式清楚，页面结果才可信。

四、业务数据

4.1 静态配置

无数组字段：页面围绕购物车金额、门槛和优惠券完成结算计算

4.2 列表渲染

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

4.3 选中态表达

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

列表项、结果区和参数区通过同一组状态连接，页面读起来就不会散。

五、输入控件

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 或 Text 标签适合处理保存、切换、完成、重置等离散动作。

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

六、交互行为

6.1 动作列表

1. Slider 调整 cart
2. Slider 调整 threshold
3. Slider 调整 coupon
4. need 方法计算差额
5. pay 方法计算实付金额

6.2 关键源码

need(): number { let v: number = this.threshold - this.cart; return v > 0 ? v : 0 }
pay(): number { let v: number = this.cart - this.coupon; return v > 0 ? v : 0 }

6.3 反馈闭环

• Slider 调整 cart
• Slider 调整 threshold
• Slider 调整 coupon
• need 方法计算差额
• pay 方法计算实付金额

用户调整输入后，状态字段马上更新；状态更新后，公式和 UI 同步刷新。这就是声明式 UI 最直观的优势。

七、公式解析

7.1 核心公式

need = max(threshold - cart, 0); pay = max(cart - coupon, 0)

7.2 方法封装

当公式包含边界处理、条件判断或多项合计时，封装为方法可以让 build 方法更清晰。

private calc(): number {
  return Math.round(1)
}

7.3 结果渲染

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

结果展示必须带单位，例如元、kg、ml、百分比、天、周、Mbps、cm 或 GPA。

八、视觉设计

8.1 大数字

免运费购物车 的核心结果应该用大字号展示，让用户无需阅读大量说明就能看懂当前状态。

8.2 图形容器

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

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

8.3 条件颜色

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

8.4 文案提示

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

好的文案会把数字结果转成用户能行动的提示。

九、布局策略

9.1 上下结构

上下结构适合先展示结果，再逐项调整参数。

9.2 左右结构

左右结构适合左侧展示结果，右侧展示参数。

9.3 信息层级

层级	内容	目的
一级	核心结果	快速判断
二级	当前参数	明确来源
三级	说明文案	解释规则

十、调试路径

10.1 手动验证

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

10.2 日志辅助

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

10.3 问题定位

问题	原因	处理方式
结果不变	状态没有写回	检查 onChange
数字异常	公式缺少边界处理	增加取整或 max
文案错误	条件判断顺序不对	单独验证分支
列表错位	index 映射错误	对齐数组顺序

十一、工程扩展

11.1 历史记录

可以保存每次计算结果，形成购物、物流、运动、排班、烘焙或学习记录。

interface HistoryItem {
  title: string
  input: string
  result: string
  createdAt: string
}

11.2 本地缓存

工具页面常会反复使用同一组参数，本地缓存可以减少重复输入。

11.3 分享结果

{
  "tool": "免运费购物车",
  "state": "cart、threshold、coupon",
  "result": "calculated"
}

十二、体验优化

12.1 单位清晰

金额、体积、心率、天数、温度、年龄、账期、高度、网速和成绩都要紧跟单位展示。

12.2 范围合理

Slider 的 min、max 和 step 要贴近真实使用场景，避免调整成本过高。

12.3 反馈直接

输入变化后结果必须立即刷新，工具页面不适合把结果藏在提交动作之后。

十三、完整片段

13.1 状态骨架

@Entry
@Component
struct Index {
  @State cart: number = 128; // 购物车金额，默认 128
  @State threshold: number = 199; // 免运费门槛，默认 199
  @State coupon: number = 20; // 优惠券金额，默认 20
}

13.2 数据配置

// 无数组字段：页面围绕购物车金额、门槛和优惠券完成结算计算
private primaryColor: string = '#DC2626'

13.3 交互代码

need(): number { let v: number = this.threshold - this.cart; return v > 0 ? v : 0 }
pay(): number { let v: number = this.cart - this.coupon; return v > 0 ? v : 0 }

13.4 样式代码

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

十四、复用价值

14.1 状态复用

• number 用于金额、重量、比例、温度、速度和分数。
• boolean 用于模式开关和类型切换。
• number 索引用于训练区间、体型和课程等固定选项。

14.2 公式复用

免运费购物车 的公式写法可以迁移到更多购物、物流、运动、排班、烘焙、宠物、财务、办公和学习工具页面。

14.3 组件复用

结果卡片、参数滑杆、状态标签、单位文案都可以抽成通用组件。

十五、发布级拆解

15.1 场景先行

文章开头先说清楚 免运费购物车 解决什么问题，再进入 ArkTS 代码，读者更容易理解公式意义。

15.2 状态为线索

围绕 cart、threshold、coupon 展开讲解，可以把页面输入、计算和结果串起来。

15.3 公式落地

公式 need = max(threshold - cart, 0); pay = max(cart - coupon, 0) 是本项目的核心技术点，应同时解释输入来源、计算过程和输出展示。

十六、总结

Free Shipping Cart Calc 用简洁的 ArkTS 页面完成了 购物结算 场景。它围绕 cart、threshold、coupon 建模，结合 无数组字段：页面围绕购物车金额、门槛和优惠券完成结算计算 组织输入，并通过 need = max(threshold - cart, 0); pay = max(cart - coupon, 0) 把业务规则转换成即时可见的结果。

这类鸿蒙小工具的关键在于：状态清楚、公式透明、反馈及时、边界稳定。理解这个项目后，再开发免运费购物车、体积重、心率区间、排班、烘焙温度、宠物年龄、账期回款、桌面人体工学、测速记录或 GPA 统计页面都会更顺手。

---

相关资源：

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