• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ArcAlphabetIndexer
2
3The **ArcAlphabetIndexer** component is a circular component designed for quick navigation through alphabetically sorted items. It can be integrated with container components to quickly locate items within the visible area.
4
5>  **NOTE**
6>
7>  This component is supported since API version 16. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## Modules to Import
11
12```
13import { ArcAlphabetIndexer, ArcAlphabetIndexerAttribute } from '@kit.ArkUI'
14```
15
16
17## Child Components
18
19Not supported
20
21
22## APIs
23
24ArcAlphabetIndexer(info: ArcAlphabetIndexerInitInfo)
25
26Creates an instance of the **ArcAlphabetIndexer** component with initialization parameters.
27
28**Atomic service API**: This API can be used in atomic services since API version 16.
29
30**System capability**: SystemCapability.ArkUI.ArkUI.Circle
31
32**Parameters**
33
34| Name    | Type    | Mandatory    | Description    |
35| -------- | -------- | -------- | -------- |
36| info     | [ArcAlphabetIndexerInitInfo](#arcalphabetindexerinitinfo) | Yes| Initialization parameters for the **ArcAlphabetIndexer** component.|
37
38
39## Attributes
40
41In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
42
43### color
44
45color(color: Optional<ColorMetrics>)
46
47Sets the text color of the index items in the normal state.
48
49**Atomic service API**: This API can be used in atomic services since API version 16.
50
51**System capability**: SystemCapability.ArkUI.ArkUI.Circle
52
53**Parameters**
54
55| Name| Type                                      | Mandatory| Description                               |
56| ------ | ------------------------------------------ | ---- | ----------------------------------- |
57| color  | [Optional&lt;ColorMetrics&gt;](../js-apis-arkui-graphics.md#colormetrics12) | Yes  | Text color of the index items in the normal state.<br>Default value: **0xFFFFFF**|
58
59### selectedColor
60
61selectedColor(color: Optional&lt;ColorMetrics&gt;)
62
63Sets the text color of the selected item.
64
65**Atomic service API**: This API can be used in atomic services since API version 16.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Circle
68
69**Parameters**
70
71| Name| Type                                      | Mandatory| Description                                     |
72| ------ | ------------------------------------------ | ---- | ----------------------------------------- |
73| color  | [Optional&lt;ColorMetrics&gt;](../js-apis-arkui-graphics.md#colormetrics12) | Yes  | Text color of the selected item.<br>Default value: **0xFFFFFF**|
74
75### popupColor
76
77popupColor(color: Optional&lt;ColorMetrics&gt;)
78
79Sets the text color for the pop-up window.
80
81**Atomic service API**: This API can be used in atomic services since API version 16.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Circle
84
85**Parameters**
86
87| Name| Type                                      | Mandatory| Description                                       |
88| ------ | ------------------------------------------ | ---- | ------------------------------------------- |
89| color  | [Optional&lt;ColorMetrics&gt;](../js-apis-arkui-graphics.md#colormetrics12) | Yes  | Text color of the pop-up window.<br>Default value: **0xFFFFFF**|
90
91### selectedBackgroundColor
92
93selectedBackgroundColor(color: Optional&lt;ColorMetrics&gt;)
94
95Sets the background color of the selected item.
96
97**Atomic service API**: This API can be used in atomic services since API version 16.
98
99**System capability**: SystemCapability.ArkUI.ArkUI.Circle
100
101**Parameters**
102
103| Name| Type                                      | Mandatory| Description                                     |
104| ------ | ------------------------------------------ | ---- | ----------------------------------------- |
105| color  | [Optional&lt;ColorMetrics&gt;](../js-apis-arkui-graphics.md#colormetrics12) | Yes  | Background color of the selected item.<br>Default value: **0x1F71FF**|
106
107### popupBackground
108
109popupBackground(color: Optional&lt;ColorMetrics&gt;)
110
111Sets the background color of the pop-up window.
112
113**Atomic service API**: This API can be used in atomic services since API version 16.
114
115**System capability**: SystemCapability.ArkUI.ArkUI.Circle
116
117**Parameters**
118
119| Name| Type                                                    | Mandatory| Description                                                        |
120| ------ | -------------------------------------------------------- | ---- | ------------------------------------------------------------ |
121| color  | [Optional&lt;ColorMetrics&gt;](../js-apis-arkui-graphics.md#colormetrics12) | Yes  | Background color of the pop-up window.<br>Default value: **0xD8404040**|
122
123### usePopup
124
125usePopup(enabled: Optional&lt;boolean&gt;)
126
127Sets whether to display the pop-up window.
128
129**Atomic service API**: This API can be used in atomic services since API version 16.
130
131**System capability**: SystemCapability.ArkUI.ArkUI.Circle
132
133**Parameters**
134
135| Name| Type   | Mandatory| Description                                  |
136| ------ | ------- | ---- | -------------------------------------- |
137| enabled | Optional&lt;boolean&gt; | Yes  | Whether to display the pop-up window.<br>Default value: **false**|
138
139### selectedFont
140
141selectedFont(font: Optional&lt;Font&gt;)
142
143Sets the font style of the selected item, including size, weight, style, and font family.
144
145**Atomic service API**: This API can be used in atomic services since API version 16.
146
147**System capability**: SystemCapability.ArkUI.ArkUI.Circle
148
149**Parameters**
150
151| Name| Type                                    | Mandatory| Description                                                        |
152| ------ | ---------------------------------------- | ---- | ------------------------------------------------------------ |
153| font   | [Optional&lt;Font&gt;](ts-types.md#font) | Yes  | Font style of the selected item.<br>Default value: {<br>size:'13.0fp',<br> style:FontStyle.Normal,<br> weight:500,<br> family:'HarmonyOS Sans'<br>} |
154
155### popupFont
156
157popupFont(value: Optional&lt;Font&gt;)
158
159Sets the font style of the pop-up window.
160
161**Atomic service API**: This API can be used in atomic services since API version 16.
162
163**System capability**: SystemCapability.ArkUI.ArkUI.Circle
164
165**Parameters**
166
167| Name| Type                    | Mandatory| Description                                                        |
168| ------ | ------------------------ | ---- | ------------------------------------------------------------ |
169| value  | [Optional&lt;Font&gt;](ts-types.md#font) | Yes  | Font style of the pop-up window.<br>Default value:<br>{<br>size:'19.0fp',<br> style:FontStyle.Normal,<br> weight:500,<br> family:'HarmonyOS Sans'<br>} |
170
171### font
172
173font(font: Optional&lt;Font&gt;)
174
175Sets the default font style of the index items.
176
177**Atomic service API**: This API can be used in atomic services since API version 16.
178
179**System capability**: SystemCapability.ArkUI.ArkUI.Circle
180
181**Parameters**
182
183| Name| Type                    | Mandatory| Description                                                        |
184| ------ | ------------------------ | ---- | ------------------------------------------------------------ |
185| font   | [Optional&lt;Font&gt;](ts-types.md#font) | Yes  | Default font style of the index items.<br>Default value:<br>{<br>size:'13.0fp',<br> style:FontStyle.Normal,<br> weight:500,<br> family:'HarmonyOS Sans'<br>} |
186
187### itemSize
188
189itemSize(size: Optional&lt;LengthMetrics&gt;)
190
191Sets the size of the index item area.
192
193**Atomic service API**: This API can be used in atomic services since API version 16.
194
195**System capability**: SystemCapability.ArkUI.ArkUI.Circle
196
197**Parameters**
198
199| Name| Type                      | Mandatory| Description                                                        |
200| ------ | -------------------------- | ---- | ------------------------------------------------------------ |
201| size  | Optional&lt;LengthMetrics&gt; | Yes  | Size of the index item area. For the circular item area, this represents the diameter of the circle. Percentage values are not supported.<br>Default value: **24.0**<br>Unit: vp|
202
203### selected
204
205selected(index: Optional&lt;number&gt;)
206
207Sets the index of the selected item.
208
209**Atomic service API**: This API can be used in atomic services since API version 16.
210
211**System capability**: SystemCapability.ArkUI.ArkUI.Circle
212
213**Parameters**
214
215| Name| Type  | Mandatory| Description                        |
216| ------ | ------ | ---- | ---------------------------- |
217| index  | Optional&lt;number&gt; | Yes  | Index of the selected item.<br>Default value: **0**<br>This parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).|
218
219### autoCollapse
220
221autoCollapse(enable: Optional&lt;boolean&gt;)
222
223Sets whether to auto-collapse or expand the indexer.
224
225**Atomic service API**: This API can be used in atomic services since API version 16.
226
227**System capability**: SystemCapability.ArkUI.ArkUI.Circle
228
229**Parameters**
230
231| Name| Type   | Mandatory| Description                                      |
232| ------ | ------- | ---- | ------------------------------------------ |
233| enable  | Optional&lt;boolean&gt; | Yes  | Whether to auto-collapse or expand the indexer.<br>Default value: **false**|
234
235### popupBackgroundBlurStyle
236
237popupBackgroundBlurStyle(style: Optional&lt;BlurStyle&gt;)
238
239Sets the background blur style of the pop-up window.
240
241**Atomic service API**: This API can be used in atomic services since API version 16.
242
243**System capability**: SystemCapability.ArkUI.ArkUI.Circle
244
245**Parameters**
246
247| Name| Type                                        | Mandatory| Description                                                        |
248| ------ | -------------------------------------------- | ---- | ------------------------------------------------------------ |
249| style  | [Optional&lt;BlurStyle&gt;](ts-universal-attributes-background.md#blurstyle9) | Yes  | Background blur style of the pop-up window.<br>Default value: **COMPONENT_REGULAR**|
250
251## Events
252
253In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
254
255### onSelect
256
257onSelect(handler: Optional&lt;OnSelectCallback&gt;)
258
259Triggered when an index item is selected. The return value is the index of the selected item.
260
261**Atomic service API**: This API can be used in atomic services since API version 16.
262
263**System capability**: SystemCapability.ArkUI.ArkUI.Circle
264
265**Parameters**
266
267| Name| Type  | Mandatory| Description            |
268| ------ | ------ | ---- | ---------------- |
269| handler  | Optional&lt;[OnSelectCallback](#onselectcallback)&gt; | Yes  | Callback used to return the result.|
270
271
272## ArcAlphabetIndexerInitInfo
273
274Defines the initialization parameters for the **ArcAlphabetIndexer** component.
275
276**Atomic service API**: This API can be used in atomic services since API version 16.
277
278**System capability**: SystemCapability.ArkUI.ArkUI.Circle
279
280**Parameters**
281
282| Name| Type| Mandatory| Description|
283| -------- | -------- | -------- | -------- |
284| arrayValue | string[] | Yes| Array of alphabet index strings. It cannot be set to empty.|
285| selected   | number              | Yes| Index of the initial selected item. If the value is out of range, the default value **0** is used.<br>This parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).|
286
287## OnSelectCallback
288
289type OnSelectCallback =  (index: number) => void
290
291Defines the callback used in [onSelect](#onselect).
292
293**Atomic service API**: This API can be used in atomic services since API version 16.
294
295**System capability**: SystemCapability.ArkUI.ArkUI.Circle
296
297**Parameters**
298
299| Name | Type   | Mandatory| Description             |
300| ------ | ------ | ---- | ---------------- |
301| index  | number | Yes| Index of the selected item.|
302
303
304## Example
305
306This example demonstrates how to link an **ArcAlphabetIndexer** component with an **ArcList** component for synchronized control and navigation.
307
308```ts
309// xxx.ets
310import {
311  LengthMetrics,
312  ColorMetrics,
313  ArcList,
314  ArcListItem,
315  ArcListAttribute,
316  ArcListItemAttribute,
317  ArcAlphabetIndexer,
318  ArcAlphabetIndexerAttribute
319} from '@kit.ArkUI';
320
321@Builder
322function buildText() {
323  Stack() {
324    Text("head")
325      .fontSize(30)
326      .padding(10)
327      .backgroundColor(0xF9CF93)
328      .border({ width: '1px', color: Color.Black })
329
330    Divider().width('100%').height('1px')
331  }
332  .alignContent(Alignment.Bottom)
333}
334
335@Entry
336@Component
337struct ArcListAndIndexer {
338  private fullValue: string[] = [
339    '#', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N',
340    'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'
341  ]
342  private arrName : string[] = [
343    '1','2','3','4','5','6','7','8','9','10','11','12','13','14','15','16','17','18','19','20',
344    '21','22','23','24','25','26','27','28','29','30','31','32','33','34','35','36','37','38',
345    '39','40', '41','42',
346  ];
347
348  private scrollerForList: Scroller = new Scroller()
349  @State indexerIndex: number = 0;
350
351  private watchSize: string = '466px' // Default watch size: 233*233
352  private itemSize: number = 16  // Default size of the index item area: 24
353
354  build() {
355    Column() {
356      Row() {
357        Stack() {
358          ArcList({ scroller : this.scrollerForList, initialIndex: 0 }) {
359            ForEach(this.arrName, (itemName: string, index: number) => {
360              ArcListItem() {
361                Text(itemName)
362                  .width('90%')
363                  .height('92px')
364                  .fontSize(16)
365                  .textAlign(TextAlign.Center)
366                  .backgroundColor(index % 2 == 0 ? 0xAFEEEE : 0x00FFFF)
367                  .borderRadius(23)
368              }
369            })
370          }
371          .scrollBar(BarState.Off)
372          .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => {
373            this.indexerIndex = centerIndex;
374          })
375          .borderWidth(1)
376          .width(this.watchSize)
377          .height(this.watchSize)
378          .borderRadius(this.watchSize)
379          .space(LengthMetrics.px(4))
380
381          ArcAlphabetIndexer({ arrayValue: this.fullValue, selected: 0 })
382            .autoCollapse(true)
383            .width(this.watchSize)
384            .height(this.watchSize)
385            .usePopup(false)
386            .selected(this.indexerIndex)
387            .onSelect((index: number) => {
388              this.indexerIndex = index
389              this.scrollerForList.scrollToIndex(this.indexerIndex)
390            })
391            .borderWidth(1)
392            .hitTestBehavior(HitTestMode.Transparent)
393            .selectedColor(ColorMetrics.resourceColor(0xFFFFFF))
394            .selectedBackgroundColor(ColorMetrics.resourceColor(0x1F71FF))
395            .color(ColorMetrics.resourceColor(0xFFFFFF))
396            .popupColor(ColorMetrics.resourceColor(0xFFFFFF))
397            .popupBackground(ColorMetrics.resourceColor(0xD8404040))
398            .itemSize(LengthMetrics.px(this.itemSize))
399            .selectedFont({
400              size:'11.0fp',
401              style:FontStyle.Normal,
402              weight:500,
403              family:'HarmonyOS Sans'
404            })
405            .font({
406              size:'11.0fp',
407              style:FontStyle.Normal,
408              weight:500,
409              family:'HarmonyOS Sans'
410            })
411
412        }.width('100%').height('100%')
413      }.width('100%').height('100%')
414    }
415  }
416}
417```
418
419![arc_alphabet_indexer_preview](figures/arc_alphabet_indexer_preview.gif)
420