本文中的项目、包列表、页面状态及日志均为人为设计的演示数据；配图属于独立绘制的技术示意，不是 DevEco Studio 实际运行结果，也不代表真机播放测试。
一、语种没变，选择器为什么跳到了日语
有一次整理语音导览的设置页面，我遇到一种特别容易被当成“小概率 UI 抖动”的问题：用户原来选的是英语，运营删除了一款暂时不可用的粤语语音包，页面刷新后，旋转选择器却高亮了日语。用户完全没有进行第二次选择，设置页自己把含义变了。第一次看日志时，记录里只有一个整型下标，数据库里甚至没有保存“英语”两个字，因此错误很难追到源头。
根因并不神秘。旧目录按照普通话、粤语、英语、日语排列，英语位于索引 2；新目录移除了粤语，英语变成索引 1，而索引 2 现在表示日语。下标是当前列表的坐标，不是用户选择的业务身份。把下标当作偏好保存，一旦服务端做增删、排序或者语言包灰度下线，界面就可能悄悄改变用户意图。
这次把问题收敛到VoiceShelf演示项目的VoicePackPage，任务编号VS-2301。不接入真实语音合成，也不声称存在任何播放完成的回执；我们只验证本地语种目录变化时，TextPicker 能否把“英语”稳定映射回来。第一张图使用青绿与米白的杂志式封面，强调“选中项身份”和“显示位置”的区别。
二、先订一个不会被下标带偏的数据合同
目前只需要四种语音包：zh_CN对应普通话，yue对应粤语，en对应英语，ja对应日语。第一版目录的修订号为 1，用户已确认的语种 ID 是en，当时的可见索引是 2。第二版目录将yue下架，修订号升到 2；合法目录变为普通话、英语、日语。此时语种仍然是en，下标应重新计算为 1。
业务上应当长期保存稳定 ID，而不能保存中文显示名。显示名可能多语言翻译，也可能被运营改成“英文”或“英语（标准）”。对于这个范围有限的 Demo，id是静态约定的短字符串；真实产品还需要接入语音资源包的发布状态、资源版本和离线文件存在性。TextPicker 只负责给出候选位置，不承担这些业务事实的判断。
先用最小的数据结构建立“以 ID 找位置”的函数。它不依赖 UI 组件，也不需要系统权限，适合在单元测试里喂入不同顺序的目录。
interface VoicePack { id: string label: string } function indexOfPack(packs: VoicePack[], packId: string): number { const found: number = packs.findIndex((p: VoicePack) => p.id === packId) return found >= 0 ? found : 0 } const VOICE_PACKS_V1: VoicePack[] = [ { id: 'zh_CN', label: '普通话' }, { id: 'yue', label: '粤语' }, { id: 'en', label: '英语' }, { id: 'ja', label: '日语' } ] const VOICE_PACKS_V2: VoicePack[] = [ { id: 'zh_CN', label: '普通话' }, { id: 'en', label: '英语' }, { id: 'ja', label: '日语' } ]这里的回退到 0 不是通用的推荐做法，而是 Demo 明确约定“普通话始终存在”的结果。实际产品如允许整个目录变空，就应该切到“暂无可用包”空态并禁用提交，不能在空数组上强行访问第零项。更重要的是，在回退发生后必须给用户提示，不能静默把一种语音变成另一种。数据合同里还要有修订号，避免较旧的目录更新重新写回当前界面。
三、把确认值、草稿值、目录修订号拆开
第二个常见误区是把滑动回调直接写入偏好存储。用户只是滚过一个选项，尚未点击确认；若此时路由关闭或者目录变化，草稿应当能够恢复。我的处理方式是把confirmedId和draftId分开：前者是已提交偏好，后者是页面当前临时意图。只有执行确认操作且目标仍在当前目录，才能把草稿提交到确认值。
以下会话对象只保存轻量字符串与数组，不持有媒体播放器和网络请求。applyCatalog()负责把目录变更映射到新位置，同时拒绝旧修订号。这样，即便运营系统迟到地推送修订 1，也不会覆盖已经显示的修订 2。
class VoicePackDraft { private packs: VoicePack[] = VOICE_PACKS_V1.slice() private revision: number = 1 private confirmedId: string = 'en' private draftId: string = 'en' getRevision(): number { return this.revision } getPacks(): VoicePack[] { return this.packs.slice() } getConfirmedId(): string { return this.confirmedId } getDraftId(): string { return this.draftId } getIndex(): number { return indexOfPack(this.packs, this.draftId) } choose(index: number): void { if (index < 0 || index >= this.packs.length) { return } this.draftId = this.packs[index].id } applyCatalog(revision: number, next: VoicePack[]): boolean { if (revision <= this.revision || next.length === 0) { return false } this.packs = next.slice() this.revision = revision if (!this.packs.some((p: VoicePack) => p.id === this.draftId)) { this.draftId = this.packs[0].id } return true } cancel(): void { this.draftId = this.confirmedId } confirm(): boolean { if (!this.packs.some((p: VoicePack) => p.id === this.draftId)) { return false } this.confirmedId = this.draftId return true } }这段代码刻意让状态规则与视图分离。目录变更后，界面通过getIndex()重新求值，而不是沿用旧的 2。注意cancel()只是恢复草稿；如果先前已确认的语种后来也被下架，还要额外定义“已确认资源不可用”的产品策略。本文的演示只下架yue，已确认的en仍可用，因此不会触发这一分支。
释放方面，这个对象没有文件描述符、定时器或监听器，不需要虚构一个dispose()才显得完整。不过页面关闭时可以执行cancel()，避免再次展示时继续使用未确认的选择。异步目录若来自远端，则需要在页面层另外处理取消订阅、生命周期标志与网络异常，不能把这里的同步类误当成全栈同步方案。
四、TextPicker 只接收当前可用目录
华为官方 TextPicker API 文档给出了range、selectedIndex和onChange。其中单列range可以是字符串数组；onChange回调的index类型覆盖单列数字与多列数字数组。这里明确只做单列，避免把多列签名偷换成单列专用类型。官方还提示，动态变更时不要改变range类型和列数，空数组的显示行为也与我们希望的“空态禁用提交”不同，所以业务模型必须先挡住非法目录。
在VoicePackPage中，目录更新后同时回写当前标签数组和重新计算的索引。为避免出现旧标签与新索引混搭，两个界面状态由同一个会话对象一次性导出。在工程里，这里可以进一步用不可变快照包装，本文保留能看清状态流向的写法。
@Entry @Component struct VoicePackPage { private draft: VoicePackDraft = new VoicePackDraft() @State private labels: string[] = ['普通话', '粤语', '英语', '日语'] @State private selectedIndex: number = 2 @State private status: string = '已确认 · 英语' private syncView(): void { this.labels = this.draft.getPacks().map((p: VoicePack) => p.label) this.selectedIndex = this.draft.getIndex() } private updateToRevision2(): void { if (!this.draft.applyCatalog(2, VOICE_PACKS_V2)) { return } this.syncView() this.status = '修订 2 · 保留英语' } private commit(): void { if (!this.draft.confirm()) { this.status = '确认失败 · 语种已不可用' return } this.status = '已确认 · 英语' console.info('[DEMO] VoiceShelf VS-2301 revision=2 draft=en index=1 status=CONFIRMED') } aboutToDisappear(): void { this.draft.cancel() } build() { Column({ space: 22 }) { Text('VoiceShelf · 语音包设置').fontSize(26).fontWeight(FontWeight.Bold) Text('任务 VS-2301 · 修订 2').fontSize(15) TextPicker({ range: this.labels }) .selectedIndex(this.selectedIndex) .onChange((value: string | string[], index: number | number[]) => { if (typeof index !== 'number') { return } this.draft.choose(index) this.selectedIndex = this.draft.getIndex() this.status = '待确认 · ' + String(value) }) Button('模拟下架粤语').onClick(() => this.updateToRevision2()) Button('确认语种').onClick(() => this.commit()) Text(this.status).fontSize(16) }.padding(24).width('100%') } }此处代码用于说明结构与边界，未经过目标 SDK 编译。真实项目应把“修订 2”文案由状态计算，不能在任何修订号下都写死 2；commit()中的日志同样是约定场景下的演示行，不是实际 HiLog 的采样结果。代码里的按钮故意叫“模拟下架粤语”，读者不会把它误解为真实运营动作。
五、拿索引故障做一次可解释的验收
按约定序列检查：打开页面时修订 1、英语en、索引 2；点击“模拟下架粤语”后修订 2，候选顺序变成普通话、英语、日语；此时getIndex()返回 1，草稿 ID 依然是en。再点击“确认语种”，界面状态应显示“已确认 · 英语”。本轮三张图都固定使用任务VS-2301、修订 2、语种en、索引 1，不借用其他文章的数字。
手机纯屏演示图保留了时间、5G、Wi-Fi、信号和电量图标，页面顶部有“演示界面”标签。它画的是状态合同满足时应该呈现的页面，不是录屏抓帧，也不能用来宣称播放功能正常。
我会特别验证两个反例：同样的下架操作重复发送修订 2，不应该再次改写选择；迟到的修订 1 应被拒绝，不能把粤语插回去。若将英语本身从下一版目录删除，则当前回退策略只会把草稿指向普通话，界面必须明确提醒用户重新确认，这时不能沿用“已确认 · 英语”的正常态。正式产品需要覆盖这个分支，而不是只给顺利场景拍图。
六、为什么不直接绑定中文标签
有人可能会觉得，把selected设置成“英语”，总不至于变成“日语”吧。问题是显示词并非业务主键。语言包的名称可能随本地化改变，两个不同音色也可能有同一个语种名称。把持久化 ID 与屏幕标签解耦，未来加入“英语·播报员A”和“英语·播报员B”时，不需要重新设计存储结构。
另外，TextPicker 的onChange发生在滑动选中后，并不等价于我们自定义页面上的“确认提交”。不能看到回调就立刻写本地偏好，更不能立刻销毁正在播报的音频对象。真实语音引擎可能存在正在播放、缓冲、可中断三个阶段，切换资源要单独制定过渡策略。本文没有调用媒体能力，故意把这些后续操作留在边界之外。
七、调试时看数据，不猜控件的心理
如果页面又出现了错误语种，我希望 HiLog 中能看到目录修订、稳定语种 ID 和派生索引三个独立字段，而不是只打印selected=2。演示行写为[DEMO] VoiceShelf VS-2301 revision=2 draft=en index=1 status=CONFIRMED。所谓[DEMO]，就是提醒任何截图使用者：这串文字是说明预期值，并非从模拟器采集到的实测性能证据。
检查顺序也变得清晰：先核对新目录是否真的移除了yue，再确认en没丢失，随后检查是否重新派生index=1，最后看确认按钮是否把草稿提交。若在第二步就发现en不存在，那是业务可用性问题，不能靠重新渲染 Picker 修复。把排障路径写成数据检查点，课程演示和工程交接都会更少扯皮。
八、当前实现的收口
这次修复最重要的不是多写一个findIndex()，而是把“用户选择的内容”和“组件当前显示位置”定义成两种状态。TextPicker 负责滑动与高亮，会话对象负责业务身份与确认，目录修订号负责拒绝倒退更新。三个职责分开后，同一个问题不必在多个页面里分别打补丁。
目前得到的是一个可以通过静态案例检查的状态方案，还不是已经在 HarmonyOS 7 真机上验收过的成品。后续接入真实语音包下载、播放与偏好持久化时，需要补上失败回退、资源卸载、页面重进和无障碍朗读等环节，尤其不能让已经被下架的已确认语种悄悄替换为另一种语言。先守住身份，再谈体验，工程风险通常会小很多。
官方资料：华为 TextPicker API（V13）。本文使用的range、selectedIndex、onChange已参考该文档，未宣称目标 SDK 编译结果。
