HarmonyOS7拼音索引多语言页实战：中文拼音索引与多语言分组处理

前言

一旦数据从英文名切到中文名，AlphabetIndexer 的事情就不只是显示 A-Z 这么简单了。拼音映射、分组归类、特殊字符处理，这些都可能冒出来。这个案例更接近真实业务。 这一页适合慢一点读，不是因为代码特别难，而是因为它里面很多决定都和真实页面很像。把这些决定看懂，比把组件名字记住更值钱。

别看这个案例篇幅不算长，但它很适合拿来练“页面目标和代码结构怎么对齐”这件事。你后面不管是复刻，还是准备拆成自己的业务组件，都会更顺。

这类写法尤其适合落在 中文通讯录、城市列表、带拼音检索的数据页 这些场景里，所以我下面不会只讲“组件怎么写”，而是更关心“放进页面之后为什么这样组织”。

别急着抄，先认结构

很多人学示例会直接复制 UI 代码，结果复刻出来是像的，但后面一改就散。原因通常不是代码抄错了，而是结构关系没先看懂。

这一页没有额外拆出接口，页面更多是直接围绕基础数据和组件参数展开。

这个案例表面看是界面效果，真正该盯的是状态怎么流动，因为大多数可复用价值都藏在这里。

这页有没有灵魂，主要看状态怎么带

中文拼音索引的关键不是“显示中文名”，而是把中文数据映射到稳定的首字母分组里。

• isShow：控制示例区域显示。
• selectedIndex：记录当前选中的拼音首字母下标。
• listScroller：负责把索引选择转换成分组列表滚动。

这里要特别注意pinyinInitials和contacts的对应关系。真实项目里如果数据来自接口，最好在入库或请求后就把拼音首字母算好，否则页面侧一边渲染一边处理拼音，后续维护会很痛苦。

时间不多的话，先盯这几个入口

示例代码里最怕被忽略的，就是那些看起来普通、实际上掌控页面节奏的方法。这里建议优先把它们摸清。

• 这个案例没有太多额外方法，核心价值主要集中在页面结构和组件组合方式。

我自己读这类方法时，通常只抓一条线：谁触发、谁被改、页面哪里立刻有反馈。把这三件事连起来，很多交互代码一下就顺了。

第一段关键代码：页面是怎么被带起来的

这一段建议慢一点看。它通常决定了页面初始状态，也决定了后续哪些区域会跟着刷新。

@StateisShow:boolean=true@StateselectedIndex:number=0privatelistScroller:Scroller=newScroller()build(){Column(){if(this.isShow){Column({space:16}){Text('中文拼音索引').fontSize(20).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR)Text('AlphabetIndexer 结合拼音首字母索引中文联系人').fontSize(13).fontColor(DEMO_SUBTEXT_COLOR).width('100%')Row(){List({scroller:this.listScroller}){ForEach(sortedKeys,(key:string)=>{ListItemGroup(){ListItem(){Text(key)

这一段我通常不会一下翻过去，而是先确认下面这几个判断点：

• @State字段到底在控制显示、选择、跳转结果还是模式切换。
• 默认值是不是合理，页面一打开会不会就落在一个可理解的状态上。
• 字段命名能不能让后来的人一眼看懂用途，而不是还要翻半天 UI。

第二段关键代码：真正决定交互手感的地方

这一段完整代码最有价值的是数据组织方式：pinyinInitials负责提供索引入口，contacts负责保存每个首字母下的中文联系人，sortedKeys再保证列表分组顺序稳定。组件只是最后一层展示，前面的分组数据才是页面能不能跑顺的关键。

/** * 拼音索引多语言页 */import{PRESET_COLORS,generateListItems,DEMO_BG_COLOR,DEMO_CARD_COLOR,DEMO_THEME_COLOR,DEMO_SUBTEXT_COLOR}from'./types'constpinyinInitials:string[]='ABCDEFGHJKLMNOPQRSTWXYZ'.split('')constcontacts:Record<string,string[]>={'A':['艾琳','安然','安琪'],'B':['白雪','白云飞','卞庄'],'C':['陈晨','崔明','曹雪'],'D':['丁丁','杜鹃','东方'],'F':['冯宝宝','方圆'],'G':['郭靖','顾清风','关羽'],'H':['黄蓉','韩梅梅','胡歌'],'J':['姜子牙','金庸','贾宝玉'],'K':['柯南','孔明'],'L':['李白','刘备','林黛玉','罗辑'],'M':['马超','马云','孟子'],'N':['倪萍','牛顿'],'P':['潘金莲','蒲松龄'],'Q':['秦始皇','钱学森','齐天大圣'],'R':['任我行','阮玲玉'],'S':['孙悟空','司马懿','苏轼','沈腾'],

代码读到这里，我通常会顺手补三件事，不然后面很容易只看热闹：

1. 这个交互入口接收的到底是什么输入。
2. 输入进来之后，代码改了哪个状态，或者触发了哪次导航。
3. 变化发生后，用户最先感知到的反馈会落在哪个区域。

这三个问题串起来之后，这一页基本就不只是“看过”，而是真的读懂了。

如果你要亲手试，顺序最好别乱

第一次接触这个案例时，不要急着扩展功能。先把默认状态和一次完整交互跑顺，后面加东西才不会歪。

1. 先进入页面，确认首屏是不是把拼音索引多语言页的主题交代清楚。
2. 盯住核心展示区，观察默认状态下最醒目的内容是什么。
3. 主动触发一次关键交互，比如点击、滑动、跳转、返回、切换或者选择。
4. 回头检查状态区、提示区、标题区或者附属信息有没有跟着变化。
5. 最后再打开源码，对照刚才那次交互，把状态变化链路串起来。

如果这五步你能边操作边说清楚页面发生了什么，后面再换成自己的数据和交互，心里会稳很多。

真放到业务里，我会先改什么

我自己迁示例代码时，最怕的是把展示逻辑和业务逻辑粘成一团。这个案例里有些地方可以提前规避。

• 字母索引类页面建议先把分组数据结构稳定下来，再去调索引条样式和反馈层。
• 一旦页面里还要加搜索、筛选或定位结果，状态来源最好先分层，不然后面很容易互相覆盖。
• 只要页面里有重复块，就别硬撑着手写到底；早点抽成小组件，后面改样式和改交互都会轻松很多。
• 示例数据最好和布局代码分开放，不然后面一接接口，页面文件很容易立刻变臃肿。

它的参考价值不只是把效果跑出来

我会把这类案例当成“工程感比炫技感更强”的材料来留存。后面真的要做同类页面时，能少走不少弯路。

• 页面结构比较稳，后续不管是换数据还是换皮肤，成本都不会特别高。
• 状态数量总体可控，适合拿来练“一个页面里如何分配职责”这件事。
• 组件参数和页面目标之间关系比较直观，不太会出现“能跑但看不懂为什么这么配”的情况。

完整代码

下面保留整理过命名的完整 ArkTS 代码，方便你直接对照学习。这里已经去掉原始的 Demo 命名，改成了更贴近当前案例语义的名称。

/** * 拼音索引多语言页 */import{PRESET_COLORS,generateListItems,DEMO_BG_COLOR,DEMO_CARD_COLOR,DEMO_THEME_COLOR,DEMO_SUBTEXT_COLOR}from'./types'constpinyinInitials:string[]='ABCDEFGHJKLMNOPQRSTWXYZ'.split('')constcontacts:Record<string,string[]>={'A':['艾琳','安然','安琪'],'B':['白雪','白云飞','卞庄'],'C':['陈晨','崔明','曹雪'],'D':['丁丁','杜鹃','东方'],'F':['冯宝宝','方圆'],'G':['郭靖','顾清风','关羽'],'H':['黄蓉','韩梅梅','胡歌'],'J':['姜子牙','金庸','贾宝玉'],'K':['柯南','孔明'],'L':['李白','刘备','林黛玉','罗辑'],'M':['马超','马云','孟子'],'N':['倪萍','牛顿'],'P':['潘金莲','蒲松龄'],'Q':['秦始皇','钱学森','齐天大圣'],'R':['任我行','阮玲玉'],'S':['孙悟空','司马懿','苏轼','沈腾'],'T':['唐僧','诸葛亮'],'W':['王昭君','武则天','吴用'],'X':['西门庆','许仙','项羽'],'Y':['杨过','岳飞','袁隆平'],'Z':['张飞','赵云','诸葛亮','周瑜','庄子'],}// Sort keysconstsortedKeys:string[]=Object.keys(contacts).sort()@Entry@Componentstruct AlphabetIndexerPinyinMultilang{@StateisShow:boolean=true@StateselectedIndex:number=0privatelistScroller:Scroller=newScroller()build(){Column(){if(this.isShow){Column({space:16}){Text('中文拼音索引').fontSize(20).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR)Text('AlphabetIndexer 结合拼音首字母索引中文联系人').fontSize(13).fontColor(DEMO_SUBTEXT_COLOR).width('100%')Row(){List({scroller:this.listScroller}){ForEach(sortedKeys,(key:string)=>{ListItemGroup(){ListItem(){Text(key).fontSize(15).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR).width('100%').padding({left:12,top:6,bottom:4}).backgroundColor('#F5F5F5')}ForEach(contacts[key]asstring[],(name:string)=>{ListItem(){Row({space:10}){Text(name.charAt(0)).fontSize(16).fontWeight(FontWeight.Bold).fontColor('#FFFFFF').width(32).height(32).textAlign(TextAlign.Center).backgroundColor(PRESET_COLORS[sortedKeys.indexOf(key)%PRESET_COLORS.length].value).borderRadius(16)Text(name).fontSize(15).fontColor('#333333')}.width('100%').padding({left:16,top:6,bottom:6})}})}})}.layoutWeight(1).height(320).divider({strokeWidth:0.5,color:'#EEEEEE'}).backgroundColor(DEMO_CARD_COLOR).borderRadius(12)AlphabetIndexer({arrayValue:sortedKeys,selected:this.selectedIndex}).selectedColor(DEMO_THEME_COLOR).popupColor(DEMO_THEME_COLOR).usingPopup(true).selectedBackgroundColor('#E8EAF6').itemSize(12).onSelect((index:number)=>{this.selectedIndex=indexthis.listScroller.scrollToIndex(index)})}.width('100%').height(320)}.alignItems(HorizontalAlign.Start)}Text('拼音索引多语言页 - AlphabetIndexer 多语言索引').fontSize(12).fontColor('#999999').margin({top:12})}.width('100%').height('100%').backgroundColor(DEMO_BG_COLOR).padding(16)}}

收个尾

如果你最近正好要做 中文通讯录、城市列表、带拼音检索的数据页，那这篇可以直接当起步模板。先跑通，再替换数据和交互，效率会比从空白页起步高很多。