企业官网建设流程全解析

鸿蒙 ArkTS 实战：Seal Usage Record 从状态建模到办公交互完整解析

前言

印章使用记录 是一个面向行政与资产管理的鸿蒙 ArkTS 应用。记录印章使用事项、审批状态和筛选条件，适合行政用印流程。 本文基于 entry/src/main/ets/pages/Index.ets 的真实代码结构展开，重点分析interface 数据模型、@State 状态、业务方法、Builder 组件和页面布局，形成一篇可直接发布的技术解析。

图示说明：页面以办公场景为核心，通过卡片、输入框、筛选按钮、统计信息和状态动作完成闭环。

一、应用定位与业务闭环

1.1 场景定位

Seal Usage Record 的目标不是复杂后台系统，而是把高频办公动作压缩到一个单页工具中。用户打开页面后，可以查看当前状态、录入新记录、切换筛选条件，并通过按钮推进状态。

1.2 代码阅读路径

1. 先看接口，确认业务对象包含哪些字段。
2. 再看状态，确认哪些数据会触发页面刷新。
3. 接着看方法，确认新增、筛选、推进、导出等逻辑。
4. 最后看 Builder，确认重复 UI 如何复用。

核心判断：轻量办公工具的工程质量，取决于状态链路是否清晰，而不是页面控件数量。

二、工程结构与入口文件

2.1 核心目录

项目为鸿蒙 ArkTS 工程，核心页面位于 entry/src/main/ets/pages/Index.ets。

Seal Usage Record ├── AppScope ├── entry │ └── src │ └── main │ ├── ets │ │ └── pages │ │ └── Index.ets │ └── module.json5 ├── hvigor ├── build-profile.json5 └── oh-package.json5

2.2 页面入口

ArkTS 使用 @Entry 和 @Component 定义页面入口。

@Entry@Componentstruct Index{build(){Scroll(){Column(){// 页面主体}}}}

2.3 技术要素

三、数据模型设计

3.1 接口清单

源码中的接口包括：$iface。这些接口是列表渲染、状态推进和统计计算的基础。

interfaceSealRecord{id:number;title?:string;name?:string;status?:string;done?:boolean;}

实际源码会根据业务场景使用更明确字段，例如议程、记录、设备、印章、用品、里程碑、成员、链接、账号或竞品等。

3.2 字段角色

3.3 建模收益

使用接口可以把页面数据结构固定下来，避免 UI 渲染时字段来源不明确。对于后续接入本地存储或接口数据，也更容易做序列化转换。

四、@State 状态拆解

4.1 状态清单

项目中的状态包括：$state。

@Staterecords:SealRecord[]=[];@StatedraftText:string='';@Statefilter:string='全部';@Statemessage:string='';

不同项目的命名不同，但模式一致：列表保存业务对象，草稿字段接收输入，筛选字段控制视图，消息字段反馈操作结果。

4.2 状态分类

4.3 状态更新策略

列表更新建议使用新数组替换，保证响应式刷新稳定。

privateupdateRecord(id:number):void{this.records=this.records.map((item:SealRecord)=>{if(item.id!==id){returnitem;}return{...item,done:!item.done};});}

五、核心方法解析

5.1 方法清单

源码中的核心方法包括：$method。

5.2 新增逻辑

新增方法通常从输入状态读取文本，做空值判断，然后追加到列表。

privateaddRecord():void{consttitle=this.draftText.trim();if(title.length===0){return;}constrecord:SealRecord={id:Date.now(),title:title,done:false};this.records=[record,...this.records];this.draftText='';}

5.3 筛选逻辑

筛选方法把分类状态和列表数据组合起来。

privatevisibleRecords():SealRecord[]{returnthis.records.filter((item:SealRecord)=>{returnthis.filter==='全部'||item.status===this.filter;});}

5.4 状态推进

状态推进不要直接修改数组中的旧对象，使用 map 生成新对象更稳。

privatenext(id:number):void{this.records=this.records.map((item:SealRecord)=>{returnitem.id===id?{...item,status:'已处理'}:item;});}

六、Builder 组件复用

6.1 Builder 清单

源码中的 Builder 组件包括：$builder。

@Builderprivatecard(item:SealRecord){Column(){Text(item.title??item.name??'未命名').fontSize(16).fontWeight(FontWeight.Bold)}.padding(14).backgroundColor('#FFFFFF').borderRadius(8)}

6.2 复用范围

6.3 分工边界

Builder 负责界面片段，不承担复杂业务计算。复杂逻辑放到 private 方法中，页面更容易维护。

七、页面布局结构

7.1 纵向布局

办公类应用通常使用 Scroll + Column，能容纳统计、表单、筛选和列表。

Scroll(){Column(){// 概览区// 操作区// 列表区}.padding(16)}.height('100%').width('100%')

7.2 信息分区

7.3 ForEach 渲染

ForEach(this.records,(item:SealRecord)=>{this.card(item)},(item:SealRecord)=>item.id.toString())

稳定 key 有助于列表刷新时保持条目对应关系。

八、交互链路

8.1 输入链路

TextInput({text:this.draftText}).onChange((value:string)=>{this.draftText=value;})

输入框只负责写入草稿状态，不直接操作列表。

8.2 按钮链路

Button('添加').onClick(()=>{this.addRecord();})

按钮调用方法，方法更新状态，页面自动刷新。

8.3 反馈链路

privatesetMessage(text:string):void{this.message=text;}

反馈状态适合展示导出成功、提醒已设置、记录已更新等结果。

实践要点：不要让 UI 组件直接散落业务规则。组件触发方法，方法更新状态，是更稳定的链路。

九、业务状态与颜色语义

9.1 状态分类

9.2 文案表达

办公工具的文案要直接表达动作和状态，例如“添加”“确认”“导出”“推进”“已借出”“待审批”。

9.3 卡片信息密度

每张卡片应包含三类信息：

• 主标题：用户首先识别的对象。
• 状态标签：当前处理阶段。
• 操作按钮：下一步能做什么。

十、运行与调试

10.1 DevEco Studio 运行

# 使用 DevEco Studio 打开项目# 同步依赖# 选择 entry 模块# 运行到模拟器或真机

10.2 Hvigor 构建

hvigorw clean hvigorw assembleHap

10.3 调试关注点

十一、可维护性分析

11.1 文件规模

当前 Index.ets 约 83 行，适合作为单页示例。超过这个规模后，可以拆分卡片组件、表单组件和统计组件。

11.2 状态数量控制

能从列表计算出来的值，不必额外保存为 @State。这样可以减少状态不一致。

privateactiveCount():number{returnthis.records.filter((item:SealRecord)=>!item.done).length;}

11.3 命名一致性

源码中的 $primaryMethod 体现了业务动作命名。方法名保持动词开头，可以降低维护成本。

十二、扩展方向

12.1 本地存储

可以把主列表持久化到本地，重新打开页面时恢复。

interfaceStoredItem{id:number;payload:string;updatedAt:number;}

12.2 搜索能力

当记录数量增加后，可以引入关键词搜索，并和现有筛选状态组合。

12.3 导出能力

办公场景常需要导出文本、表格或截图。当前方法层已经有消息状态或导出动作，可以继续扩展。

十三、同类模板抽象

13.1 数据模板

interfaceOfficeItem{id:number;title:string;status:string;}

13.2 状态模板

@Stateitems:OfficeItem[]=[];@StatedraftTitle:string='';@Statefilter:string='全部';

13.3 UI 模板

@BuilderprivateitemCard(item:OfficeItem){Row(){Text(item.title).layoutWeight(1)Text(item.status)}.padding(12).backgroundColor('#FFFFFF')}

十四、实现亮点

14.1 模型明确

Seal Usage Record 使用 $iface 描述业务对象，列表渲染和操作方法都有明确类型依据。

14.2 状态集中

$state 覆盖了页面交互所需的核心状态，调试时可以直接定位状态入口。

14.3 组件复用

$builder 把重复 UI 抽出来，页面结构更清楚。

十五、总结

Seal Usage Record 是一个典型的鸿蒙 ArkTS 办公小工具。它通过 $iface 建模业务数据，通过 $state 保存页面状态，通过 $method 完成新增、筛选、推进和反馈，再通过 $builder 构建统一的卡片与操作区域。

这类应用的实现重点是数据链路：输入进入状态，方法更新列表，列表驱动 UI，统计从源数据派生。掌握这套结构后，可以快速扩展出更多办公看板、登记表、提醒器和轻量管理工具。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！

相关资源：

• HarmonyOS Developer
• ArkTS 语言基础
• ArkUI 声明式开发
• DevEco Studio
• Stage 模型应用包结构
• HarmonyOS 应用开发指南