生词本管理——NewWordManager 的增删改查设计引言在英语学习应用中生词本是一个核心功能模块。用户在学习过程中遇到的生词需要能够方便地收藏、归类、复习并追踪掌握程度。如果设计不当生词本很容易变成收藏即遗忘的死角。本文将以NewWordManager的实现为例展示如何构建一个结构清晰、功能完备的生词本管理模块。一、数据模型设计生词本的核心是NewWordItem数据结构它需要记录生词本身的信息、学习状态和元数据exportinterfaceNewWordItem{keyID:string// 唯一标识用于去重和检索title:string// 单词/词组type:string// 题型类型1:单词拼写 2:听力 等phonetic:string// 音标partOfSpeech:string// 词性example:string// 例句exampleTranslation:string// 例句翻译audioUrl:string// 读音 URLaddTime:number// 添加时间戳masteryLevel:number// 掌握程度0-未掌握 1-熟悉 2-掌握wordPackage:string// 所属词汇包}关键设计决策keyID为主键与题目系统中的TopicItemType.keyID对应确保唯一性。masteryLevel三级制简化掌握程度模型避免过于复杂的记忆曲线计算。wordPackage分类维度支持按词汇包筛选方便用户分类管理。二、单例模式 CRUD 架构NewWordManager采用经典的单例模式通过PreferenceUtil进行数据持久化exportclassNewWordManager{privatestaticinstance?:NewWordManager;privateNEW_WORD_KEYNEW_WORDS;privateconstructor(){}publicstaticgetInstance():NewWordManager{if(!NewWordManager.instance){NewWordManager.instancenewNewWordManager();}returnNewWordManager.instance;}privatesaveNewWords(words:NewWordItem[]):void{PreferenceUtil.getInstance().put(this.NEW_WORD_KEY,words);}}所有数据通过NEW_WORD_KEY存储在PreferenceUtil的默认文件中。saveNewWords作为私有方法封装了写入细节对外只暴露语义化的 CRUD 方法。三、增Create去重添加添加生词时最关键的是去重检查——避免同一单词被重复收藏publicaddNewWord(topicItem:TopicItemType,wordPackage:string默认词汇包):boolean{try{letwords:NewWordItem[]this.getAllNewWords();// 去重检查letexistIndexwords.findIndex(itemitem.keyIDtopicItem.keyID);if(existIndex0){// 已存在则更新添加时间words[existIndex].addTimeDate.now();this.saveNewWords(words);Logger.info(NewWordManager,生词已存在更新时间:${topicItem.keyID});returnfalse;// 返回 false 表示已存在非新增}// 构建新词条letnewWord:NewWordItem{keyID:topicItem.keyID,title:topicItem.title,type:topicItem.type,phonetic:topicItem.ques?.[0]?.phonetic||,partOfSpeech:topicItem.ques?.[0]?.partOfSpeech||,example:topicItem.ques?.[0]?.example||,exampleTranslation:topicItem.ques?.[0]?.exampleTranslation||,audioUrl:topicItem.audioUrl||,addTime:Date.now(),masteryLevel:0,// 默认未掌握wordPackage:wordPackage};words.push(newWord);this.saveNewWords(words);Logger.info(NewWordManager,添加生词成功:${topicItem.title});returntrue;}catch(e){Logger.error(NewWordManager,添加生词失败:${JSON.stringify(e)});returnfalse;}}设计亮点幂等性如果生词已存在不会重复添加而是更新addTime以置顶该词条。默认值兜底topicItem.ques?.[0]?.phonetic || 链式可选访问确保数据不缺失。返回值语义true表示新增成功false表示已存在。四、查Retrieve多维查询// 获取所有生词publicgetAllNewWords():NewWordItem[]{try{letwordsPreferenceUtil.getInstance().get(this.NEW_WORD_KEY,[])asNewWordItem[];returnwords||[];}catch(e){Logger.error(NewWordManager,获取生词列表失败:${JSON.stringify(e)});return[];}}// 按词汇包筛选publicgetNewWordsByPackage(wordPackage:string):NewWordItem[]{try{letwordsthis.getAllNewWords();if(!wordPackage||wordPackage全部){returnwords;}returnwords.filter(itemitem.wordPackagewordPackage);}catch(e){Logger.error(NewWordManager,筛选生词失败:${JSON.stringify(e)});return[];}}// 获取生词数量publicgetNewWordCount():number{returnthis.getAllNewWords().length;}// 检查是否为生词publicisNewWord(keyID:string):boolean{letwordsthis.getAllNewWords();returnwords.some(itemitem.keyIDkeyID);}// 获取所有词汇包名称列表publicgetAllWordPackages():string[]{try{letwordsthis.getAllNewWords();letpackagesnewSetstring();packages.add(全部);words.forEach(item{packages.add(item.wordPackage);});returnArray.from(packages);}catch(e){Logger.error(NewWordManager,获取词汇包列表失败:${JSON.stringify(e)});return[全部];}}查询方法丰富多样getAllNewWords全量查询支持 UI 列表展示排序逻辑。getNewWordsByPackage按词汇包筛选使用filter实现支持全部快捷查询。isNewWord快速判断使用some提前终止遍历。getAllWordPackages使用Set自动去重动态生成分类过滤列表。五、改Update掌握度更新publicupdateMasteryLevel(keyID:string,masteryLevel:number):boolean{try{letwords:NewWordItem[]this.getAllNewWords();letindexwords.findIndex(itemitem.keyIDkeyID);if(index0){words[index].masteryLevelmasteryLevel;this.saveNewWords(words);Logger.info(NewWordManager,更新掌握程度:${keyID}-${masteryLevel});returntrue;}returnfalse;// 词不存在}catch(e){Logger.error(NewWordManager,更新掌握程度失败:${JSON.stringify(e)});returnfalse;}}更新操作采用读取 → 修改 → 全量写回的模式。这是因为 Preferences 是键值存储不支持部分字段更新——我们需要将整个数组读出修改目标项再整体写回。六、删Delete单条删除与清空// 单条删除publicremoveNewWord(keyID:string):boolean{try{letwords:NewWordItem[]this.getAllNewWords();letnewWordswords.filter(itemitem.keyID!keyID);this.saveNewWords(newWords);Logger.info(NewWordManager,移除生词成功:${keyID});returntrue;}catch(e){Logger.error(NewWordManager,移除生词失败:${JSON.stringify(e)});returnfalse;}}// 清空所有publicclearAllNewWords():boolean{try{PreferenceUtil.getInstance().put(this.NEW_WORD_KEY,[]);Logger.info(NewWordManager,清空生词本成功);returntrue;}catch(e){Logger.error(NewWordManager,清空生词本失败:${JSON.stringify(e)});returnfalse;}}删除操作的两种粒度removeNewWord使用filter生成新数组不可变操作不修改原数组。clearAllNewWords直接写入空数组效率最高。七、最佳实践7.1 全量读写的权衡在 Preferences 这样的键值存储中生词列表是以数组形式整体存储的。当生词数量增大时如超过 1000 条全量读写的性能会下降。对于大规模数据建议考虑迁移到关系型数据库如kit.ArkData的 relationalStore。7.2 返回值设计原则所有操作方法统一返回boolean调用方可以据此判断操作结果并给出用户反馈letaddedNewWordManager.getInstance().addNewWord(topicItem);if(added){showToast(已添加到生词本);}else{showToast(该词已在生词本中);}7.3 日志埋点每个关键操作都包含Logger.info/error日志方便调试和用户行为分析。生产环境中可以通过日志平台聚合分析用户添加/删除生词的行为模式。八、总结NewWordManager展示了如何在 HarmonyOS 应用中构建一个具备完整 CRUD 能力的业务 Manager。它通过单例模式管理状态通过PreferenceUtil完成持久化通过清晰的接口设计提供生词的增删改查功能。这种Manager Preferences的轻量级存储模式非常适合小规模业务数据的持久化场景是 HarmonyOS 应用开发中的经典实践。