用 HarmonyOS ArkUI 构建「背诵师说」应用——从零到一的技术实践
本文记录了一个经典文本背诵类 App 在 HarmonyOS 上的完整开发过程，涵盖 ArkUI 声明式 UI、状态管理、中国风设计等关键技术点，适合 HarmonyOS 入门开发者参考。
一、项目背景
最近在学习 HarmonyOS 应用开发，想找一个既有文化内涵、又能覆盖多个技术点的练手项目。想到小时候背《师说》的经历——如果能做一个优雅的背诵 App，既能练技术，又有实际用途，岂不是一举两得？
于是就有了这个项目：一个用 ArkUI 构建的《师说》背诵应用。
项目地址：本文会一步步拆解核心实现。
二、技术选型与项目结构
2.1 技术栈
| 项目 | 选择 |
|---|---|
| 开发框架 | HarmonyOS ArkUI（声明式 UI） |
| 开发语言 | ArkTS（TypeScript 的超集） |
| 项目模型 | Stage 模型 |
| 最低 API | API 9+ |
| 构建工具 | hvigor |
2.2 目录结构
entry/src/main/ets/ ├── entryability/ │ └── EntryAbility.ets # Ability 生命周期管理 ├── entrybackupability/ │ └── EntryBackupAbility.ets └── pages/ └── Index.ets # 主页面（全部 UI 在此）选择单页面架构，因为背诵应用的核心诉求就是沉浸式阅读，不需要复杂路由跳转。这也是 ArkUI 非常适合的场景——一个页面、丰富交互、流畅滚动。
三、核心功能实现
3.1 数据结构设计
《师说》全文约 500 字，按自然段落分为 4 段，每段若干句。为了让代码清晰且支持逐句展示，我采用了二维数组的数据结构：
privatereadonlyfullText:string[][]=[// 第一段：8句["古之学者必有师。","师者，所以传道受业解惑也。",// ...],// 第二段：13句["嗟乎！师道之不传也久矣！",// ...],// 第三段、第四段...];段落标题和句数统计也独立维护：
privatereadonlyparagraphTitles:string[]=["第一段 · 论师之必要","第二段 · 论耻学于师","第三段 · 圣人无常师","第四段 · 作说以贻"];这种"数据与视图分离"的方式，让后续的迭代（比如添加白话翻译、注释等）变得非常容易。
3.2 段落折叠展开 —— 状态管理
背诵的核心体验是"逐段攻克"，所以折叠展开功能必不可少。
状态定义：
// 控制"全部展开/收起"的一键开关@StateisAllExpanded:boolean=true;// 记录每个段落的展开状态@StateparagraphExpanded:boolean[]=[true,true,true,true];展开/收起逻辑：
// 全部展开/收起按钮Button(this.isAllExpanded?'收起全部':'展开全部').onClick(()=>{this.isAllExpanded=!this.isAllExpanded;// 同步所有段落的状态for(leti=0;i<this.paragraphExpanded.length;i++){this.paragraphExpanded[i]=this.isAllExpanded;}})点击段落标题切换：
Row().onClick(()=>{this.paragraphExpanded[index]=!this.paragraphExpanded[index];// 同步"全部展开"状态this.isAllExpanded=this.paragraphExpanded.every((v)=>v);})这里有一个细节：当用户手动展开所有段落时，isAllExpanded会自动更新为true；收起任意一个则自动变为false。这种"双向同步"让按钮状态始终与实际情况一致。
3.3 条件渲染与动画
ArkUI 支持在build()方法中使用if条件渲染，配合transition实现展开动画：
if(this.paragraphExpanded[index]){Column(){ForEach(paragraph,(sentence:string,idx:number)=>{// 渲染每一句Text(sentence).fontSize(17).lineHeight(30)})}.transition({type:TransitionType.Insert,opacity:1})}transition的Insert类型会在组件挂载时播放淡入效果，避免了展开时内容"硬出现"的突兀感。
3.4 滚动控制
长文本场景下，滚动体验至关重要。ArkUI 提供了Scroll组件和Scroller控制器：
privatescroller:Scroller=newScroller();build(){Scroll(this.scroller){Column(){// 全部内容}}}回到顶部功能：
this.scroller.scrollTo({xOffset:0,yOffset:0,animation:{duration:500,curve:Curve.EaseInOut}})scrollTo支持动画曲线和时长设置，EaseInOut曲线让滚动先加速后减速，手感很自然。
3.5 中国风 UI 设计
视觉上，我希望让 App 有一种"捧读古籍"的感觉。
色彩系统：
// 主色调：棕褐色系'#2C1810'// 正文文字（深褐）'#8B4513'// 主色（赭石）'#C49A6C'// 装饰色（古铜金）'#F8F4EC'// 背景色（米白宣纸）'#EDE5D8'// 卡片边框（淡黄）卡片设计：每段正文包裹在白色卡片中，带圆角和阴影，模拟"书页"质感：
Column().width('88%').backgroundColor('#FFFFFF').borderRadius(10).border({width:1,color:'#EDE5D8'}).shadow({radius:6,color:'#1A000000',offsetX:0,offsetY:2})装饰元素：竖线、圆点、分隔线等细节增强古风感：
// 句子前的装饰竖线Row().width(3).height('80%').backgroundColor('#D4C5A9').borderRadius(2)// 段落标题前的装饰点Ellipse().width(8).height(8).fill('#C49A6C')四、开发过程中的踩坑记录
坑 1：FontWeight.SemiBold 不存在
编译时报错：
Property 'SemiBold' does not exist on type 'typeof FontWeight'查阅 API 后发现 HarmonyOS 的FontWeight枚举只包含Lighter | Regular | Medium | Bold | Bolder，没有SemiBold。解决方案：使用FontWeight.Medium替代。
坑 2：Windows 下 hvigor 构建注意
在 cmd.exe 中运行hvigorw assembleHap时，Windows 没有tail命令。建议将构建输出重定向到文件再查看：
hvigorw assembleHap --no-daemon>build_output.txt2>&1坑 3：ForEach 的 keyGenerator
ArkUI 的ForEach要求提供唯一的 key 生成函数，用于列表 diff 更新：
ForEach(this.fullText,(paragraph,index)=>{/* item 渲染 */},(paragraph)=>paragraph[0]// keyGenerator)如果 key 不唯一，控制台会报警告且列表更新可能出现异常。对于纯文本数据，用首句或索引作为 key 最稳妥。
五、性能与体验优化
5.1 减少不必要的状态更新
@State装饰的变量会在每次变化时触发视图重绘。我把段落展开状态设计为boolean[]而非Map<number, boolean>，因为数组在 ArkUI 中变更检测效率更高。
5.2 文本行高与阅读舒适度
古诗文背诵需要长时间注视屏幕，行高（lineHeight）和字号（fontSize）的配比直接影响阅读体验：
- 正文：
fontSize: 17fp, lineHeight: 30（行高约为字号的 1.76 倍） - 标题：
fontSize: 48fp, letterSpacing: 20（大字距，营造古书排版感）
5.3 点击交互反馈
每句正文都绑定了onClick事件，虽然当前只做了占位，后续可以扩展为"点击高亮当前句子"或"点击播放该句朗读"功能：
Text(sentence).onClick(()=>{// 预留：高亮、朗读、标注等})六、可扩展的方向
目前 App 已完成核心背诵功能，未来可以添加：
- 朗读模式：接入 TTS（TextToSpeech），逐句朗读
- 背诵检测：隐藏部分文字，用户凭记忆填空
- 注释弹窗：点击难词弹出释义（如"传道受业解惑"的逐词解释）
- 进度追踪：记录已背段落、复习提醒
- 多篇古文：扩展为"古文背诵合集"，加入《岳阳楼记》《醉翁亭记》等
这些功能在 ArkUI 中都能用现有的组件能力实现，难度主要在业务逻辑而非 UI 层面。
七、总结
通过这个项目，我完整地体验了 HarmonyOS ArkUI 的开发流程：
| 知识点 | 实践内容 |
|---|---|
| 声明式 UI | Column、Row、Text、Scroll、Stack 等组件使用 |
| 状态管理 | @State 装饰器、数组状态同步 |
| 条件渲染 | if/else 配合 transition 动画 |
| 数据驱动 | ForEach 列表渲染与 keyGenerator |
| 样式系统 | 链式 API、色彩/字体/阴影配置 |
| 构建部署 | hvigor 构建与 HAP 打包 |
最重要的是，在这个过程中我重新理解了《师说》——“闻道有先后，术业有专攻”——做技术和做学问，道理是相通的。希望这篇博客能为正在学习 HarmonyOS 开发的你提供一些参考。
项目代码开源，欢迎 Star 和 PR。如果你也想亲手构建一个背诵应用，不妨从 Fork 开始。
