鸿蒙 ArkTS 实战：Theater Rehearsal Table 从业务记录到移动工作台完整解析

前言

Theater Rehearsal Table 是一个面向 剧场排练表 的鸿蒙 ArkTS 单页应用。它的实现并不追求复杂后台，而是把一线业务里最常见的记录、数量统计、备注和完成状态放到一个移动工作台中。

项目适用于 剧组排练时管理场次、演员日程、道具清单和通知提醒。对于 舞台监督、导演助理、剧团统筹 来说，核心目标是减少临时纸条、聊天转发和表格补录，把当天任务沉淀成可追踪的列表。

业务痛点：剧场排练涉及演员、场次、道具和通知，任何一项遗漏都会直接影响排练效率。

图示说明：本文围绕 Theater Rehearsal Table 的页面状态、业务记录、统计卡片和交互闭环展开。

一、业务定位与页面目标

1.1 解决什么问题

把场次和道具备注整理成可勾选记录，舞台监督能快速确认每个排练环节的准备状态。 这类小工具的关键不是功能数量，而是把一个高频动作做短、做稳、做清楚。

1.2 页面能力概览

当前页面主要由四部分组成：

1. 顶部标题，确认工具所属业务场景。

2. 统计卡片，展示 Scenes 与 Done 完成度。

3. 业务标签，概括页面覆盖的关键环节。

4. 表单和列表，完成新增、展示、勾选和反馈。

页面区域	代码元素	业务作用
标题区	Text	标识剧场排练表场景
统计区	totalAmount / doneCount	统计排练场次与完成度
标签区	四个能力标签	提示业务范围
列表区	ForEach	承载记录闭环

二、工程结构与入口文件

2.1 目录结构

项目采用标准 Stage 工程，页面逻辑集中在 entry/src/main/ets/pages/Index.ets。这对于工具型应用很合适，定位问题时路径短，阅读代码时上下文集中。

entry/
  src/
    main/
      ets/
        entryability/
          EntryAbility.ets
        pages/
          Index.ets
      module.json5

2.2 入口配置理解

页面虽然是业务主体，但应用加载依赖模块配置和 Ability 入口。理解这个关系，可以避免只看页面代码却找不到运行入口的问题。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true
      }
    ]
  },
  "topic": "剧场排练表"
}

三、数据模型：四个字段完成闭环

3.1 记录结构

项目使用 ToolRecord 描述一条业务记录。title 表示任务主体，amount 表示数量口径，note 保存上下文，done 表示是否完成。

interface ToolRecord {
  title: string;
  amount: number;
  note: string;
  done: boolean;
}

@State records: ToolRecord[] = [
  { title: 'Act 1 rehearsal', amount: 3, note: 'Props: chair, letter', done: false },
  { title: 'Final run', amount: 1, note: 'Notice sent to cast', done: false }
];

3.2 默认记录分析

默认记录用于表达项目的真实业务方向，同时也能在首次运行时验证统计和列表渲染是否正常。

默认标题	数量	备注	完成状态
Act 1 rehearsal	3	Props: chair, letter	false
Final run	1	Notice sent to cast	false

这些默认数据分别触达 演员日程、场次计划、道具清单 和 通知提醒，不是空泛占位。

四、状态管理设计

4.1 页面状态字段

页面把 records、输入框草稿、提醒开关和状态文案都放在 @State 中。它们变化后会驱动 UI 重新渲染，适合轻量页面直接管理。

@State titleText: string = '';
@State amountText: string = '';
@State noteText: string = '';
@State notifyOn: boolean = true;
@State status: string = 'Tool workflow ready';

4.2 草稿和正式记录分离

三个输入框先写入草稿状态，只有点击新增并通过校验后才进入 records。这样可以避免用户输入一半时影响正式列表。

关键点：移动端工具越简单，越要保证数据进入列表前经过明确动作和基础校验。

五、统计逻辑：总量与完成度

5.1 总量统计

totalAmount() 遍历 records，把 amount 累加为 Scenes。它是顶部左侧卡片的数据来源。

5.2 完成统计

doneCount() 统计 done 为 true 的记录数量，并与总记录数拼接显示。这个指标能快速反映任务推进情况。

private totalAmount(): number {
  let total = 0;
  this.records.forEach((item: ToolRecord) => {
    total += item.amount;
  });
  return total;
}

private doneCount(): number {
  let count = 0;
  this.records.forEach((item: ToolRecord) => {
    if (item.done) {
      count++;
    }
  });
  return count;
}

函数	统计来源	页面表现	业务意义
totalAmount	amount	Scenes	掌握排练场次
doneCount	done	Done	掌握完成进度
toggleDone	index	背景变化	形成闭环

六、新增记录流程

6.1 输入校验

新增时先把数量转换为数字，再判断标题是否为空、数量是否有效。无效输入不会进入正式列表。

6.2 顶部插入

新增记录通过数组展开放到列表最前面，新任务优先展示，符合现场处理习惯。

private addRecord(): void {
  const amount = Number(this.amountText);
  if (this.titleText.trim().length === 0 || !Number.isFinite(amount)) {
    this.status = 'Enter title and valid number';
    return;
  }
  this.records = [{
    title: this.titleText,
    amount: Math.round(amount),
    note: this.noteText.length > 0 ? this.noteText : 'No note yet',
    done: false
  }, ...this.records];
  this.titleText = '';
  this.amountText = '';
  this.noteText = '';
  this.status = 'Record added';
}

七、完成状态与刷新机制

7.1 勾选完成

列表项通过 checkbox 触发完成状态切换。代码修改对应记录后，重新展开数组生成新引用，从而稳定触发刷新。

private toggleDone(index: number): void {
  this.records[index].done = !this.records[index].done;
  this.records = [...this.records];
}

7.2 视觉反馈

完成后的记录使用浅绿色背景，未完成记录保持白色。对于现场工具来说，颜色反馈比长文本提示更高效。

记录状态	颜色	含义
未完成	#FFFFFF	仍需处理
已完成	#DCFCE7	已形成闭环
输入异常	状态文案	需要修正输入

八、统计卡片与业务标签

8.1 顶部统计卡片

统计卡片采用左右布局：左侧表示业务总量，右侧表示完成比例。这个布局适合快速扫描。

Row({ space: 10 }) {
  Column({ space: 4 }) {
    Text('Scenes').fontSize(13).fontColor('#475569')
    Text(String(this.totalAmount())).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#1D4ED8')
  }.layoutWeight(1).padding(14).backgroundColor('#DBEAFE').borderRadius(8)
  Column({ space: 4 }) {
    Text('Done').fontSize(13).fontColor('#475569')
    Text(this.doneCount() + '/' + this.records.length).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#047857')
  }.layoutWeight(1).padding(14).backgroundColor('#D1FAE5').borderRadius(8)
}

8.2 业务标签解读

四个标签分别是 Actor schedule、Scene plan、Prop list、Notice alert。它们帮助用户快速理解工具覆盖的业务范围。

• 演员日程：确认记录对象。

• 场次计划：明确执行计划。

• 道具清单：处理异常或提醒。

• 通知提醒：保留交接依据。

九、表单与列表渲染

9.1 表单区域

表单由标题、数字、备注三个输入框组成，配合一个新增按钮完成最短路径录入。

Column({ space: 10 }) {
  TextInput({ placeholder: 'Title', text: this.titleText })
    .onChange((value: string) => this.titleText = value)
  TextInput({ placeholder: 'Number', text: this.amountText })
    .type(InputType.Number)
    .onChange((value: string) => this.amountText = value)
  TextInput({ placeholder: 'Note', text: this.noteText })
    .onChange((value: string) => this.noteText = value)
  Button('Add record')
    .height(42)
    .width('100%')
    .onClick(() => this.addRecord())
}

9.2 列表区域

列表中每条记录都包含勾选框、标题、备注和数量。信息密度较高，但每个字段都有明确位置。

ForEach(this.records, (item: ToolRecord, index: number) => {
  Row() {
    Toggle({ type: ToggleType.Checkbox, isOn: item.done })
      .onChange(() => this.toggleDone(index))
    Column({ space: 6 }) {
      Text(item.title).fontSize(18).fontWeight(FontWeight.Bold).fontColor('#111827')
      Text(item.note).fontSize(14).fontColor('#475569')
    }.layoutWeight(1).margin({ left: 8 })
    Text(String(item.amount)).fontSize(18).fontWeight(FontWeight.Bold).fontColor('#1D4ED8')
  }.padding(14)
   .backgroundColor(item.done ? '#DCFCE7' : '#FFFFFF')
   .borderRadius(8)
   .width('100%')
})

十、业务流程复盘

10.1 标准路径

Theater Rehearsal Table 的业务闭环可以拆成四步：

1. 录入排练场次。

2. 填写场次数量。

3. 记录道具或通知备注。

4. 排练完成后勾选。

10.2 异常路径

异常路径主要发生在新增动作前。标题为空或数量非法时，列表不写入新数据，而是更新状态文案。

const amount = Number(this.amountText);
const invalid = this.titleText.trim().length === 0 || !Number.isFinite(amount);
if (invalid) {
  this.status = 'Enter title and valid number';
}

十一、可扩展设计

11.1 模型拆分

当业务继续增长时，可以把记录模型拆到独立文件，并增加 id、时间戳和来源字段。

interface PersistedRecord {
  id: string;
  title: string;
  amount: number;
  note: string;
  done: boolean;
  updatedAt: number;
}

11.2 行业扩展

后续可以加入排练日历、角色分组、道具借还和通知回执。

扩展顺序可以保持为：

1. 增加本地持久化，保证数据不因关闭应用丢失。

2. 增加行业字段，让记录更贴近真实业务。

3. 增加导出、提醒或同步能力，支撑团队协作。

十二、调试与验证

12.1 核心验证点

验证时重点观察新增记录、统计变化、完成勾选和异常输入四类路径。

12.2 运行检查

可以在 DevEco Studio 中启动预览或真机运行，按业务流程逐项验证交互是否符合预期。

# 常规验证动作
# 1. 输入标题、数量和备注
# 2. 点击 Add record
# 3. 检查新记录是否位于顶部
# 4. 勾选记录并观察 Done 统计

验证项	预期结果	业务意义
有效新增	列表顶部新增记录	快速追加现场任务
空标题	显示错误状态	拦截无效数据
勾选完成	统计和背景同步变化	完成闭环明确
空备注	自动写入默认备注	记录保持完整

十三、可复用的工具应用模式

13.1 通用公式

这个项目可以抽象为一个通用模式：业务对象、数量口径、备注上下文、完成状态。很多线下管理工具都能从这个公式起步。

业务对象 + 数量口径 + 备注上下文 + 完成状态 = 可落地的移动工作台

13.2 复用时要注意什么

复用时不能只替换标题，还要同步调整默认数据、统计文案、功能标签和业务备注，否则页面会失去行业可信度。

总结

Theater Rehearsal Table 通过简洁的 ArkTS 代码，把 剧场排练表 中的高频记录动作整理成移动端工作台。它的核心价值在于让记录可新增、数量可统计、备注可追溯、状态可闭环。

对 舞台监督、导演助理、剧团统筹 来说，这种应用能够降低现场沟通成本，并把当天任务形成清晰列表。随着持久化、提醒和行业字段补齐，它可以继续扩展成更完整的业务工具。

如果这篇文章对你有帮助，可以点赞、收藏并关注，后续会继续拆解更多鸿蒙 ArkTS 实战项目。

---

相关资源：

• HarmonyOS 应用开发
• ArkTS 语言基础
• ArkUI 声明式开发
• DevEco Studio
• Stage 模型应用结构
• Ability Kit
• CSDN 写作平台