前言

城市选择器几乎是移动应用里的高频模块。定位城市、热门城市、字母索引、选中回显，这些元素经常会一起出现。这个案例适合用来做多模块组合练习。 我一直觉得，好示例不一定代码多，但一定能把“为什么要这么写”交代清楚。城市选择器 这个页面就属于这种，值得停下来认真拆一遍。

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

这类写法尤其适合落在 外卖定位、出行购票、生活服务、地区切换页 这些场景里，所以我下面不会只讲“组件怎么写”，而是更关心“放进页面之后为什么这样组织”。

这页的阅读顺序我建议这样走

这一类页面看源码最怕的就是“每一段都认识，但拼起来不知道为什么这么摆”。所以这里先从页面骨架讲起，比直接盯属性更省时间。

| 辅助信息区 | 补充状态、标签、分组或统计信息 | 次级文本、角标、分组标题、描述块 |
| 交互入口区 | 负责切换、返回、定位、选择等动作 | 点击事件、按钮、索引条、导航入口 |

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

我会把它当成真实业务页面来拆，重点看哪些写法可以直接迁到项目里，哪些只是示例环境下的轻量实现。

先把谁在驱动页面这件事搞清楚

城市选择器的状态比普通索引页多一步：用户不只是跳到某个分组，还要最终选中一个城市。

• isShow：控制示例区域显示。
• selectedIndex：记录当前索引分组，用来同步右侧字母条。
• selectedCity：保存最终选择结果，顶部“当前选择”区域直接读取它。
• listScroller：把字母索引和城市分组列表连接起来。

这个结构很适合真实业务：热门城市、定位城市、字母分组都可以继续往里加，但最终回显只需要盯住selectedCity，页面状态不会乱。

我会优先读的就是这几段逻辑

我一般不会把所有方法从上到下读一遍，而是先找“用户动一下之后，页面为什么会变”的那条链路。

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

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

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

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

@StateisShow:boolean=true@StateselectedIndex:number=0@StateselectedCity:string='请选择城市'privatelistScroller:Scroller=newScroller()build(){Column(){if(this.isShow){Column({space:12}){Text('城市选择器').fontSize(20).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR)// 选中城市显示Row({space:10}){Text('📍').fontSize(16)Text('当前选择：'+this.selectedCity).fontSize(14).fontColor(this.selectedCity==='请选择城市'?DEMO_SUBTEXT_COLOR:DEMO_THEME_COLOR).fontWeight(FontWeight.Medium).layoutWeight(1)}

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

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

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

这一段关键代码把城市选择的两个动作拆开了：点城市时更新selectedCity，点右侧索引时更新selectedIndex并滚动列表。一个负责最终结果，一个负责浏览效率。把这两条线分清楚，后面加热门城市、最近访问、定位失败提示都不会互相打架。

.onClick(()=>{this.selectedCity=city})})}})}.layoutWeight(1).height(300).divider({strokeWidth:0.5,color:'#EEEEEE'}).backgroundColor(DEMO_CARD_COLOR).borderRadius(12)AlphabetIndexer({arrayValue:cityKeys,selected:this.selectedIndex}).selectedColor(DEMO_THEME_COLOR).popupColor(DEMO_THEME_COLOR).usingPopup(true).selectedBackgroundColor('#E8EAF6').itemSize(11).onSelect((index:number)=>{this.selectedIndex=index

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

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'constcityGroups:Record<string,string[]>={'B':['北京','保定','包头','宝鸡'],'C':['成都','重庆','长沙','常州','长春'],'D':['大连','东莞','大同'],'F':['福州','佛山'],'G':['广州','贵阳','桂林'],'H':['杭州','合肥','海口','哈尔滨','呼和浩特'],'J':['济南','金华','嘉兴','江门'],'N':['南京','宁波','南昌','南宁'],'Q':['青岛','泉州','秦皇岛'],'S':['上海','深圳','苏州','沈阳','石家庄'],'T':['天津','太原','台州'],'W':['武汉','无锡','温州','乌鲁木齐'],'X':['西安','厦门','徐州','湘潭'],'Z':['郑州','珠海','中山','株洲'],}constcityKeys:string[]=Object.keys(cityGroups).sort()@Entry@Componentstruct CitySelectorPanel{@StateisShow:boolean=true@StateselectedIndex:number=0@StateselectedCity:string='请选择城市'privatelistScroller:Scroller=newScroller()build(){Column(){if(this.isShow){Column({space:12}){Text('城市选择器').fontSize(20).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR)// 选中城市显示Row({space:10}){Text('📍').fontSize(16)Text('当前选择：'+this.selectedCity).fontSize(14).fontColor(this.selectedCity==='请选择城市'?DEMO_SUBTEXT_COLOR:DEMO_THEME_COLOR).fontWeight(FontWeight.Medium).layoutWeight(1)}.width('100%').padding(12).backgroundColor('#E8EAF6').borderRadius(10)Row(){List({scroller:this.listScroller}){ForEach(cityKeys,(key:string)=>{ListItemGroup(){ListItem(){Text(key).fontSize(14).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR).width('100%').padding({left:12,top:6,bottom:3}).backgroundColor('#F5F5F5')}ForEach(cityGroups[key]asstring[],(city:string)=>{ListItem(){Row({space:10}){Text(city.charAt(0)).fontSize(14).fontWeight(FontWeight.Bold).fontColor(DEMO_THEME_COLOR).width(28).height(28).textAlign(TextAlign.Center).backgroundColor('#E8EAF6').borderRadius(6)Text(city).fontSize(15).fontColor('#333333').layoutWeight(1)Text('>').fontSize(12).fontColor('#CCCCCC')}.width('100%').padding({left:12,right:12,top:8,bottom:8})}.onClick(()=>{this.selectedCity=city})})}})}.layoutWeight(1).height(300).divider({strokeWidth:0.5,color:'#EEEEEE'}).backgroundColor(DEMO_CARD_COLOR).borderRadius(12)AlphabetIndexer({arrayValue:cityKeys,selected:this.selectedIndex}).selectedColor(DEMO_THEME_COLOR).popupColor(DEMO_THEME_COLOR).usingPopup(true).selectedBackgroundColor('#E8EAF6').itemSize(11).onSelect((index:number)=>{this.selectedIndex=indexthis.listScroller.scrollToIndex(index)})}.width('100%').height(300)}.alignItems(HorizontalAlign.Start)}Text('城市选择器 - 城市选择器').fontSize(12).fontColor('#999999').margin({top:12})}.width('100%').height('100%').backgroundColor(DEMO_BG_COLOR).padding(16)}}

收个尾

这个案例没有故意炫技，反而因此更适合学习。页面目标清楚、代码组织也相对直接，拿来练手或者做项目骨架都不亏。