1# 城市选择案例 2 3### 介绍 4 5本示例介绍城市选择场景的使用：通过[AlphabetIndexer](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-alphabet-indexer.md)实现首字母快速定位城市的索引条导航。 6 7### 效果图预览 8 9<img src="casesfeature/citysearch/city_search.gif" width="300"> 10 11**使用说明** 12 13分两个功能 14- 在搜索框中可以根据城市拼音首字母模糊搜索出相近的城市，例如输入"a"，会出现"阿尔山"、"阿勒泰地区"、"安庆"、"安阳"。输入"b"，会出现"北京"、"亳州"、"包头"、"宝鸡"。 15- 下方城市列表通过AlphabetIndexer组件实现拼音索引条，通过滑动选择城市首拼，快速定位相关首拼城市。 16 17### 下载安装 18 191.模块oh-package.json5文件中引入依赖。 20```typescript 21"dependencies": { 22 "citysearch": "har包地址" 23} 24``` 252.ets文件import列表视图组件。 26```typescript 27import { AlphabetListView } from 'citysearch'; 28``` 29 30### 快速使用 31 32本文主要介绍了如何快速上手自定义城市列表视图实现城市的索引条导航视图。包括数据初始化以及构建城市视图组件。 33 341. 数据准备。初始化城市列表和热门城市列表数组。 35 36```typescript 37// 热门城市列表 38hotCityList: HotCityListItemView[] = []; 39 // 城市列表 40cityList: CityListItemView[] = []; 41 42aboutToAppear(): void { 43 CITY_DATA.forEach((cityItem: AlphabetListItemType) => { 44 this.cityList.push(new AlphabetListItemView(cityItem, wrapBuilder(cityListItemSection))) 45 }) 46 HOT_CITY.forEach((hotCityItem: string) => { 47 this.hotCityList.push(new HotListItemView(hotCityItem, wrapBuilder(hotCitySection))) 48 }) 49} 50 51``` 52以上代码中，[AlphabetListItemView](./casesfeature/citysearch/src/main/ets/model/DetailData.ets)为字母数据列表项的类，[HotListItemView](./casesfeature/citysearch/src/main/ets/model/DetailData.ets)为热门列表项的类。两者都包含列表项数据、 53列表项视图属性，开发者可以自行配置，也可以使用默认的属性配置。 54 552. 构建自定义城市列表视图。 56```typescript 57 58AlphabetListView({ 59 hotSelectList: this.hotCityList, 60 hotSelectListTitle: $r('app.string.citysearch_hotCity'), 61 alphabetSelectList: this.cityList, 62 hotSelectHandle: (hotSelectValue: string) => { 63 this.hotCityHandle(hotSelectValue); 64 }, 65 alphabetSelectHandle: (alphabetSelectValue: string) => { 66 this.cityHandle(alphabetSelectValue); 67 } 68}) 69 70``` 71 72### 属性(接口)说明 73 74HotListItemView类属性 75 76| 属性 | 类型 | 释义 | 默认值 | 77|:------------------:|:------------------------:|:-------:|:---:| 78| hotListItem | string | 热门列表项数据 | - | 79| contentBuilder | WrappedBuilder<[string]> | 热门列表项视图 | - | 80 81AlphabetListItemType类属性 82 83| 属性 | 类型 | 释义 | 默认值 | 84|:--------:|:------------------------------------:|:------------:|:---------:| 85| name | string | 数据名称的首字母 | - | 86| dataList | string[] | 字母对应的列表数据 | - | 87 88 89AlphabetListItemView类属性 90 91| 属性 | 类型 | 释义 | 默认值 | 92|:-------------------------:|:-----------------------------------:|:-----:|:---:| 93| alphabetListItem | AlphabetListItemType | 列表项数据 | - | 94| contentBuilder | WrappedBuilder<[string]> | 列表项视图 | - | 95 96 97AlphabetListView自定义组件属性 98 99| 属性 | 类型 | 释义 | 默认值 | 100|:------------------------------:|:---------------------:|:-----------:|:---:| 101| hotSelectList | HotCityListItemView[] | 热门选择列表数据 | - | 102| hotSelectListTitle | ResoureStr | 热门列表标题 | - | 103| alphabetSelectList | CityListItemView[] | 字母选择列表数据 | - | 104| hotSelectHandle | void | 热门选择列表项逻辑处理 | - | 105| alphabetSelectHandle | void | 字母选择列表项逻辑处理 | - | 106 107### 实现思路 108#### 场景：通过AlphabetIndexer实现索引条导航 109 110城市列表中的右侧首拼索引条，通过AlphabetIndexer组件实现首字母快速定位城市的索引条导航。 111 112- 通过AlphabetIndexer的selected属性与城市列表中List组件onScrollIndex事件绑定，[AlphabetListView.ets](./casesfeature/citysearch/src/main/ets/utils/AlphabetListView.ets) 113 114```typescript 115AlphabetIndexer({ arrayValue: this.alphabetIndexer, selected: this.stabIndex }) 116 .height(CommonConstants.VIEW_FULL) 117 .selectedColor($r('app.color.citysearch_alphabet_select_color'))// 选中项文本颜色 118 .popupColor($r('app.color.citysearch_alphabet_pop_color'))// 弹出框文本颜色 119 .selectedBackgroundColor($r('app.color.citysearch_alphabet_selected_bgc'))// 选中项背景颜色 120 .popupBackground($r('app.color.citysearch_alphabet_pop_bgc'))// 弹出框背景颜色 121 .popupPosition({ 122 x: $r('app.integer.citysearch_pop_position_x'), 123 y: $r('app.integer.citysearch_pop_position_y') 124 }) 125 .usingPopup(true)// 是否显示弹出框 126 .selectedFont({ size: $r('app.integer.citysearch_select_font'), weight: FontWeight.Bolder })// 选中项字体样式 127 .popupFont({ size: $r('app.integer.citysearch_pop_font'), weight: FontWeight.Bolder })// 弹出框内容的字体样式 128 .alignStyle(IndexerAlign.Right)// 弹出框在索引条左侧弹出 129 .itemSize(CommonConstants.ALPHABET_SIZE)// 每一项的尺寸大小 130 .margin({ right: CommonConstants.ALPHABET_MARGIN_RIGHT_SIZE }) 131 .onSelect((tabIndex: number) => { 132 this.scroller.scrollToIndex(tabIndex); 133 }) 134``` 135- 当用户滑动List组件，list组件onScrollIndex监听到firstIndex的改变，绑定赋值给AlphabetIndexer的selected属性，从而定位到字母索引。 136- 当点击AlphabetIndexer的字母索引时，通过scrollToIndex触发list组件滑动并指定firstIndex，从而实现List列表与AlphabetIndexer组件首字母联动吸顶展示，[CityView.ets](./casesfeature/citysearch/src/main/ets/utils/AlphabetListView.ets)。 137```typescript 138List({ space: CommonConstants.LIST_SPACE, initialIndex: CommonConstants.INITIAL_INDEX, scroller: this.scroller }) { 139 .onScrollIndex((firstIndex: number, lastIndex: number) => { 140 this.stabIndex = firstIndex; 141 }) 142} 143``` 144 145 146### 高性能知识点 147 148由于需要通过搜索按钮频繁的控制自定义组件的显隐状态，[AlphabetListView.ets](./casesfeature/citysearch/src/main/ets/utils/AlphabetListView.ets)，因此推荐使用显隐控制替代条件渲染。 149 150### 工程结构&模块类型 151 152 ``` 153 citysearch // har类型 154 |---src/main/ets/common 155 | |---commonConstants.ets // 常量 156 |---src/main/ets/model 157 | |---DetailData.ets // 模型层-数据模块 158 |---src/main/ets/util 159 | |---AlphabetListView.ets // 视图层-城市列表组件 160 | |---Logger.ets // 日志 161 |---src/main/ets/view 162 | |---CitySearch.ets // 视图层-主页 163 | |---SearchView.ets // 视图层-搜索组件 164 ``` 165 166### 参考资料 167 168[AlphabetIndexer参考文档](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-container-alphabet-indexer.md) 169 170### 约束与限制 171 1721.本示例仅支持标准系统上运行。 173 1742.本示例已适配API version 12版本SDK。 175 1763.本示例需要使用DevEco Studio 5.0.0 Release及以上版本才可编译运行。 177 178### 下载 179 180如需单独下载本工程，执行如下命令： 181```javascript 182git init 183git config core.sparsecheckout true 184echo /code/UI/CitySearch/ > .git/info/sparse-checkout 185git remote add origin https://gitee.com/openharmony/applications_app_samples.git 186git pull origin master 187```
