• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Indicator
2
3The **Indicator** component provides two types of navigation indicators: dot indicators and digit indicators.
4
5It encapsulates the existing [indicator](ts-container-swiper.md#indicator) capabilities—previously part of the [Swiper](ts-container-swiper.md) component—and delivers them as a standalone component. You can use the **Indicator** component independently or bind it to a **Swiper** component through **IndicatorComponentController**.
6
7When multiple **Indicator** components are bound to a single **Swiper**, only the last bound **Indicator** is active.
8
9Conversely, if an **Indicator** is bound to multiple **Swiper** components, only the last bound **Swiper** works with the **Indicator**.
10
11>  **NOTE**
12>
13> This component is supported since API version 15. Updates will be marked with a superscript to indicate their earliest API version.
14
15
16## Child Components
17
18Not supported
19
20## APIs
21
22IndicatorComponent(controller?: IndicatorComponentController)
23
24A constructor used to create an **Indicator** component. You can optionally pass a controller to manage the **Indicator** component.
25
26**Widget capability**: This API can be used in ArkTS widgets since API version 15.
27
28**Atomic service API**: This API can be used in atomic services since API version 15.
29
30**System capability**: SystemCapability.ArkUI.ArkUI.Full
31
32**Parameters**
33
34|Name|Type|Mandatory|Description|
35| ----- | ----- | -- |  --- |
36| controller |  [IndicatorComponentController](#indicatorcomponentcontroller) | No| Controller to manage the **Indicator** component.|
37
38## Attributes
39
40In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported.
41
42### style
43
44style(indicatorStyle: DotIndicator | DigitIndicator)
45
46Sets the style of the navigation indicator.
47
48**Widget capability**: This API can be used in ArkTS widgets since API version 15.
49
50**Atomic service API**: This API can be used in atomic services since API version 15.
51
52**System capability**: SystemCapability.ArkUI.ArkUI.Full
53
54**Parameters**
55
56| Name| Type                                                        | Mandatory| Description                                                        |
57| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
58| indicatorStyle  | [DotIndicator](ts-container-swiper.md#dotindicator10) \| [DigitIndicator](ts-container-swiper.md#digitindicator10) | Yes  | Style of the navigation indicator.<br> \- **DotIndicator**: dot style.<br> \- **DigitIndicator**: digit style.<br>  Default style: **DotIndicator**|
59
60> **NOTE**
61>
62> When **indicatorStyle** is set to **DotIndicator**, [maxDisplayCount](ts-container-swiper.md#maxdisplaycount12) does not take effect.
63
64### count
65
66count(totalCount: number)
67
68Sets the total number of navigation points.
69
70When the **Indicator** component is used with a **Swiper** component, the count is subject to the number of pages in the **Swiper** component.
71
72**Widget capability**: This API can be used in ArkTS widgets since API version 15.
73
74**Atomic service API**: This API can be used in atomic services since API version 15.
75
76**System capability**: SystemCapability.ArkUI.ArkUI.Full
77
78**Parameters**
79
80| Name| Type  | Mandatory| Description                                            |
81| ------ | ------ | ---- | ------------------------------------------------ |
82| totalCount  | number | Yes  |  Total number of navigation points.<br>Default value: **2**|
83
84### initialIndex
85
86initialIndex(index: number)
87
88Sets the initial index of the navigation indicator when it first appears. If the value is less than 0 or greater than or equal to the total count, the default value **0** is used.
89
90This attribute does not take effect when the **Indicator** component is bound to a **Swiper** component.
91
92**Widget capability**: This API can be used in ArkTS widgets since API version 15.
93
94**Atomic service API**: This API can be used in atomic services since API version 15.
95
96**System capability**: SystemCapability.ArkUI.ArkUI.Full
97
98**Parameters**
99
100| Name| Type  | Mandatory| Description                                            |
101| ------ | ------ | ---- | ------------------------------------------------ |
102| index  | number | Yes  | Initial index of the navigation indicator when it first appears.<br>Default value: **0**|
103
104### loop
105
106loop(isLoop: boolean)
107
108Sets whether to enable looping.
109
110This attribute does not take effect when the **Indicator** component is bound to a **Swiper** component.
111
112**Widget capability**: This API can be used in ArkTS widgets since API version 15.
113
114**Atomic service API**: This API can be used in atomic services since API version 15.
115
116**System capability**: SystemCapability.ArkUI.ArkUI.Full
117
118**Parameters**
119
120| Name| Type   | Mandatory| Description                           |
121| ------ | ------- | ---- | ------------------------------- |
122| isLoop  | boolean | Yes  | Whether to enable looping. The value **true** means to enable looping, and **false** means the opposite.<br>Default value: **true**|
123
124### vertical
125
126vertical(isVertical: boolean)
127
128Sets whether vertical swiping is used.
129
130This attribute does not take effect when the **Indicator** component is bound to a **Swiper** component.
131
132**Widget capability**: This API can be used in ArkTS widgets since API version 15.
133
134**Atomic service API**: This API can be used in atomic services since API version 15.
135
136**System capability**: SystemCapability.ArkUI.ArkUI.Full
137
138**Parameters**
139
140| Name| Type   | Mandatory| Description                              |
141| ------ | ------- | ---- | ---------------------------------- |
142| isVertical  | boolean | Yes  | Whether vertical swiping is used. The value **true** means vertical swiping, and **false** means horizontal swiping.<br>Default value: **false**.|
143
144## Events
145
146In addition to the [universal events](ts-component-general-events.md), the following events are supported.
147
148### onChange
149
150onChange(event: Callback\<number>)
151
152Triggered when the currently selected navigation index changes. The callback provides the new index.
153
154**Widget capability**: This API can be used in ArkTS widgets since API version 15.
155
156**Atomic service API**: This API can be used in atomic services since API version 15.
157
158**System capability**: SystemCapability.ArkUI.ArkUI.Full
159
160**Parameters**
161
162| Name| Type  | Mandatory| Description                |
163| ------ | ------ | ---- | -------------------- |
164| event  | [Callback](./ts-types.md#callback12)\<number> | Yes  | Callback triggered when the index changes.|
165
166## IndicatorComponentController
167
168Implements a controller for the **Indicator** component, allowing you to control navigation.
169
170### constructor
171
172constructor()
173
174A constructor used to create an **IndicatorComponentController** object.
175
176**Widget capability**: This API can be used in ArkTS widgets since API version 15.
177
178**Atomic service API**: This API can be used in atomic services since API version 15.
179
180**System capability**: SystemCapability.ArkUI.ArkUI.Full
181
182### showNext
183
184showNext(): void
185
186Moves to the next navigation point.
187
188**Widget capability**: This API can be used in ArkTS widgets since API version 15.
189
190**Atomic service API**: This API can be used in atomic services since API version 15.
191
192**System capability**: SystemCapability.ArkUI.ArkUI.Full
193
194### showPrevious
195
196showPrevious(): void
197
198Moves to the previous navigation point.
199
200**Widget capability**: This API can be used in ArkTS widgets since API version 15.
201
202**Atomic service API**: This API can be used in atomic services since API version 15.
203
204**System capability**: SystemCapability.ArkUI.ArkUI.Full
205
206### changeIndex
207
208changeIndex(index: number, useAnimation?: boolean): void
209
210Moves to a specific navigation index.
211
212**Widget capability**: This API can be used in ArkTS widgets since API version 15.
213
214**Atomic service API**: This API can be used in atomic services since API version 15.
215
216**System capability**: SystemCapability.ArkUI.ArkUI.Full
217
218**Parameters**
219
220| Name     | Type      | Mandatory | Description    |
221| -------- | ---------- | ---- | -------- |
222| index| number | Yes   | Target navigation index.|
223| useAnimation| boolean | No   | Whether to use an animation for when the target index is reached. The value **true** means to use an animation, and **false** means the opposite.<br>Default value: **false**.|
224
225## Example
226
227### Example 1: Using a Dot Indicator with a Swiper Component
228This example shows how to bind a dot-style **Indicator** component to a **Swiper** component using **IndicatorComponentController**.
229```
230@Entry
231@Component
232struct DotIndicatorDemo {
233  private indicatorController: IndicatorComponentController = new IndicatorComponentController();
234  private swiperController: SwiperController = new SwiperController();
235  @State list: number[] = [];
236  aboutToAppear(): void {
237    for (let i = 1; i <= 6; i++) {
238      this.list.push(i);
239    }
240  }
241
242  build() {
243    Column() {
244      Swiper(this.swiperController) {
245        ForEach(this.list, (item: string) => {
246          Text(item.toString())
247            .width('100%')
248            .height(160)
249            .backgroundColor(0xAFEEEE)
250            .textAlign(TextAlign.Center)
251            .fontSize(30)
252        }, (item: string) => item)
253      }
254      .cachedCount(2)
255      .index(0)
256      .autoPlay(true)
257      .interval(2000)
258      .indicator(this.indicatorController)
259      .loop(true)
260      .duration(1000)
261      .itemSpace(0)
262      .curve(Curve.Linear)
263      .onChange((index: number) => {
264        console.info(index.toString());
265      })
266
267      IndicatorComponent(this.indicatorController)
268        .initialIndex(0)
269        .style(
270          new DotIndicator()
271            .itemWidth(15)
272            .itemHeight(15)
273            .selectedItemWidth(15)
274            .selectedItemHeight(15)
275            .color(Color.Gray)
276            .selectedColor(Color.Blue))
277        .loop(true)
278        .count(6)
279        .vertical(true)
280        .onChange((index: number) => {
281          console.log("current index: " + index );
282        })
283    }
284  }
285}
286```
287![bindIndicatorDotStyle](figures/bindIndicatorDotStyle.gif)
288
289### Example 2: Using a Digit Indicator with a Swiper Component
290
291This example shows how to bind a digit-style **Indicator** component to a **Swiper** component using **IndicatorComponentController**.
292
293```
294@Entry
295@Component
296struct DigitIndicatorDemo {
297  private indicatorController: IndicatorComponentController = new IndicatorComponentController();
298  private swiperController: SwiperController = new SwiperController();
299  @State list: number[] = [];
300  aboutToAppear(): void {
301    for (let i = 1; i <= 6; i++) {
302      this.list.push(i);
303    }
304  }
305
306  build() {
307    Column() {
308      Swiper(this.swiperController) {
309        ForEach(this.list, (item: string) => {
310          Text(item.toString())
311            .width('100%')
312            .height(160)
313            .backgroundColor(0xAFEEEE)
314            .textAlign(TextAlign.Center)
315            .fontSize(30)
316        }, (item: string) => item)
317      }
318      .cachedCount(2)
319      .index(0)
320      .autoPlay(true)
321      .interval(2000)
322      .indicator(this.indicatorController)
323      .loop(true)
324      .duration(1000)
325      .itemSpace(0)
326      .curve(Curve.Linear)
327      .onChange((index: number) => {
328        console.info(index.toString());
329      })
330
331      IndicatorComponent(this.indicatorController)
332        .initialIndex(0)
333        .style(Indicator.digit()
334          .fontColor(Color.Gray)
335          .selectedFontColor(Color.Gray)
336          .digitFont({ size: 20, weight: FontWeight.Bold })
337          .selectedDigitFont({ size: 20, weight: FontWeight.Normal }))
338        .loop(true)
339        .count(6)
340        .vertical(true)
341        .onChange((index: number) => {
342          console.log("current index: " + index );
343        })
344    }
345  }
346}
347```
348
349![bindIndicatorDigitStyle](figures/bindIndicatorDigitStyle.gif)
350