AI单词记忆卡基于HarmonyOS ArkTS的智能记忆卡应用开发实战摘要本文详细记录了在HarmonyOS平台上使用ArkTS语言开发AI单词记忆卡应用的完整技术历程。文章按照对齐→架构→原子化→审批→自动化执行→评估六阶段开发方法论系统阐述了从需求分析到架构设计、从任务分解到编码实现、从测试验证到复盘总结的全过程。通过丰富的ArkTS代码示例和HarmonyOS API调用实践深度剖析了AI原生应用在鸿蒙生态中的开发范式与技术要点。全文约10,000字适合HarmonyOS应用开发者、AI产品研发人员及对ArkTS/ArkUI技术栈感兴趣的读者阅读。一、对齐阶段Align从模糊需求到精确规范1.1 项目背景与原始需求AI单词记忆卡是一款面向英语学习者的智能背词工具其核心诉求是用户输入待学习的单词列表AI自动生成结构化的记忆卡片包含单词释义、音标、词根词缀分析、记忆技巧、搭配用法、复习计划等完整学习信息。在当前的移动互联网教育赛道中传统背词应用如百词斩、墨墨背单词等普遍存在以下痛点内容同质化所有用户看到的是相同的词库内容缺乏个性化定制能力记忆方法单一仅提供基础的释义和例句缺少词根拆解、联想记忆等深度学习方法复习计划机械虽然遵循艾宾浩斯遗忘曲线但无法根据用户的学习习惯动态调整学习体验割裂背词、查词、复习等功能分散在不同模块中学习流不连贯AI大模型的崛起为上述问题提供了全新的解决思路。借助大语言模型的语义理解和生成能力我们可以为每个单词量身定制记忆卡片在词根分析、联想记忆、智能例句等方面实现质的飞跃。1.2 项目上下文分析在着手开发之前我们首先对现有项目结构和开发环境进行了全面分析。1.2.1 项目结构分析本项目基于DevEco Studio构建是HarmonyOS原生应用。项目根目录为MyApplication采用模块化工程结构MyApplication/ ├── entry/ # 主模块 │ ├── src/main/ │ │ ├── ets/ │ │ │ ├── apps/ # 应用页面集合 │ │ │ │ └── AI单词记忆卡/ # 本应用模块 │ │ │ │ ├── AI单词记忆卡Page.ets # 页面层 │ │ │ │ ├── AI单词记忆卡Model.ets # 数据模型层 │ │ │ │ └── AI单词记忆卡Service.ets # 业务逻辑层 │ │ │ ├── pages/ │ │ │ │ └── Index.ets # 主入口页面应用列表 │ │ │ ├── entryability/ │ │ │ │ └── EntryAbility.ets # Ability生命周期 │ │ │ └── entrybackupability/ │ │ │ └── EntryBackupAbility.ets │ │ ├── module.json5 # 模块配置文件 │ │ └── resources/ # 资源文件 │ ├── oh-package.json5 # 依赖配置 │ └── build/ # 构建产物 ├── oh-package.json5 # 全局依赖配置 └── build-profile.json5 # 构建配置从项目结构可以看出这是一个典型的HarmonyOS多应用聚合平台——主页面Index.ets以网格形式展示所有AI应用用户点击后通过router.pushUrl跳转到对应应用的详情页。每个应用独立封装在apps/目录下的子文件夹中遵循Page Model Service的三层架构模式。1.2.2 技术栈分析编程语言ArkTSHarmonyOS的TypeScript方言具备静态类型检查能力UI框架ArkUI声明式UI框架类似SwiftUI的语法风格开发工具DevEco Studio基于IntelliJ的IDE目标平台HarmonyOS设备类型为phone依赖管理oh-package.json5HarmonyOS的包管理配置路由方案kit.ArkUI的router模块值得特别关注的是ArkTS相较于标准TypeScript的语法约束。在后续的编码阶段我们必须严格遵守这些约束否则编译将无法通过。例如不支持any和unknown类型必须显式指定类型不支持解构赋值必须使用临时变量逐字段操作不支持Function.bind、Function.apply、Function.call需遵循传统OOP风格处理this语义不支持索引签名必须使用数组替代不支持in运算符需使用instanceof替代this只能在实例方法中使用不能在独立函数和静态方法中使用这些约束对ArkTS开发者的编码习惯提出了较高要求但也正是这些限制保证了代码在HarmonyOS运行时中的高效执行。1.3 需求理解与边界确认在深入理解项目背景和技术约束后我们梳理出AI单词记忆卡的核心功能需求功能模块优先级描述单词列表输入P0用户输入待学习的单词列表记忆方法选择P0用户选择或输入偏好的记忆方法如词根法、联想法等AI记忆卡生成P0基于输入调用AI服务生成结构化记忆卡片卡片内容展示P0展示单词、音标、词性、释义、词根、记忆法、例句、搭配、复习计划、分组建议、学习技巧返回导航P1提供返回上一级页面的能力其中P0为必须实现的核心功能P1为辅助功能。本次开发的边界范围限定在前端UI交互层 数据模型层 模拟服务层AI大模型的真实调用由于环境和成本的限制在本次实现中以Service层的Mock数据替代。1.4 疑问澄清与决策在需求对齐过程中我们遇到并解决了以下关键问题Q1数据模型需要包含哪些字段经过分析一个完整的单词记忆卡应当包含以下信息维度基础信息单词word、音标phonetic、词性pos语义信息中文释义meaning语言分析词根root记忆辅助记忆技巧mnemonic应用场景例句example、搭配collocations学习规划复习计划review_plan、分组建议grouping、学习技巧tips卡片集cards支持批量单词生成Q2页面结构如何组织采用输入区 生成按钮 结果展示区的经典三段式布局。输入区收集用户参数按钮触发生成逻辑结果区以卡片形式展示AI生成的完整学习内容。这种布局符合用户先输入→后查看的操作心智模型。Q3如何与主页面集成主页面Index.ets通过apps.json配置文件维护应用列表每个应用包含icon、title、subtitle、pageUrl等信息。AI单词记忆卡需要注册为其中一个应用用户在主页面点击对应卡片后通过router.pushUrl跳转到本页面。1.5 最终共识经过上述对齐过程我们形成了以下共识文档要点项目名称AI单词记忆卡技术栈ArkTS ArkUI HarmonyOS架构模式Page视图层- Model数据层- Service服务层三层架构核心功能用户输入单词列表和记忆方法AI生成结构化的记忆卡片数据流用户输入 → Page层收集 → Service层处理 → Model层封装 → Page层渲染验收标准输入框可正常录入、点击生成按钮可展示Mock数据、返回按钮可正确导航二、架构阶段Architect从共识到系统设计2.1 整体架构设计基于共识阶段的输出我们设计了AI单词记忆卡的整体架构。架构设计遵循以下原则分层清晰视图层、数据层、服务层各司其职职责边界明确单向数据流数据从Service流向Model再流向Page避免双向绑定带来的复杂性可测试性Service层独立于UI可以单独进行单元测试可扩展性未来接入真实AI API时只需修改Service层Page和Model层无需变动架构分层图┌─────────────────────────────────────────────────────────┐ │ UI 层 (Page) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ AI单词记忆卡Page.ets │ │ │ │ ├── 输入区单词列表 TextInput │ │ │ │ ├── 输入区记忆方法 TextInput │ │ │ │ ├── 操作区生成按钮 Button │ │ │ │ └── 展示区记忆卡片 Column ForEach │ │ │ └──────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ 业务逻辑层 (Service) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ AI单词记忆卡Service.ets │ │ │ │ ├── generateData(input) → AI单词记忆卡Data │ │ │ │ └── 内部数据处理逻辑 │ │ │ └──────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ 数据模型层 (Model) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ AI单词记忆卡Data │ │ │ │ ├── cards: string[] │ │ │ │ ├── word: string / phonetic: string │ │ │ │ ├── pos: string / meaning: string │ │ │ │ ├── root: string / mnemonic: string │ │ │ │ ├── example: string / collocations: string[] │ │ │ │ ├── review_plan: string / grouping: string │ │ │ │ └── tips: string │ │ │ └──────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ 路由层 (Router) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ kit.ArkUI / router │ │ │ │ └── router.pushUrl / router.back() │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘2.2 模块依赖关系Index.ets (主页面) │ │ router.pushUrl({ url: apps/AI单词记忆卡/AI单词记忆卡Page }) │ ▼ AI单词记忆卡Page.ets ────import────▶ AI单词记忆卡Model.ets │ │ │ import │ import (通过Page间接依赖) ▼ │ AI单词记忆卡Service.ets ◀───────────────────┘ │ └── 依赖无外部依赖纯逻辑层依赖关系说明AI单词记忆卡Page.ets依赖AI单词记忆卡Model.ets类型引用和AI单词记忆卡Service.ets服务调用AI单词记忆卡Service.ets依赖AI单词记忆卡Model.ets数据模型AI单词记忆卡Model.ets无外部依赖是纯数据定义所有文件均位于同一目录下采用相对路径导入2.3 数据流向设计用户输入单词和记忆方法 │ ▼ Page层收集输入 → inputData: Recordstring, Object │ ▼ 点击生成记忆卡按钮 │ ▼ 调用 service.generateData(inputData) │ ▼ Service层处理输入生成模拟数据 │ ▼ 返回 AI单词记忆卡Data 实例 │ ▼ Page层赋值 resultData触发UI更新 │ ▼ showResult true条件渲染结果显示区域 │ ▼ ForEach 遍历 cards 和 collocations 数组 Row 逐行展示 word/phonetic/pos/meaning 等字段这个数据流的核心特点是由状态变量驱动UI更新。Page层中定义了State inputData、State resultData、State showResult三个状态变量当Service返回结果并赋值给resultData后ArkUI的响应式框架自动检测到状态变化重新执行build()方法中与resultData相关的UI描述从而完成视图更新。2.4 接口契约定义2.4.1 数据模型接口// AI单词记忆卡Data - 核心数据模型classAI单词记忆卡Data{cards:string[]// 卡片列表支持批量word:string// 单词phonetic:string// 音标pos:string// 词性meaning:string// 中文释义root:string// 词根mnemonic:string// 记忆技巧example:string// 例句collocations:string[]// 搭配列表review_plan:string// 复习计划grouping:string// 分组建议tips:string// 学习技巧}2.4.2 服务层接口// 输入参数input:Recordstring,Object// 其中支持的键// 单词列表 → string 类型// 记忆方法 → string 类型// 返回结果generateData(input:Recordstring,Object):AI单词记忆卡Data2.4.3 页面层状态变量StateinputData:Recordstring,Object{}// 输入数据容器StateresultData:AI单词记忆卡Data|nullnull// 结果数据可为空StateshowResult:booleanfalse// 结果展示控制2.5 异常处理策略在ArkTS的约束下异常处理策略设计如下空值保护resultData声明为AI单词记忆卡Data | null类型在UI渲染前通过! null进行空值检查条件渲染通过showResult布尔状态变量控制结果区域的显示/隐藏避免在未生成数据时渲染空白内容catch子句遵循ArkTS规范catch子句变量不标注类型ArkTS不支持catch子句类型标注为any或unknown数据边界数组遍历使用ForEach组件当数组为空时自动不渲染内容2.6 设计可行性验证在架构设计完成后我们进行了技术可行性验证确认以下关键点均可行✅ ArkTS的State装饰器支持Recordstring, Object类型的状态变量✅ ArkUI的ForEach组件支持string[]数组的遍历渲染✅router.pushUrl和router.back()API在HarmonyOS中运行正常✅ ArkTS类支持带构造函数的class定义已在Model中验证✅ 条件渲染if表达式在ArkUI中工作正常三、原子化阶段Atomize任务分解与工作量评估在架构设计确认后我们将开发任务分解为以下可独立执行、可验证的原子任务。3.1 任务分解任务1数据模型层Model实现文件AI单词记忆卡Model.ets子任务1.1 定义AI单词记忆卡Data类包含所有字段声明1.2 实现构造函数完成字段初始化1.3 处理数组类型字段cards、collocations的默认值预估工时0.5小时验收标准类定义完整所有字段类型正确构造函数完成字段初始化文件编译通过无语法错误任务2业务逻辑层Service实现文件AI单词记忆卡Service.ets子任务2.1 导入Model层依赖2.2 定义AI单词记忆卡Service类2.3 实现generateData方法接收Recordstring, Object类型输入2.4 实现Mock数据生成逻辑2.5 返回AI单词记忆卡Data类型实例预估工时1小时验收标准方法签名正确参数和返回值类型匹配Mock数据生成逻辑完整文件编译通过任务3页面视图层Page实现文件AI单词记忆卡Page.ets子任务3.1 导入Model、Service依赖及router模块3.2 定义页面组件结构声明State状态变量3.3 实例化Service对象3.4 实现顶部导航栏返回按钮 标题 装饰图标3.5 实现输入区域单词列表输入框 记忆方法输入框3.6 实现生成记忆卡按钮及点击事件绑定3.7 实现结果展示区域条件渲染 逐字段展示3.8 美化UI样式颜色、圆角、间距、字体等预估工时3小时验收标准页面布局完整输入区、按钮、结果区功能正常点击按钮可触发Service调用并展示结果返回按钮可正确导航回主页面UI样式符合设计规范任务4应用注册与路由配置子任务4.1 在apps.json中注册AI单词记忆卡应用项4.2 确认路由路径与文件路径一致预估工时0.5小时验收标准主页面网格中可看到AI单词记忆卡入口点击卡片可正确跳转到详情页任务5代码审查与测试子任务5.1 ArkTS语法合规性审查对照语法约束清单5.2 功能测试输入→生成→展示全流程5.3 边界测试空输入、特殊字符输入预估工时1小时验收标准无ArkTS语法违规功能流程完整可用边界情况处理合理3.2 任务依赖关系图任务1Model层 │ ▼ 任务2Service层── 依赖任务1 │ ▼ 任务3Page层── 依赖任务1、任务2 │ ▼ 任务4路由配置── 依赖任务3 │ ▼ 任务5审查测试── 依赖任务1~43.3 工作量汇总任务预估工时复杂度关键产出任务1Model层0.5h★☆☆☆☆AI单词记忆卡Data类任务2Service层1h★★☆☆☆业务逻辑实现任务3Page层3h★★★★☆完整UI页面任务4路由配置0.5h★☆☆☆☆应用注册任务5审查测试1h★★☆☆☆质量保障合计6h——四、审批阶段Approve质量门控与审核确认在进入编码阶段之前我们对前面阶段的产出一一进行了审核确认确保每个环节的质量达标。4.1 ALIGNMENT文档审核审核项状态说明项目背景清晰✅ 通过明确了AI单词记忆卡的定位和目标用户技术栈明确✅ 通过ArkTS ArkUI HarmonyOS功能需求完整✅ 通过覆盖输入、生成、展示全流程边界条件清晰✅ 通过明确了本次开发使用Mock数据ArkTS约束清单✅ 通过已逐条确认规避了所有不支持的特性4.2 架构设计审核审核项状态说明架构图清晰准确✅ 通过三层架构职责明确接口定义完整✅ 通过Model、Service、Page接口均已定义与现有系统一致✅ 通过沿用已有PageModelService模式设计可行性验证✅ 通过关键API和语法已验证无过度设计✅ 通过仅实现当前需求无超前设计4.3 任务分解审核审核项状态说明任务粒度合理✅ 通过每个任务可在1~3小时内完成依赖关系正确✅ 通过依赖图逻辑正确验收标准明确✅ 通过每个任务有具体可验证的标准工作量合理✅ 通过总计6小时符合预期4.4 质量门控确认在进入编码阶段前我们确认以下质量门控条件已满足需求边界清晰无歧义✅ — 功能范围、输入输出均已明确技术方案与现有架构对齐✅ — 沿用项目已有的三层架构模式验收标准具体可测试✅ — 每项标准均可通过编译检查或功能测试验证所有关键假设已确认✅ — Mock数据方案已确认项目特性规范已对齐✅ — ArkTS语法约束清单已对齐五、自动化执行阶段Automate编码实现与细节剖析5.1 数据模型层实现Model数据模型层是整个应用的地基它定义了记忆卡片的数据结构。在AI单词记忆卡Model.ets中我们定义了一个包含13个字段的类。// 文件路径entry/src/main/ets/apps/AI单词记忆卡/AI单词记忆卡Model.etsexportclassAI单词记忆卡Data{cards:string[][]word:stringphonetic:stringpos:stringmeaning:stringroot:stringmnemonic:stringexample:stringcollocations:string[][]review_plan:stringgrouping:stringtips:stringconstructor(){this.cards[]this.wordthis.phoneticthis.posthis.meaningthis.rootthis.mnemonicthis.examplethis.collocations[]this.review_planthis.groupingthis.tips}}设计要点字段默认值所有字段在声明时即赋予默认值string类型默认为空字符串string[]类型默认为空数组[]这符合ArkTS使用带初始化的声明规范避免了使用let v!: T的确定性赋值断言。构造函数初始化虽然字段声明时已赋值构造函数中仍然显式进行了初始化。这是为了确保new AI单词记忆卡Data()构造出的实例字段状态清晰可预期也是一种防御性编程实践。数组类型字段cards和collocations是string[]数组类型对应ArkTS中不支持索引签名请改用数组的约束。在UI层我们将使用ForEach组件遍历这两个数组进行渲染。export关键字类使用export导出以便Page层和Service层通过import引用。这符合ArkTS不支持UMD请使用export和import语法的规范。5.2 业务逻辑层实现Service业务逻辑层是应用的核心处理单元负责接收Page层的输入参数进行数据处理并返回结构化的数据模型。在AI单词记忆卡Service.ets中我们实现了完整的服务类。// 文件路径entry/src/main/ets/apps/AI单词记忆卡/AI单词记忆卡Service.etsimport{AI单词记忆卡Data}from./AI单词记忆卡ModelexportclassAI单词记忆卡Service{privatemodel:AI单词记忆卡Dataconstructor(){this.modelnewAI单词记忆卡Data()}// 生成AI单词记忆卡数据generateData(input:Recordstring,Object):AI单词记忆卡Data{letresult:AI单词记忆卡DatanewAI单词记忆卡Data()// Mock data generation based on inputletwordsVal:stringString(input[words]||)result.cards[示例数据1,示例数据2,示例数据3]result.review_plan生成结果wordsVal result.grouping生成结果wordsVal result.tips生成结果wordsValreturnresult}}设计要点私有成员变量private model: AI单词记忆卡Data是Service类的内部状态用于持有数据模型实例。在ArkTS中不支持以#符号开头的私有标识符需使用private关键字替代。方法签名generateData方法接收Recordstring, Object类型参数返回AI单词记忆卡Data类型。这里的Recordstring, Object是ArkTS支持的泛型工具类型之一与Partial、Required、Readonly一样是少数被支持的TS实用类型。Mock数据策略目前Service层返回的是模拟数据这是在没有接入真实AI API情况下的合理策略。当后续接入真实AI模型时只需在generateData方法中将Mock逻辑替换为API调用逻辑即可Page层和Model层无需任何改动。类型转换String(input[words] || )展示了如何在ArkTS中安全地处理可能为undefined的值。由于Recordstring, Object的索引访问可能返回undefined这里使用|| 提供默认值再用String()进行显式类型转换。5.3 页面视图层实现Page页面视图层是用户直接交互的界面也是代码量最大的部分。在AI单词记忆卡Page.ets中我们实现了完整的UI交互逻辑。// 文件路径entry/src/main/ets/apps/AI单词记忆卡/AI单词记忆卡Page.etsimport{AI单词记忆卡Data}from./AI单词记忆卡Modelimport{AI单词记忆卡Service}from./AI单词记忆卡Serviceimport{router}fromkit.ArkUIEntryComponentstructAI单词记忆卡Page{StateinputData:Recordstring,Object{}StateresultData:AI单词记忆卡Data|nullnullStateshowResult:booleanfalseprivateservice:AI单词记忆卡ServicenewAI单词记忆卡Service()build(){// 页面构建逻辑}}5.3.1 状态变量与装饰器ArkUI的声明式编程模型核心在于装饰器机制。我们使用了以下关键装饰器Entry标记当前组件为页面入口使其可以被路由导航到Component标记当前struct为ArkUI组件使其具备生命周期和构建能力State标记状态变量当变量值变化时自动触发UI重新渲染三个状态变量的设计各有侧重inputData收集用户输入使用Recordstring, Object类型以支持灵活的键值对存储resultData存储Service返回的结果声明为AI单词记忆卡Data | null联合类型在未生成数据时为nullshowResult布尔类型开关控制结果区域的显示/隐藏5.3.2 顶部导航栏实现Row(){Text(← 返回).fontSize(13).fontColor(#6D28D9).onClick((){router.back()})Blank()Column(){Text( AI单词记忆卡).fontSize(17).fontWeight(FontWeight.Bold).fontColor(#4C1D95)Text(FLASHCARD · 记忆卡).fontSize(9).fontColor(#7C3AED).margin({top:2})}Blank()Text().fontSize(22)}.width(100%).padding({left:20,right:20,top:16,bottom:14}).backgroundColor(#F5F3FF)设计要点布局对称使用Blank()组件将标题居中左侧为返回按钮右侧为装饰图标形成对称的视觉平衡返回导航router.back()是HarmonyOS的标准返回API无需手动管理页面栈层级标题主标题使用17号字体加粗副标题使用9号字体浅色形成视觉层次感品牌色系采用紫色系#6D28D9、#4C1D95、#7C3AED与AI 学习的产品调性一致5.3.3 输入区域实现Column(){Text( 单词列表).fontSize(11).fontColor(#6D28D9).margin({top:6,bottom:3})TextInput({placeholder:请输入单词列表}).fontSize(13).height(40).backgroundColor(#FFFFFF).borderRadius(8).border({width:1,color:#C4B5FD}).padding({left:12,right:12}).onChange((val:string){this.inputData[单词列表]val})Text( 记忆方法).fontSize(11).fontColor(#6D28D9).margin({top:6,bottom:3})TextInput({placeholder:请输入记忆方法}).fontSize(13).height(40).backgroundColor(#FFFFFF).borderRadius(8).border({width:1,color:#C4B5FD}).padding({left:12,right:12}).onChange((val:string){this.inputData[记忆方法]val})}.width(100%).padding(18).backgroundColor(#FFFFFF).borderRadius(8).border({width:1,color:#DDD6FE}).margin({top:6})设计要点TextInput组件ArkUI的TextInput是标准的文本输入组件支持placeholder占位符、onChange回调等属性数据收集通过onChange回调将用户输入实时写入inputData对