README.md
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```
