鸿蒙 ArkTS 实战：Warehouse Pick List 从仓库拣货清单到仓储作业应用完整解析

前言

仓库拣货清单 是一个典型的鸿蒙 ArkTS 单页工具应用。它围绕“围绕纸箱、胶带、标签纸、气泡袋四个 SKU 展示待拣数量，并记录已完成的拣货项。”这个真实需求，把参数输入、业务公式、状态反馈和结果展示集中在一个页面中。

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

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

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

一、项目场景

1.1 业务目标

围绕纸箱、胶带、标签纸、气泡袋四个 SKU 展示待拣数量，并记录已完成的拣货项。

1.2 用户路径

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

1.3 技术目标

目标	页面体现	ArkTS 实现
参数输入	金额、体重、页数、月份等	Slider / Button
状态保存	当前数值、开关、阶段	@State
业务公式	均分、BMI、折旧、进度	方法封装
结果反馈	大数字、提示、颜色	Text / Stack / 条件样式

二、页面入口

2.1 组件骨架

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('仓库拣货清单')
    }
  }
}

2.2 单页结构价值

仓库拣货清单 的主要状态是 picked、selected。这些字段全部参与页面展示或公式计算，集中在一个组件中，能够让数据流保持足够直观。

2.3 页面分区

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

三、状态建模

3.1 State 字段

字段	类型	说明
picked	number	已完成拣货项数量，默认 1
selected	number	当前选中的 SKU 索引

3.2 状态声明

@Entry
@Component
struct Index {
  @State picked: number = 1; // 已完成拣货项数量，默认 1
  @State selected: number = 0; // 当前选中的 SKU 索引
}

3.3 状态边界

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

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

四、业务数据

4.1 静态配置

skus：A12 纸箱、B08 胶带、C21 标签纸、D03 气泡袋；nums：8、4、12、6

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 ? '#2563EB' : '#FFFFFF')
.fontColor(this.selected === index ? '#FFFFFF' : '#2563EB')

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

五、输入控件

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('#2563EB')
  .onClick(() => {
    this.count += 1
  })

六、交互行为

6.1 动作列表

1. ForEach 渲染 SKU 列表
2. 点击行切换 selected
3. 完成一项按钮在 picked 小于 4 时递增
4. 重置按钮把 picked 归零

6.2 关键源码

Button('完成一项').onClick(() => {
  if (this.picked < 4) {
    this.picked += 1
  }
})
Button('重置').onClick(() => { this.picked = 0 })

6.3 反馈闭环

• ForEach 渲染 SKU 列表
• 点击行切换 selected
• 完成一项按钮在 picked 小于 4 时递增
• 重置按钮把 picked 归零

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

七、公式解析

7.1 核心公式

progress = picked / skus.length

7.2 方法封装

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

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

7.3 结果渲染

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

结果旁边要保留单位，例如元、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' : '#2563EB')

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 问题定位

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

十一、工程扩展

11.1 历史记录

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

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

11.2 本地缓存

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

11.3 分享结果

{
  "tool": "仓库拣货清单",
  "state": "picked、selected",
  "result": "calculated"
}

十二、体验优化

12.1 单位清晰

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

12.2 范围合理

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

12.3 反馈直接

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

十三、完整片段

13.1 状态骨架

@Entry
@Component
struct Index {
  @State picked: number = 1; // 已完成拣货项数量，默认 1
  @State selected: number = 0; // 当前选中的 SKU 索引
}

13.2 数据配置

// skus：A12 纸箱、B08 胶带、C21 标签纸、D03 气泡袋；nums：8、4、12、6
private primaryColor: string = '#2563EB'

13.3 交互代码

Button('完成一项').onClick(() => {
  if (this.picked < 4) {
    this.picked += 1
  }
})
Button('重置').onClick(() => { this.picked = 0 })

13.4 样式代码

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

十四、复用价值

14.1 状态复用

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

14.2 公式复用

仓库拣货清单 的公式写法可以迁移到更多分摊、估算、统计、进度和记录页面。

14.3 组件复用

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

十五、发布级拆解

15.1 场景先行

文章开头先说清楚 仓库拣货清单 解决什么问题，再进入 ArkTS 代码，读者更容易理解公式意义。

15.2 状态为线索

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

15.3 公式落地

公式 progress = picked / skus.length 是本项目的核心技术点，应同时解释输入来源、计算过程和输出展示。

十六、总结

Warehouse Pick List 用简洁的 ArkTS 页面完成了 仓储作业 场景。它围绕 picked、selected 建模，结合 skus：A12 纸箱、B08 胶带、C21 标签纸、D03 气泡袋；nums：8、4、12、6 组织输入，并通过 progress = picked / skus.length 把业务规则转换成即时可见的结果。

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

---

相关资源：

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