【寻迹校园 HarmonyOS NEXT 实战 06】共享权威词表让发布表单与首页筛选使用同一套分类这是“寻迹校园 HarmonyOS NEXT 实战”系列第 6 篇。本文结合ReportTaxonomy.ets说明 HarmonyOS NEXT 应用如何用稳定内部值、展示标签和筛选关键词建立共享权威词表避免发布、筛选和旧数据回显互相打架。上图为本文原创生成的词表治理概念图不是项目截图。它强调一个核心事实页面可以有不同文案但分类和区域的业务含义只能有一个权威来源。一、同一个地点为什么会出现三种写法校园失物招领看起来只是填写分类和地点实际很容易产生数据漂移。例如同一个位置可能同时出现发布页保存“第一教学楼附近”首页筛选按钮显示“第一教学楼”匹配规则使用“第一教学楼”做包含判断旧版本数据里还保存过“教学一号楼”。如果每个页面各维护一份字符串数组短期能运行后续会出现三个问题发布记录无法被筛选命中、旧记录无法正确回显、修改文案时必须同时寻找多个页面。解决方案不是在每次比较前堆更多if而是建立共享权威词表让“展示给用户的名称”“真正写入数据的稳定值”和“用于模糊筛选的关键词”各司其职。二、稳定值、展示标签和筛选关键词不能混为一谈项目为区域定义了一个简单模型exportclassReportAreaOption{label:string;value:string;filterKeyword:string;constructor(label:string,value:string,filterKeyword:string){this.labellabel;this.valuevalue;this.filterKeywordfilterKeyword;}}三个字段分别解决不同问题字段责任示例label页面按钮与筛选项展示第一教学楼value发布记录真正保存的值第一教学楼附近filterKeyword首页模糊筛选和旧文本兼容第一教学楼如果把三个概念压成一个字符串文案调整就会变成数据迁移。把它们拆开后页面可以显示更简洁的名称业务数据仍保留足够语义筛选也不必要求完全相等。三、9 类物品和 7 个区域只定义一次“寻迹校园”当前单校演示词表包含 9 个物品分类箱包、证卡、数码、钥匙、衣物、雨具、水杯、书籍和其他。区域词表包含 7 个入口第一教学楼、图书馆、体育馆、食堂、保卫处、宿舍区和其他区域。真实代码集中在common-coreexportconstREPORT_CATEGORY_OPTIONS:string[][箱包,证卡,数码,钥匙,衣物,雨具,水杯,书籍,其他];exportconstREPORT_AREA_OPTIONS:ReportAreaOption[][newReportAreaOption(第一教学楼,第一教学楼附近,第一教学楼),newReportAreaOption(图书馆,图书馆服务台,图书馆),newReportAreaOption(体育馆,体育馆入口,体育馆),newReportAreaOption(食堂,食堂二楼,食堂),newReportAreaOption(保卫处,保卫处失物招领点,保卫处),newReportAreaOption(宿舍区,宿舍区服务站,宿舍区),newReportAreaOption(其他区域,其他校内区域,其他)];词表放在common-core而不是某个页面中是因为发布页、首页筛选、匹配规则和测试都需要引用它。它属于跨模块业务契约不属于任何单一 UI。四、发布页保存 value首页筛选使用 filterKeyword发布页为用户展示label选中后写入valueprivateareaOption(option:ReportAreaOption){Button(option.label).onClick((){this.areaoption.value;this.validationnewPublishValidation();})}首页筛选则复制同一份REPORT_AREA_OPTIONS读取filterKeyword构造查询。这样“图书馆服务台”能够被“图书馆”筛选命中而页面不需要知道发布页保存了什么长文案。这也是稳定键和值的重要区别用户看到的是可调整文案业务判断依赖的是稳定数据含义。上图展示从发布选择、稳定值保存到首页筛选命中的映射链。每次修改词表时应该沿这条链检查展示、存储、筛选和历史记录而不是只看当前页面按钮。五、旧数据不能因为词表升级而消失共享词表上线前设备里可能已经存在自定义值或旧版本区域。编辑这些记录时如果下拉项只渲染新词表旧值会无法选中用户甚至会误以为数据丢失。项目的兼容方式是先复制权威选项再把当前记录中不存在于新词表的值追加为临时保留项。privateareaOptions():ReportAreaOption[]{constoptions:ReportAreaOption[][];REPORT_AREA_OPTIONS.forEach((option:ReportAreaOption)options.push(option));if(this.area.trim().length0!options.some((option:ReportAreaOption)option.valuethis.area)){options.push(newReportAreaOption(保留${this.area},this.area,this.area));}returnoptions;}分类也采用相同策略当前值不在 9 类权威分类中时把它追加到页面可选项。这样可以做到“新数据使用新词表旧数据仍可读取和编辑”避免一次 UI 调整破坏历史数据。六、为什么不要在页面里复制数组页面内复制词表通常会留下这些隐患发布页新增“雨具”首页筛选忘记增加一个页面写“数码产品”另一个页面写“数码”测试使用第三份硬编码数据全部通过但真实页面不一致旧值兼容只在编辑页处理详情页仍显示空白多模块项目出现循环依赖被迫从页面反向导入常量。正确的依赖方向应该是entry页面依赖common-core词表Service 和纯规则同样依赖common-core但common-core永远不依赖页面。七、词表治理还需要哪些验证仅仅把数组挪到公共文件还不够。一次词表变更至少要验证发布页的分类和区域按钮数量正确选中区域后保存的是value不是label首页筛选使用filterKeyword能够命中更长的保存值编辑旧记录时未知分类与区域仍能回显匹配规则不会把“其他区域”当成高置信相同地点空值、长文本和旧版本脏数据有兜底单元测试直接导入权威词表而不是复制期望数组。这些检查比“页面上看起来一致”更可靠因为它们覆盖了写入、读取、筛选和升级四个方向。八、跨校版本不能继续把校园字典写死当前 9 类物品和 7 个区域适合单校比赛演示但不能直接包装成通用校园平台。不同学校的校区、楼栋、服务台和命名方式差异很大。跨校版本至少需要引入campusId和校区维度可版本化的校园区域字典服务端或配置包下发旧版本字典迁移策略离线缓存和失效时间管理端审核避免任意地点进入公共词表。因此本文描述的是当前单机应用的权威词表设计不宣称已经具备跨校配置中心。九、用户视角下的直接收益词表治理看似是代码整洁问题实际会直接影响用户发布后能否被搜索到、编辑旧记录时是否丢值、筛选按钮是否能稳定命中、匹配理由是否使用用户理解的区域名称。共享权威词表把这些体验从“多个页面碰巧一致”变成可测试契约也让后续增加分类、调整文案和升级数据时有明确影响范围。十、一次词表变更需要做影响分析共享词表集中之后修改入口变少了但一次改动的影响范围反而更应该写清楚。以“图书馆”更名为“中心图书馆”为例不能只修改按钮文字还要判断这是展示调整、搜索关键词扩充还是存储值迁移。三种改动对应的风险完全不同。变更类型可以直接修改的内容必须额外检查的内容仅优化展示文案label小屏截断、无障碍朗读、设计稿文案扩充搜索命中范围filterKeyword或别名集合误命中、性能、历史记录检索修改持久化含义value旧数据迁移、回滚、统计口径、跨版本兼容删除分类或区域新数据入口旧记录回显、编辑保存、详情页兜底实际开发中可以把每次词表变更写成一个小型影响单变更原因、旧值、新值、读取方、写入方、迁移策略、回滚方式和验收场景。这样代码审查者看到的不只是“数组改了一行”而是完整的数据契约变化。十一、迁移、回滚与脏数据处理如果只是调整label通常不需要迁移数据库如果要替换value则必须先确认设备中是否已经存在旧值。稳妥流程是先让新版本同时识别新旧值再把新发布记录写成新值最后在有充分验证后逐步迁移历史数据。直接删除旧值会让用户已经发布的记录变成无法筛选的孤岛。回滚同样不能只恢复代码。假设新版本已经写入“中心图书馆服务台”旧版本却只认识“图书馆服务台”应用降级后仍可能出现未知值。因此回滚方案要么保证旧版本可以通过“保留当前值”路径展示要么在数据迁移时保留可逆映射。对于比赛演示项目即使没有复杂数据库迁移脚本也应把这个边界写进测试和交付说明。脏数据处理还应区分空字符串、前后空格、未知分类、未知区域和过长自定义文本。页面负责给出友好提示Service 负责最终校验Repository 负责读取失败和默认值兜底。不要在 UI 中悄悄把未知值改成“其他”因为这会改变用户原始记录的含义。十二、团队协作和可追踪验收多人协作时权威词表的改动应该由一个明确模块负责页面需求不能各自复制常量“先做出来”。代码审查至少要回答是否新增了稳定值、是否影响旧记录、筛选是否仍能命中、是否需要修改测试、是否改变了单校演示边界。只有展示文案变化时也要确认没有误改value。交付验收可以使用用户语言而不是只写“常量已抽取”用户在发布页选择“图书馆”后保存并返回首页能够被“图书馆”筛选命中旧版本保存的自定义地点进入编辑页后仍能看到原值不会被自动清空新增分类在发布、详情、筛选和匹配说明中采用一致名称删除入口后历史记录仍可读取且用户知道它属于保留数据应用重启后再次查询结果与保存前一致不依赖页面内存状态。这些验收语句把技术实现与真实体验连接起来也便于后续定位问题究竟发生在展示、写入、读取还是筛选阶段。十三、本文小结在 HarmonyOS NEXT 多模块项目中分类和区域不是普通页面常量而是写入、筛选、匹配和历史兼容共同依赖的业务契约。label / value / filterKeyword的拆分让展示、存储和搜索各自稳定common-core统一持有词表页面只消费旧值通过临时保留项继续回显。下一篇将继续解决另一个跨页面问题不引入全局状态库如何用dataRevision让首页、消息和“我的发布”重新读取权威数据。系列导航第 6 篇 / 共 50 篇。上一篇《Page → Service → Repository》下一篇《用 dataRevision 实现跨页面刷新信号》。