鸿蒙 ArkTS 实战：Self Discipline Contract 从自律契约到个人效率工具完整解析
前言
Self Discipline Contract 是一个基于鸿蒙 ArkTS 的个人效率类单页应用，主题围绕目标承诺、惩罚条款、见证人、完成次数和契约文本展开。它把看不见的状态、计划、注意力或成长记录，转成可输入、可点击、可反馈的界面。
本文直接基于项目Index.ets源码写作，分析它的状态字段、页面结构、核心函数、反馈文案和扩展方向。文章按可发布技术博客组织，不包含作者提示内容。
个人效率工具的关键不是把页面做复杂，而是把一次行动做具体。用户点击后能看到变化，就会更愿意继续使用。
配图可作为文章首屏示意。真实发布时可以替换为运行截图，展示指标区、输入区和反馈区。
一、项目定位与场景价值
1.1 应用定位
用户填写承诺、惩罚和见证人，签署后生成契约文本，并能累计完成记录。
该项目适合用于个人成长、复盘、记录、专注、素材管理等轻量场景。源码集中在一个页面内，便于学习 ArkTS 状态驱动 UI。
1.2 价值拆解
| 价值 | 说明 | 页面体现 |
|---|---|---|
| 快速输入 | 用户能直接编辑核心内容 | TextInput |
| 即时反馈 | 按钮点击后状态变化 | Button |
| 指标可见 | 数字、百分比或文本展示进展 | Completed records |
| 后续复盘 | 文案保留上下文 | 状态提示 |
二、源码入口与页面骨架
2.1 入口组件
页面采用 ArkTS 标准组件结构。
@Entry@Componentstruct Index{build(){// page content}}2.2 结构特点
项目根据业务使用了Scroll、Column、Row、Stack或Grid。这些容器把指标展示、输入表单和操作按钮组织成清晰的单页工具。
Scroll(){Column({space:16}){Text('Self Discipline Contract')// inputs// metric// actions// feedback}}三、状态模型抽象
3.1 模型定义
从源码可以抽象出ContractState。
typeContractState={title:string;value:string|number;note:string;updated:boolean;};3.2 实际状态代码
项目真实状态如下。
@Statepromise:string='Run three times a week';@Statepenalty:string='Donate 50 yuan if broken';@Statewitness:string='Alex';@Statedone:number=4;3.3 状态职责
| 状态 | 类型 | 职责 |
|---|---|---|
promise | 状态字段 | 支撑自律契约的输入、指标或反馈 |
penalty | 状态字段 | 支撑自律契约的输入、指标或反馈 |
witness | 状态字段 | 支撑自律契约的输入、指标或反馈 |
done | 状态字段 | 支撑自律契约的输入、指标或反馈 |
contract | 状态字段 | 支撑自律契约的输入、指标或反馈 |
状态字段都能直接映射到页面上的输入、指标或结果文案，这是单页工具保持可维护性的基础。
四、默认数据与首屏体验
4.1 默认内容
| 默认项 | 字段 | 含义 |
|---|---|---|
| Run three times a week | promise | 默认承诺 |
| Alex | witness | 默认见证人 |
4.2 默认值作用
默认值让用户进入页面后马上理解使用方式。它既是演示数据，也是开发阶段验证页面行为的样例。
- 默认输入说明字段格式。
- 默认指标让页面有进度感。
- 默认文案解释下一步动作。
五、核心业务函数
5.1 主逻辑代码
项目核心函数如下。
sign():void{this.contract='I commit: '+this.promise+'. Witness: '+this.witness+'. Penalty: '+this.penalty+'.';}5.2 操作流程
- 填写承诺
- 填写惩罚和见证人
- 签署契约
- 累计完成次数
这条流程让页面形成闭环：用户输入内容，按钮触发逻辑，状态发生变化，界面立即反馈。
六、辅助逻辑与展示
6.1 辅助代码
项目中还包含补充动作或布局展示。
Button('Done +1').layoutWeight(1).backgroundColor('#16A34A').onClick(()=>this.done++)6.2 辅助能力
| 类型 | 作用 | 价值 |
|---|---|---|
| 上限控制 | 避免数值越界 | 数据稳定 |
| 卡片展示 | 提升信息密度 | 易扫读 |
| 复盘文案 | 保留上下文 | 可回顾 |
| 计数累计 | 形成进展感 | 强化坚持 |
七、输入组件设计
7.1 TextInput 状态绑定
输入框直接更新状态。
TextInput({text:this.promise,placeholder:'Input value'}).onChange((value:string)=>this.promise=value)7.2 输入类型
这类工具输入通常分为文本、数字和备注。文本用于目标和说明，数字用于能量、分钟、次数、等级、时长等指标。
TextInput({text:this.promise,placeholder:'Content'}).onChange((value:string)=>this.promise=value)八、指标展示策略
8.1 核心指标
当前项目的核心指标是Completed records。
Text('Completed records '+value).fontSize(24).fontWeight(FontWeight.Bold)8.2 指标类型
| 类型 | 示例 | 作用 |
|---|---|---|
| 百分比 | energy、progress | 展示状态强弱 |
| 次数 | count、done、sessions | 展示积累 |
| 等级 | badge、level、rank | 形成激励 |
| 文案 | note、summary、poster | 输出结果 |
九、反馈文案设计
9.1 文案更新
反馈文案通过状态字段改变。
this.note='Action recorded.';this.status='Result updated.';9.2 好反馈的标准
| 标准 | 说明 |
|---|---|
| 具体 | 包含当前活动、目标或任务 |
| 简短 | 移动端容易阅读 |
| 可复盘 | 之后看仍能理解 |
| 可行动 | 指向下一步安排 |
十、布局与视觉层次
10.1 单页结构
页面围绕一个主任务展开，避免用户在多个页面间跳转。
Column(){Text('Self Discipline Contract')// metric area// form area// action area}10.2 视觉重点
| 区域 | 内容 | 目的 |
|---|---|---|
| 顶部 | 指标或标题 | 立即建立语境 |
| 中部 | 输入项 | 修改状态 |
| 底部 | 按钮和文案 | 完成操作闭环 |
十一、运行验证流程
11.1 手工验证
可以按以下流程验证：
- 打开页面，确认标题或主指标存在。
- 检查默认输入值是否与源码一致。
- 修改第一个输入框。
- 点击主按钮。
- 观察指标或反馈文案是否变化。
// 验证路径示例constbefore='default state';constaction='tap primary button';constafter='metric and message updated';console.info(before+' -> '+action+' -> '+after);11.2 验证重点
| 验证点 | 预期 |
|---|---|
| 输入同步 | 状态跟随输入 |
| 按钮触发 | 函数执行 |
| 指标变化 | 数字或状态更新 |
| 文案反馈 | 结果明确 |
| 连续操作 | 数据边界稳定 |
十二、边界处理
12.1 数值边界
源码中常用Math.max和Math.min控制边界。
constsafeValue=Math.max(0,Math.min(100,value));12.2 业务边界
| 场景 | 风险 | 处理方式 |
|---|---|---|
| 能量低于 0 | 状态失真 | 使用下限保护 |
| 分数超过上限 | 激励失衡 | 使用上限保护 |
| 分钟过低 | 专注块无效 | 设置最小分钟 |
| 字数为 0 | 语速异常 | 分母保护 |
| 归档重复点击 | 数据膨胀 | 后续增加历史记录 |
十三、扩展为完整应用
13.1 业务扩展
后续可以加入契约周期、失败记录、见证人确认、提醒通知和契约归档。
13.2 工程抽象
可以抽象统一效率记录对象。
interfaceProductivityRecord{title:string;metric:number;note:string;createdAt:number;}functioncreateProductivityRecord(title:string,metric:number,note:string):ProductivityRecord{return{title,metric,note,createdAt:Date.now()};}十四、维护与优化
14.1 状态集中
当前体量适合把状态保留在页面组件中，后续加入历史记录后再拆分数据层。
14.2 文案管理
反馈文案可以逐步集中管理，便于导出、分享和多语言处理。
functionbuildFeedback(action:string,target:string):string{returnaction+': '+target;}14.3 持久化方向
效率工具依赖长期记录。优先保存标题、指标、备注和时间戳，就能支撑历史列表和趋势图。
十五、工程复盘
15.1 当前实现亮点
- 状态字段贴合具体场景。
- 页面动作短，反馈明确。
- 指标展示有激励作用。
- 布局结构适合移动端。
- 代码便于继续扩展。
15.2 可复用经验
Self Discipline Contract的实现方式可以迁移到社交能量、阅读摘录、演讲练习、时间账户、微习惯和日常输出等多个方向。核心都是把一个抽象状态转成明确的状态更新。
总结
Self Discipline Contract用鸿蒙 ArkTS 构建了一个围绕自律契约的个人效率工具。它通过@State保存核心数据，通过输入框收集用户内容，通过按钮触发业务函数，再用指标和文案完成即时反馈。
从工程角度看，这个项目已经具备单页工具的完整闭环。后续继续接入历史记录、图表、提醒、音频、图片或本地持久化，都可以在当前结构上平滑扩展。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
补充说明：反馈文案负责保存上下文，后续可以沉淀为历史记录。
补充说明：如果接入本地存储，建议优先保存标题、指标、备注和时间戳。
补充说明：当前页面把个人效率场景拆成输入、指标和反馈三个稳定部分。
补充说明：指标展示能让用户快速看到一次行动带来的变化。
相关资源：
- HarmonyOS 开发者官网
- ArkTS 语言基础
- ArkUI 组件开发
