鸿蒙 ArkTS 实战：Cube Training Camp 从魔方训练营到社群活动工具完整解析

前言

Cube Training Camp 是一个基于鸿蒙 ArkTS 与 ArkUI 声明式范式实现的单页应用，主题聚焦速拧训练记录。

它把 维护公式卡、最好成绩、最近成绩、排名和训练计划 这样的线下或线上活动场景，拆成可编辑字段、可点击动作、可见结果和稳定布局。

本文围绕项目真实的Index.ets代码展开，分析它的状态模型、组件结构、按钮逻辑、视觉分层和扩展方向。

图示说明：配图用于表达鸿蒙 ArkTS 应用中状态、组件、事件和反馈之间的组织关系，帮助理解本文的代码拆解。

阅读时可以结合 HarmonyOS 应用开发文档、ArkTS 语言基础、ArkUI 声明式开发范式、组件参考 等资料，更快理解本文涉及的 ArkTS 与 ArkUI 基础能力。

社群活动工具的关键是把一次真实动作做成闭环：输入能被记录，按钮能触发变化，结果能被用户立即确认。

一、应用定位与业务场景

1.1 项目解决的问题

魔方训练营 面向的业务场景是：维护公式卡、最好成绩、最近成绩、排名和训练计划。

在这种场景里，用户需要的是轻量、快速、明确的记录页面。

它不需要先进入复杂后台，也不需要打开很多页面才能完成一次操作。

1.2 适合学习的人群

这个项目适合正在学习鸿蒙 ArkTS 的开发者，尤其适合关注状态驱动 UI、活动记录工具、移动端表单交互和单页应用结构的读者。

1.3 页面核心价值

从使用路径看，页面完成了四个动作。

1. 展示当前活动关键内容。
2. 接收用户对字段的修改。
3. 用按钮触发状态变化。
4. 在同一页面刷新结果。

这就是一个完整的最小可用闭环。

二、工程入口与页面结构

2.1 入口文件

项目的主要代码集中在Index.ets。

entry/ src/ main/ ets/ pages/ Index.ets

这个文件同时承担状态声明、交互函数和 UI 构建。

2.2 页面组件声明

@Entry@Componentstruct Index{build(){// 页面内容}}

@Entry表示页面入口，@Component表示组件可以被 ArkUI 渲染。

2.3 当前页面边界

当前实现没有引入远程请求、数据库或多页面跳转。

它选择先把单页体验做完整，这对于社群活动类小工具很合适。

三、状态模型拆解

3.1 状态字段总览

这些字段共同描述了 魔方训练营 的业务状态。

3.2 字段命名与业务语义

字段命名直接对应页面含义。

formula通常代表主记录，plan则代表数量、状态或结果反馈。

这种写法能让读者通过变量名直接理解业务。

3.3 真实源码片段

@Stateformula:string='R U R prime U prime';@Statebest:number=43;@Statelatest:number=51;@Staterank:number=5;@Stateplan:string='Practice F2L for 15 minutes';solve():void{this.latest=Math.max(20,this.latest-2);this.best=Math.min(this.best,this.latest);this.rank=Math.max(1,this.rank-1);}

这段代码是项目的核心。

它展示了状态如何被声明，以及按钮点击后如何改变状态。

四、交互逻辑分析

4.1 交互点总览

每个交互点都只有一个清晰目的。

这让页面行为足够可预测。

4.2 输入框绑定

输入字段通过TextInput和onChange完成同步。

TextInput({text:this.formula,placeholder:'公式卡'}).onChange((v:string)=>this.formula=v)

用户输入后，状态立即更新。

4.3 按钮反馈

按钮通常会修改数字、文本或排名。

Button('Update').width('100%').onClick(()=>{this.plan=this.formula;})

结果区引用状态后，页面会自动刷新。

五、布局结构分析

5.1 页面布局描述

顶部并列成绩卡展示最好和最近用时，正文输入公式与训练计划，按钮记录一次解法成绩。

这个布局把核心信息放在靠前位置，把编辑和反馈放在下方或侧边。

5.2 关键 UI 代码

Row({space:10}){Text('Best\n'+this.best+'s').layoutWeight(1).fontSize(24).fontWeight(FontWeight.Bold).textAlign(TextAlign.Center).padding(20).backgroundColor('#DCFCE7').borderRadius(8)Text('Latest\n'+this.latest+'s').layoutWeight(1).fontSize(24).fontWeight(FontWeight.Bold).textAlign(TextAlign.Center).padding(20).backgroundColor('#DBEAFE').borderRadius(8)}

这段代码体现了页面最有代表性的视觉结构。

5.3 Scroll 的价值

活动工具往往字段较多。

Scroll(){Column({space:16}){// 输入区、状态区、按钮区}.padding(20).width('100%')}

滚动容器保证小屏设备上也能完整操作。

六、视觉层级设计

6.1 背景与强调色

当前页面背景色是#FFFFFF，强调色是#DCFCE7。

它们分别承担阅读底色和重点信息提示的作用。

6.2 卡片分组

6.3 字号层级

页面中常见字号可以分为三档。

• 28 到 56：用于标题、主指标和高优先级数字。
• 18 到 24：用于主要内容和卡片文本。
• 14 到 16：用于说明、状态和补充信息。

这种层级适合移动端快速扫读。

七、状态计算与边界控制

7.1 自增类状态

社群活动工具常见的自增字段包括报名、照片、视频、投票、打卡和记录次数。

this.count++;

每次自增后都应该有可见反馈。

7.2 上下限控制

排名、评分、进度和成绩通常需要边界。

this.rank=Math.max(1,this.rank-1);this.score=Math.min(100,this.score+1);

边界控制能避免显示不符合业务规则的数据。

7.3 文本结果拼接

很多反馈来自字段拼接。

constmessage=this.formula+' updated with '+this.plan;

拼接结果应该足够具体，让用户知道刚才的动作对应哪条记录。

八、输入体验优化

8.1 placeholder 的作用

placeholder让用户知道每个输入框应该填什么。

TextInput({text:this.formula,placeholder:'Primary field'})

对活动记录工具来说，清楚的占位提示能降低输入成本。

8.2 数字输入

涉及成本、评分或数量时，可以使用数字输入。

TextInput({text:this.cost,placeholder:'Cost record'}).type(InputType.Number)

这能减少非法字符输入。

8.3 长文本处理

路线、计划、任务和反馈可能很长。

长文本适合放入滚动容器或结果卡，而不是挤在按钮旁边。

九、组件能力映射

9.1 常用组件表

9.2 layoutWeight 的价值

layoutWeight可以让并列组件合理分配空间。

Row({space:10}){Text('A').layoutWeight(1)Text('B').layoutWeight(2)}

这在状态卡和左右分栏中很常见。

9.3 borderRadius 与 padding

Text('Card').padding(16).backgroundColor('#DCFCE7').borderRadius(8)

适当留白会让活动信息更像卡片，而不是拥挤文本。

十、可扩展数据模型

10.1 从单条状态到记录对象

interfaceActivityItem{id:string;title:string;detail:string;status:string;updatedAt:number;}

这个对象可以承载一次活动记录。

10.2 记录数组

@Stateitems:ActivityItem[]=[];

数组状态适合扩展历史列表。

10.3 追加记录

this.items=[...this.items,{id:Date.now().toString(),title:this.formula,detail:this.plan,status:'saved',updatedAt:Date.now()}];

不可变追加方式更容易触发界面刷新。

十一、本地存储方向

11.1 为什么需要持久化

活动数据往往需要保留。

例如报名数、照片数量、训练成绩、投票状态和时间线，都不应该在应用关闭后丢失。

11.2 持久化结构

interfaceSavedActivityState{current:ActivityItem;history:ActivityItem[];version:number;}

保留version可以支持后续字段升级。

11.3 恢复默认值

functionreadText(value:string|undefined):string{returnvalue||'';}

恢复数据时要考虑旧版本字段缺失。

十二、调试与验证

12.1 验证状态

Button('Debug').onClick(()=>{console.info('current: '+this.formula);})

先确认状态变化，再观察 UI 反馈。

12.2 验证边界

12.3 验证小屏体验

小屏设备重点检查输入框、按钮和卡片。

如果内容被挤压，优先调整卡片宽度、字号和滚动区域。

十三、工程化拆分

13.1 抽离状态卡

@BuilderfunctionStateCard(label:string,value:string,color:string){Column({space:6}){Text(label).fontSize(14).fontColor('#6B7280')Text(value).fontSize(18).fontWeight(FontWeight.Bold)}.padding(16).backgroundColor(color).borderRadius(8)}

状态卡可以复用到报名、照片、投票、成绩和记录次数。

13.2 抽离格式化函数

exportfunctionbuildStatus(title:string,value:string):string{returntitle+' / '+value;}

这样可以减少页面里的字符串拼接。

13.3 抽离主题配置

constTheme={pageBg:'#FFFFFF',accent:'#DCFCE7',radius:8,padding:20};

主题配置可以让多个活动页面保持一致。

十四、同类场景迁移

14.1 活动报名

报名类页面可以复用人数、状态和按钮结构。

14.2 训练打卡

训练类页面可以复用成绩、排名和进度结构。

14.3 作品提交

作品类页面可以复用主题、素材、投票和排名结构。

interfaceSubmitResult{workName:string;votes:number;rank:number;}

十五、发布级技术亮点

15.1 状态闭环清楚

魔方训练营 的状态、输入、按钮和反馈都在一个页面中完成。

15.2 场景表达明确

字段名和按钮行为都围绕 速拧训练记录 展开，文章读者能从代码里看到真实业务。

15.3 扩展路线自然

当前项目可以继续扩展历史记录、附件、分享、统计图、本地存储和社群成员管理。

一个好的鸿蒙小工具，应该先让用户完成一次真实动作，再考虑更复杂的数据系统。

十六、总结

Cube Training Camp 展示了鸿蒙 ArkTS 在 速拧训练记录 场景中的单页应用写法。

它用@State保存核心状态，用TextInput接收用户输入，用Button触发业务动作，再用卡片、文本和数字把结果反馈出来。

从技术角度看，它覆盖了状态管理、声明式 UI、输入绑定、按钮事件、边界控制和移动端布局。

从产品角度看，魔方训练营 把 维护公式卡、最好成绩、最近成绩、排名和训练计划 变成了一个可以直接使用的轻量工具。

相关资源：

• HarmonyOS 应用开发文档
• ArkTS 语言基础
• ArkUI 声明式开发范式