鸿蒙 ArkTS 实战：Desktop Widget Collection 从系统能力到状态管理完整解析

G_dou_

3人浏览 · 2026-07-18 17:14:54

G_dou_ · 2026-07-18 17:14:54 发布

鸿蒙 ArkTS 实战：Desktop Widget Collection 从系统能力到状态管理完整解析

前言

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

项目服务于管理天气、待办等桌面卡片的尺寸、主题和激活状态。对 桌面组件用户、效率应用开发者、产品设计师 来说，核心价值是把分散的现场信息收束为可记录、可统计、可切换状态的条目。

业务痛点：桌面卡片需要同时考虑尺寸、主题和快捷操作，配置分散会影响使用效率。

在这里插入图片描述

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

一、业务定位与产品目标

1.1 使用场景

用卡片列表管理组件名称、数量、样式备注和激活状态，适合设计桌面组件集合。当前项目虽然没有直接调用真实硬件 API，但页面结构已经把业务记录、权限提示和状态反馈组织清楚，适合作为系统能力类应用的前端雏形。

1.2 页面能力概览

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

顶部标题，明确工具的系统能力场景。
统计卡片，展示 Cards 与 Active。
功能标签，提示具体能力边界。
表单与列表，完成新增、备注展示和状态切换。

页面区域	代码元素	业务作用
标题区	Text	标识桌面卡片集合
统计区	totalAmount / activeCountValue	统计桌面卡片和激活进度
标签区	四个能力标签	明确功能范围
列表区	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": "桌面卡片集合"
}

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

3.1 字段设计

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

interface SystemItem {
  title: string;
  amount: number;
  note: string;
  active: boolean;
}

@State items: SystemItem[] = [
  { title: 'Weather card', amount: 1, note: 'Medium size', active: false },
  { title: 'Todo card', amount: 1, note: 'Dark theme', active: false }
];

3.2 默认数据分析

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

默认标题	数量	备注	Active
Weather card	1	Medium size	false
Todo card	1	Dark theme	false

这两条记录分别触达 信息卡片、快捷操作、尺寸适配 和 主题切换，让页面首次打开时就能表达业务语义。

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

4.1 页面状态字段

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

@State titleText: string = '';
@State amountText: string = '';
@State noteText: string = '';
@State permissionOn: boolean = true;
@State status: string = 'System capability demo ready';

4.2 输入与正式记录分离

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

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

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

5.1 总量统计

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

5.2 状态统计

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

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

private activeCountValue(): number {
  let count = 0;
  this.items.forEach((item: SystemItem) => {
    if (item.active) {
      count++;
    }
  });
  return count;
}

函数	统计来源	页面位置	业务意义
totalAmount	amount	Cards	掌握桌面卡片规模
activeCountValue	active	Active	掌握激活状态
toggleActive	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',
    active: false
  }, ...this.items];
  this.titleText = '';
  this.amountText = '';
  this.noteText = '';
  this.status = 'Record added';
}

七、状态切换与刷新机制

7.1 切换逻辑

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

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

7.2 视觉反馈

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

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

八、统计卡片与能力标签

8.1 顶部统计卡片

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

Row({ space: 10 }) {
  Column({ space: 4 }) {
    Text('Cards').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('Active').fontSize(13).fontColor('#475569')
    Text(this.activeCountValue() + '/' + this.items.length).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#047857')
  }.layoutWeight(1).padding(14).backgroundColor('#D1FAE5').borderRadius(8)
}

8.2 功能标签解读

四个标签分别是 Info card、Quick action、Size adapt、Theme switch，它们概括了当前工具的关键能力。

信息卡片：确认记录对象。
快捷操作：表达系统能力或使用位置。
尺寸适配：补充提醒、参数或管理能力。
主题切换：形成可复用的操作依据。

九、表单与列表渲染

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.addItem())
}

9.2 列表区域

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

ForEach(this.items, (item: SystemItem, index: number) => {
  Row() {
    Toggle({ type: ToggleType.Checkbox, isOn: item.active })
      .onChange(() => this.toggleActive(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.active ? '#DCFCE7' : '#FFFFFF')
   .borderRadius(8)
   .width('100%')
})

十、业务流程复盘

10.1 标准路径

Desktop Widget Collection 的一次完整使用可以拆成四步：

录入卡片名称。
填写卡片数量。
备注尺寸或主题。
切换启用状态。

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;
  active: boolean;
  updatedAt: number;
}

11.2 系统能力扩展

后续可以加入真实 widget 配置、尺寸预览、主题同步和快捷操作。

扩展顺序建议为：

增加本地持久化，保证记录不丢失。
接入对应系统能力或硬件 API。
增加权限说明、历史搜索和导出能力。

十二、调试与验证

12.1 核心验证点

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

12.2 运行检查

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

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

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

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

13.1 通用公式

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

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

13.2 复用边界

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

总结

Desktop Widget Collection 用简洁的 ArkTS 单页结构实现了 桌面卡片集合 的记录、统计、权限提示和状态切换闭环。它为后续接入真实系统能力提供了清晰的页面基础。

对桌面组件用户、效率应用开发者、产品设计师来说，这种工具能降低现场记录和状态确认成本。补齐持久化、权限和系统 API 后，可以继续演进成更完整的业务工具。

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

相关资源：

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙ArkUI实战：构建账户详情与流水摘要

人工智能6S服务平台

常量与不可变性实战：Flutter在鸿蒙应用中配置主题色常量

人工智能6S服务平台

鸿蒙ArkUI实战：设置每月账期起始日

人工智能6S服务平台

所有评论(0)

查看更多评论

G_dou_

@gao_dou

已为社区贡献122条内容

鸿蒙 ArkTS 实战：Desktop Widget Collection 从系统能力到状态管理完整解析

G_dou_

鸿蒙 ArkTS 实战：Desktop Widget Collection 从系统能力到状态管理完整解析

前言

一、业务定位与产品目标

1.1 使用场景

1.2 页面能力概览

二、工程结构与入口文件

2.1 目录结构

2.2 入口配置理解

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

3.1 字段设计

3.2 默认数据分析

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

4.1 页面状态字段

4.2 输入与正式记录分离

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

5.1 总量统计

5.2 状态统计

六、新增记录流程

6.1 校验规则

6.2 顶部插入策略

七、状态切换与刷新机制

7.1 切换逻辑

7.2 视觉反馈

八、统计卡片与能力标签

8.1 顶部统计卡片

8.2 功能标签解读

九、表单与列表渲染

9.1 表单区域

9.2 列表区域

十、业务流程复盘

10.1 标准路径

10.2 异常路径

十一、扩展设计

11.1 持久化模型

11.2 系统能力扩展

十二、调试与验证

12.1 核心验证点

12.2 运行检查

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

13.1 通用公式

13.2 复用边界

总结

所有评论(0)

温馨提示：您尚未绑定手机号

G_dou_