鸿蒙 ArkTS 实战：NFC Access Memo 从标签备忘到保存闭环完整解析

前言

NFC Access Memo 是一个面向 NFC 门禁备忘 的鸿蒙 ArkTS 单页工具。它用列表、统计卡片、权限提示开关和状态切换，把一个具体系统能力场景整理成可操作的移动端工作台。

项目服务于 记录门禁 NFC 标签、使用位置、提醒时间和权限说明。对 办公用户、物业人员、园区访客 来说，核心价值是把分散的现场信息收束为可记录、可统计、可切换状态的条目。

业务痛点：门禁标签和位置说明如果只靠记忆，很容易在临时出入、访客授权或车库入口场景下混乱。

图示说明：本文围绕 NFC Access Memo 的数据模型、统计卡片、权限提示和列表状态切换进行拆解。

一、业务定位与产品目标

1.1 使用场景

把 NFC 标签、位置备注、提醒和保存状态集中成列表，便于用户快速查找和复用门禁信息。 当前项目虽然没有直接调用真实硬件 API，但页面结构已经把业务记录、权限提示和状态反馈组织清楚，适合作为系统能力类应用的前端雏形。

1.2 页面能力概览

当前页面可以拆成四个区域：

1. 顶部标题，明确工具的系统能力场景。

2. 统计卡片，展示 Tags 与 Saved。

3. 功能标签，提示具体能力边界。

4. 表单与列表，完成新增、备注展示和状态切换。

页面区域	代码元素	业务作用
标题区	Text	标识NFC 门禁备忘
统计区	totalAmount / savedCount	统计NFC 标签和保存进度
标签区	四个能力标签	明确功能范围
列表区	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 负责应用入口。系统能力类工具后续接入权限和硬件 API 时，仍然需要从这个入口模型开始组织。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true
      }
    ]
  },
  "topic": "NFC 门禁备忘"
}

三、数据模型：条目记录的最小闭环

3.1 字段设计

DraftItem 使用 title、amount、note、saved 四个字段描述一条记录。它把对象名称、数量口径、备注上下文和状态开关收束在同一个模型中。

interface DraftItem {
  title: string;
  amount: number;
  note: string;
  saved: boolean;
}

@State items: DraftItem[] = [
  { title: 'Office east gate', amount: 1, note: 'Permission note saved', saved: false },
  { title: 'Garage entrance', amount: 1, note: 'Reminder 08:30', saved: false }
];

3.2 默认数据分析

默认数据不是空白占位，而是直接体现项目的核心使用场景。

默认标题	数量	备注	Saved
Office east gate	1	Permission note saved	false
Garage entrance	1	Reminder 08:30	false

这两条记录分别触达 标签备注、门禁位置、使用提醒 和 权限指引，让页面首次打开时就能表达业务语义。

四、状态管理：输入与权限提示

4.1 页面状态字段

页面使用 @State 管理输入框、helperOn 开关和状态文案。开关在界面中显示为 Helper，用于表达权限或辅助提示。

@State titleText: string = '';
@State amountText: string = '';
@State noteText: string = '';
@State helperOn: boolean = true;
@State status: string = 'Assistant workspace ready';

4.2 输入与正式记录分离

标题、数量和备注先保存在输入状态中，只有点击按钮并通过校验后才会写入列表。

关键点：系统能力类工具更需要明确的权限提示和状态反馈，否则用户很难理解当前记录是否已经进入可用状态。

五、统计逻辑：总量与状态数

5.1 总量统计

totalAmount() 遍历 items，把每条记录的 amount 相加，形成顶部 Tags 指标。

5.2 状态统计

savedCount() 统计 saved 为 true 的条目数量，并以 状态数/总数 的形式展示。

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

private savedCount(): number {
  let count = 0;
  this.items.forEach((item: DraftItem) => {
    if (item.saved) {
      count++;
    }
  });
  return count;
}

函数	统计来源	页面位置	业务意义
totalAmount	amount	Tags	掌握NFC 标签规模
savedCount	saved	Saved	掌握保存状态
toggleSaved	index	列表勾选	更新单条记录状态

六、新增记录流程

6.1 校验规则

新增时先把数量转换为数字，再校验标题是否为空、数量是否有效。无效输入不会写入列表。

6.2 顶部插入策略

新记录会插入到列表顶部，并清空输入框。这样最新记录总在最容易看到的位置。

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

七、状态切换与刷新机制

7.1 切换逻辑

勾选列表项时，toggleSaved() 会反转 saved 字段，并通过数组展开触发界面刷新。

private toggleSaved(index: number): void {
  this.items[index].saved = !this.items[index].saved;
  this.items = [...this.items];
}

7.2 视觉反馈

状态开启后的记录使用浅绿色背景，未开启记录保持白色。颜色反馈能让用户快速扫出当前状态。

状态	背景色	用户感知
未开启	#FFFFFF	仍需处理或确认
已开启	#DCFCE7	已进入保存状态
输入异常	状态文案	需要修正标题或数量

八、统计卡片与能力标签

8.1 顶部统计卡片

顶部双卡片分别展示业务总量和状态数量。颜色区分能降低移动端扫描成本。

Row({ space: 10 }) {
  Column({ space: 4 }) {
    Text('Tags').fontSize(13).fontColor('#475569')
    Text(String(this.totalAmount())).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#7C3AED')
  }.layoutWeight(1).padding(14).backgroundColor('#EDE9FE').borderRadius(8)
  Column({ space: 4 }) {
    Text('Saved').fontSize(13).fontColor('#475569')
    Text(this.savedCount() + '/' + this.items.length).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#047857')
  }.layoutWeight(1).padding(14).backgroundColor('#D1FAE5').borderRadius(8)
}

8.2 功能标签解读

四个标签分别是 NFC tag note、Access location、Use reminder、Permission guide，它们概括了当前工具的关键能力。

• 标签备注：确认记录对象。

• 门禁位置：表达系统能力或使用位置。

• 使用提醒：补充提醒、参数或管理能力。

• 权限指引：形成可复用的操作依据。

九、表单与列表渲染

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 item')
    .height(42)
    .width('100%')
    .onClick(() => this.addItem())
}

9.2 列表区域

列表使用 ForEach 渲染，每行包含状态勾选、标题、备注和数量。

ForEach(this.items, (item: DraftItem, index: number) => {
  Row() {
    Toggle({ type: ToggleType.Checkbox, isOn: item.saved })
      .onChange(() => this.toggleSaved(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('#7C3AED')
  }.padding(14)
   .backgroundColor(item.saved ? '#DCFCE7' : '#FFFFFF')
   .borderRadius(8)
   .width('100%')
})

十、业务流程复盘

10.1 标准路径

NFC Access Memo 的一次完整使用可以拆成四步：

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 PersistedSystemItem {
  id: string;
  title: string;
  amount: number;
  note: string;
  saved: boolean;
  updatedAt: number;
}

11.2 系统能力扩展

后续可以加入 NFC 读取、到点提醒、权限说明模板和标签分类。

扩展顺序建议为：

1. 增加本地持久化，保证记录不丢失。

2. 接入对应系统能力或硬件 API。

3. 增加权限说明、历史搜索和导出能力。

十二、调试与验证

12.1 核心验证点

验证时重点检查新增、统计、状态切换、背景变化和错误提示。

12.2 运行检查

可以在 DevEco Studio 中运行预览或真机，按输入、状态切换、复盘路径逐项验证。

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

验证项	预期结果	业务意义
有效新增	列表顶部出现新记录	快速沉淀现场信息
空标题	显示错误状态	避免无效记录
勾选状态	统计和背景同步变化	明确当前状态
空备注	写入 No note yet	保持列表可读

十三、可复用的系统工具模式

13.1 通用公式

这类工具可以抽象为一个通用公式：对象名称、数量口径、上下文备注、状态开关。

对象名称 + 数量口径 + 上下文备注 + 状态开关 = 可复用的系统能力工作台

13.2 复用边界

复用时不能只改标题，还要同步调整默认数据、统计文案、能力标签和业务说明，否则页面会失去真实场景感。

总结

NFC Access Memo 用简洁的 ArkTS 单页结构实现了 NFC 门禁备忘 的记录、统计、权限提示和状态切换闭环。它为后续接入真实系统能力提供了清晰的页面基础。

对 办公用户、物业人员、园区访客 来说，这种工具能降低现场记录和状态确认成本。补齐持久化、权限和系统 API 后，可以继续演进成更完整的业务工具。

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

---

相关资源：

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