用 WorkBuddy 从 0 开发一款鸿蒙（HarmonyOS）诗词单词 App：完整复盘 + 踩坑

用 WorkBuddy 从 0 开发一款鸿蒙（HarmonyOS）诗词单词 App：完整复盘 + 踩坑

一款面向鸿蒙（HarmonyOS）的每日诗词 + 英语单词学习应用，支持语音朗诵、背诵打卡、收藏复习、进度持久化。本文复盘从 0 到上线的完整实现思路与关键踩坑——全程由 WorkBuddy 辅助完成：从项目结构梳理、ArkTS 代码生成、TTS 报错排查到复盘文档撰写，AI 搭档贯穿了开发各环节。

一、灵感与定位

"一筏载诗笔，日日打卡渡新知。"

做这款小应用的出发点很简单：想每天背一首诗、记一个单词，但市面上的 App 太重。于是自己动手，做一个干净、能朗诵、能打卡、关掉再打开数据还在的小工具。

作为非专业鸿蒙开发者，我选择把 WorkBuddy 当成贴身搭档：不会的 API 直接问、报错直接贴、文档草稿让它理。下面所有代码与排错结论，都经过它和我一起打磨。

核心功能清单：

• 📜 每日诗词 / 每日单词：首页每日推荐，点开即学
• 🔊 TTS 语音朗诵：诗词朗读、单词发音，支持语速/音量调节
• ✅ 背诵 / 掌握打卡：诗词标记"已背诵"，单词标记"已掌握"，列表绿色高亮
• ⭐ 收藏复习：诗词一键收藏，在"我的"页汇总，点开即可复习
• 💾 进度持久化：退出 App 不丢数据，下次打开自动恢复
• 📊 进度可视化：圆环 / 线性进度条，实时显示学习进度

二、开发环境

构建命令（PowerShell，需设置 JAVA_HOME 与 SDK 路径）：

$env:JAVA_HOME = "D:\DevEcoStudio\jbr"
$env:DEVECO_SDK_HOME = "D:\DevEcoStudio\sdk"
$env:Path = "D:\DevEcoStudio\jbr\bin;" + $env:Path
cd 你的项目目录\HarmonyPoetryWords
node "D:\DevEcoStudio\tools\hvigor\bin\hvigorw.js" --mode module `
  -p module=entry@default -p product=default assembleHap

安装到真机：

& "D:\DevEcoStudio\sdk\default\openharmony\toolchains\hdc.exe" `
  -t <设备SN> install entry\build\default\outputs\default\entry-default-signed.hap

三、项目结构

项目核心文件分布如下：

• entry/src/main/ets/pages/Index.ets：主页面（首页 / 古诗词 / 单词 / 我的 + 诗词详情 + 单词学习）
• entry/src/main/ets/model/PoetryData.ets：古诗词数据（300 首，覆盖唐/宋/元明清）
• entry/src/main/ets/model/WordData.ets：英语单词数据（300 词，按构词规律分阶）
• entry/src/main/ets/entryability/EntryAbility.ets：应用入口
• AppScope/resources/：App 名称、图标、开屏小舟图

所有逻辑（页面 + 详情 + 学习）集中在 Index.ets 里用多个 @Component 组织，方便状态共享。最初的目录划分就是 WorkBuddy 根据我的需求描述建议的，再按实际迭代微调。

四、核心功能实现

4.1 数据模型与词库

古诗词按朝代、作者、分类组织；英语单词按"由简到难、按构词规律"分阶（前缀 / 后缀 / 词根 / 高阶词汇），更符合记忆曲线。下面的 Poetry 类模板由 WorkBuddy 根据鸿蒙 ArkTS 习惯一键生成，我再补字段：

// PoetryData.ets
export class Poetry {
  id: number = 0;
  title: string = '';
  dynasty: string = '';
  author: string = '';
  content: string = '';
  translation: string = '';   // 译文
  appreciation: string = '';  // 赏析
  category: string = '';
}

4.2 TTS 语音朗诵（重点，也是 WorkBuddy 帮我排错最多的地方）

这是整个项目踩坑最多的地方。鸿蒙 textToSpeech 的正确使用流程是：查询语音 → （必要时下载）→ 创建引擎 → 设置监听 → 朗读。

最初我照搬示例代码，朗读始终失败。把报错贴给 WorkBuddy 后，它让我重点核对语言代码格式和参数类型，才定位到下面三个坑：

import { textToSpeech } from '@kit.CoreSpeechKit';
// 1. 查询设备可用语音
const voices = await textToSpeech.listVoices({ requestId: 'q_' + Date.now(), online: 1 });
// 2. 选已安装语音；没有就尝试下载 GA 语音
let voice = voices.find(v => v.language === 'zh_CN' && v.status === 'INSTALLED');
if (!voice) {
  const gv = voices.find(v => v.language === 'zh_CN');
  // downloadVoice 只有 callback 版本，需包成 Promise
  await new Promise((resolve, reject) => {
    textToSpeech.downloadVoice(
      { requestId: 'dl', language: gv.language, person: gv.person, style: gv.style },
      (err, resp) => { err ? reject(err) : resolve(resp); }
    );
  });
}
// 3. 创建引擎
this.engine = await textToSpeech.createEngine({ language: voice.language, person: voice.person, online: 1 });
this.engine.setListener({ onComplete: () => { this.isSpeaking = false; }, /* ... */ });
// 4. 朗读（重点：音量/语速要放在 SpeakParams.extraParams，且是数字不是字符串）
this.engine.speak(text, {
  requestId: 'p_' + Date.now(),
  extraParams: { 'volume': 2.0, 'speed': 1.0, 'pitch': 1.0 } as Record<string, Object>
});

三个关键踩坑（详见第七节）：

1. 语言代码必须是下划线 zh_CN / en_US，不是横杠 zh-CN
2. 音量 volume 必须用数字 2.0，不能是字符串 '2.0'
3. 音量/语速参数要放在 SpeakParams.extraParams，而不是 CreateEngineParams

4.3 背诵 / 掌握打卡

用 AppStorage 保存每个条目的标记状态（key 形如 mem_<id>、known_<id>）。列表里已完成的项显示绿色高亮 + ✓。

// 列表中判断是否完成（引用 statsTrigger 触发刷新）
private isPoemDone(id: number): boolean {
  let _ = this.statsTrigger; // 引用响应式变量
  return AppStorage.get('mem_' + id) === '1';
}

4.4 收藏与汇总

详情页"收藏"按钮写 fav_<id>；"我的"页用 getFavPoems() 汇总所有收藏并支持点击跳转复习：

private getFavPoems(): Poetry[] {
  let _ = this.statsTrigger;
  return poetryList.filter(p => AppStorage.get('fav_' + p.id) === '1');
}

收藏后必须递增 statsTrigger，否则"我的"页不会重新计算列表（这是最初"收藏了但不显示"的根因，也是 WorkBuddy 帮我定位的响应式刷新问题）。

4.5 数据持久化

AppStorage 只在内存中，退出即丢。改用 @kit.ArkData 的 preferences 落盘：

import { preferences } from '@kit.ArkData';
private async persistMarks(): Promise<void> {
  const ctx = getContext(this);
  const prefs = await preferences.getPreferences(ctx, 'learning_progress');
  const ids: number[] = [];
  for (const p of poetryList) if (AppStorage.get('mem_' + p.id) === '1') ids.push(p.id);
  await prefs.put('memorized_poems', JSON.stringify(ids));
  await prefs.flush();
}

启动时反向恢复：

const poemJson = await prefs.get('memorized_poems', '') as string;
if (poemJson) JSON.parse(poemJson).forEach((id: number) => AppStorage.setOrCreate('mem_' + id, '1'));

4.6 响应式刷新（跨页面联动）

AppStorage 不是响应式的——值变了 UI 不会自动重建。解法：用一个 @StorageLink('statsTrigger') 作为"刷新触发器"，任何标记变化都让它 +1，所有依赖它的 getXxx() 方法随之重算。

@StorageLink('statsTrigger') statsTrigger: number = 0;

五、UI 设计

• 水墨风开屏：一叶小舟 + 副标题"一筏载诗笔，日日打卡渡新知"，轻触进入
• 底部 Tab：首页 / 古诗词 / 单词 / 我的
• 卡片式布局：统计卡片、进度条、收藏列表均为圆角白卡
• 配色：诗词红 #E53935、单词蓝 #1565C0、完成绿 #4CAF50

App 名称与图标在 AppScope/resources/base/element/string.json 与 media/app_icon.png 配置。

六、打包与安装

见第二节命令。签名 HAP 通过 hdc install 推到真机即可运行。本文档对应的应用版本为 V28。

七、踩坑总结（避坑必看）

八、后续计划

• 加入"打卡日历"与连续天数激励
• 单词也支持收藏，统一到复习队列
• 导出学习报告 / 分享

九、用 WorkBuddy 辅助鸿蒙开发：我的实际工作流

把 AI 当搭档，不等于让它替我写全部代码，而是把"重复、易错、文档化"的部分交给它，我专注判断与真机验证：

1. 需求 → 结构：先用自然语言描述 App，让 WorkBuddy 给出目录与模块划分，少走弯路。
2. 报错 → 定位：把 DevEco 的控制台报错整段贴过去，它擅长从鸿蒙 API 差异（如 callback 版 downloadVoice、参数类型要求）里揪出根因。
3. 样板 → 生成：数据类、preferences 持久化模板这类样板代码，让它一次性生成，我再按需改字段。
4. 复盘 → 成文：本篇的踩坑表格与文档结构，也是和它一起梳理出来的，效率比纯手敲高很多。

如果你也想用 WorkBuddy 上手鸿蒙 ArkTS 开发，建议从"把报错原样贴给它"开始——它比搜索引擎更懂你当前的工程上下文。

本文基于真实鸿蒙 ArkTS 项目「古诗词单词通」整理，开发过程由 WorkBuddy 全程辅助。欢迎在评论区交流鸿蒙 TTS、声明式 UI 与 AI 辅助开发的经验。 #WorkBuddy