1# advanced.Counter
2
3A counter is a component used to accurately adjust values.
4
5>  **NOTE**
6>
7>  This component is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```
12import { CounterType, CounterComponent, CounterOptions, DateData } from '@kit.ArkUI';
13```
14
15##  Child Components
16
17Not supported
18
19## CounterComponent
20
21CounterComponent({ options: CounterOptions })
22
23Defines a counter.
24
25**Decorator**: @Component
26
27**Atomic service API**: This API can be used in atomic services since API version 12.
28
29**System capability**: SystemCapability.ArkUI.ArkUI.Full
30
31**Parameters**
32
33| Name   | Type                             | Mandatory| Decorator| Description                   |
34| ------- | --------------------------------- | ---- | ---------- | ----------------------- |
35| options | [CounterOptions](#counteroptions) | Yes  | @Prop      | Parameters of the counter.|
36
37## CounterOptions
38
39Defines the type and style parameters of the counter.
40
41**Atomic service API**: This API can be used in atomic services since API version 12.
42
43**System capability**: SystemCapability.ArkUI.ArkUI.Full
44
45| Name       | Type      | Mandatory       | Description                           |
46| ----------- | ---------- | ------| --------------------------------- |
47| type | [CounterType](#countertype) | Yes  | Type of the current counter.|
48| direction<sup>12+</sup> | [Direction](ts-appendix-enums.md#direction) | No| Layout direction.<br>Default value: **Direction.Auto**|
49| numberOptions | [NumberStyleOptions](#numberstyleoptions) | No   | Parameters of the number style counter.|
50| inlineOptions | [InlineStyleOptions](#inlinestyleoptions) | No| Parameters of the inline number style counter.|
51| dateOptions | [DateStyleOptions](#datestyleoptions) | No| Parameters of the inline date style counter.|
52
53A counter type must go with parameters of the matching counter style. Below is a mapping between the counter types and counter styles.
54
55| Counter Type            | Counter Style       |
56| ----------------------- | ------------------ |
57| CounterType.LIST        | NumberStyleOptions |
58| CounterType.COMPACT     | NumberStyleOptions |
59| CounterType.INLINE      | InlineStyleOptions |
60| CounterType.INLINE_DATE | DateStyleOptions   |
61
62## CounterType
63
64Enumerates the counter types.
65
66**Atomic service API**: This API can be used in atomic services since API version 12.
67
68**System capability**: SystemCapability.ArkUI.ArkUI.Full
69
70| Name       | Description                       |
71| ----------- | --------------------------- |
72| LIST        | List counter.            |
73| COMPACT     | Compact counter.            |
74| INLINE      | Inline number counter.|
75| INLINE_DATE | Inline date counter.      |
76
77## CommonOptions
78
79Defines common attributes and events of counters.
80
81**Atomic service API**: This API can be used in atomic services since API version 12.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85
86| Name           | Type                     | Mandatory| Default Value| Description                                                        |
87| --------------- | ------------------------- | ---- | ------ | ------------------------------------------------------------ |
88| focusable       | boolean                   | No  | true   | Whether the counter is focusable.<br>**NOTE**<br>This attribute takes effect for the number style counter.|
89| step            | number                    | No  | 1      | Step of the counter.<br>Value range: an integer greater than or equal to 1.         |
90| onHoverIncrease | (isHover: boolean) =>void | No  | -      | Callback invoked when the mouse pointer is moved over or away from the Increase button of the counter.<br>**isHover**: whether the mouse pointer hovers over the component. The value **true** means that the mouse pointer enters the component, and the value **false** means that the mouse pointer leaves the component.|
91| onHoverDecrease | (isHover: boolean) =>void | No  | -      | Callback invoked when the mouse pointer is moved over or away from the Decrease button of the counter.<br>**isHover**: whether the mouse pointer hovers over the component. The value **true** means that the mouse pointer enters the component, and the value **false** means that the mouse pointer leaves the component.|
92
93##  InlineStyleOptions
94
95Defines the attributes and events of the inline number style counter.
96
97Inherits from [CommonOptions](#commonoptions).
98
99**Atomic service API**: This API can be used in atomic services since API version 12.
100
101**System capability**: SystemCapability.ArkUI.ArkUI.Full
102
103| Name     | Type                  | Mandatory| Default Value| Description                                                  |
104| --------- | ---------------------- | ---- | ------ | ------------------------------------------------------ |
105| value     | number                 | No  | 0      | Initial value of the counter.                                 |
106| min       | number                 | No  | 0      | Minimum value of the counter.                                 |
107| max       | number                 | No  | 999    | Maximum value of the counter.                                 |
108| textWidth | number                 | No  | 0      | Text width of the counter.                                  |
109| onChange  | (value: number) =>void | No  | -      | Callback invoked when the value changes. The current value is returned.<br>**value**: current value.|
110
111## NumberStyleOptions
112
113Defines the attributes and events of the number style counter.
114
115Inherits from [InlineStyleOptions](#inlinestyleoptions).
116
117**Atomic service API**: This API can be used in atomic services since API version 12.
118
119**System capability**: SystemCapability.ArkUI.ArkUI.Full
120
121| Name           | Type                                                        | Mandatory| Default Value| Description                                         |
122| --------------- | ------------------------------------------------------------ | ---- | ------ | --------------------------------------------- |
123| label           | [ResourceStr](ts-types.md#resourcestr) | No  | -      | Label of the counter.                      |
124| onFocusIncrease | () =>void                                                    | No  | -      | Callback invoked when the Increase button of the counter gains focus.|
125| onFocusDecrease | () =>void                                                    | No  | -      | Callback invoked when the Decrease button of the counter gains focus.|
126| onBlurIncrease  | () =>void                                                    | No  | -      | Callback invoked when the Increase button of the counter loses focus.|
127| onBlurDecrease  | () =>void                                                    | No  | -      | Callback invoked when the Decrease button of the counter loses focus.|
128
129## DateStyleOptions
130
131Defines the attributes and events of the inline date style counter.
132
133Inherits from [CommonOptions](#commonoptions).
134
135**Atomic service API**: This API can be used in atomic services since API version 12.
136
137**System capability**: SystemCapability.ArkUI.ArkUI.Full
138
139| Name        | Type                               | Mandatory| Default Value| Description                                                     |
140| ------------ | ----------------------------------- | ---- | ------ | --------------------------------------------------------- |
141| year         | number                              | No  | 1      | Initial year of the counter.                                 |
142| month        | number                              | No  | 1      | Initial month of the counter.                                 |
143| day          | number                              | No  | 1      | Initial day of the counter.                                   |
144| onDateChange | (date: [DateData](#datedata))=>void | No  | -      | Callback invoked when the date changes. The current date is returned.<br>**date**: current date.|
145
146## DateData
147
148Defines common date attributes and methods.
149
150**Atomic service API**: This API can be used in atomic services since API version 12.
151
152**System capability**: SystemCapability.ArkUI.ArkUI.Full
153
154| Name      | Type  | Description                        |
155| ---------- | ------ | ---------------------------- |
156| year       | number | Initial year of the counter.    |
157| month      | number | Initial month of the counter.    |
158| day        | number | Initial day of the counter.      |
159
160### constructor
161
162constructor(year: number, month: number, day: number)
163
164A constructor used to create a **DateData** object.
165
166**Atomic service API**: This API can be used in atomic services since API version 12.
167
168**System capability**: SystemCapability.ArkUI.ArkUI.Full
169
170| Name| Type| Description|
171| ---------- | ------ | ---------------------------- |
172| year       | number | Initial year of the counter.    |
173| month      | number | Initial month of the counter.    |
174| day        | number | Initial day of the counter.      |
175
176### toString
177
178toString(): string
179
180Current date.
181
182**Atomic service API**: This API can be used in atomic services since API version 12.
183
184**System capability**: SystemCapability.ArkUI.ArkUI.Full
185
186**Return value**
187
188| Type| Description|
189| -------- | -------- |
190| string | Current date.|
191
192## Example
193
194### Example 1
195
196```ts
197import { CounterType, CounterComponent } from '@kit.ArkUI';
198
199@Entry
200@Component
201struct ListCounterExample {
202  build() {
203    Column() {
204      // List counter
205      CounterComponent({
206        options: {
207          type: CounterType.LIST,
208          numberOptions: {
209            label: "Price",
210            min: 0,
211            value: 5,
212            max: 10
213          }
214        }
215      })
216    }
217  }
218}
219```
220
221![listcounter](figures/listcounter.gif)
222### Example 2
223```ts
224import { CounterType, CounterComponent } from '@kit.ArkUI';
225
226@Entry
227@Component
228struct CompactCounterExample {
229  build() {
230    Column() {
231      // Compact counter
232      CounterComponent({
233        options: {
234          type: CounterType.COMPACT,
235          numberOptions: {
236            label: "Quantity",
237            value: 10,
238            min: 0,
239            max: 100,
240            step: 10
241          }
242        }
243      })
244    }
245  }
246}
247```
248![compactcounter](figures/compactcounter.gif)
249### Example 3
250```ts
251import { CounterType, CounterComponent } from '@kit.ArkUI';
252
253@Entry
254@Component
255struct NumberStyleExample {
256  build() {
257    Column() {
258      // Inline number counter
259      CounterComponent({
260        options: {
261          type: CounterType.INLINE,
262          inlineOptions: {
263            value: 100,
264            min: 10,
265            step: 2,
266            max: 1000,
267            textWidth: 100,
268            onChange: (value: number) => {
269              console.log("onDateChange Date: " + value.toString());
270            }
271          }
272        }
273      })
274    }
275  }
276}
277```
278![numberstyle](figures/numberstyle.gif)
279### Example 4
280```ts
281import { CounterType, CounterComponent, DateData } from '@kit.ArkUI';
282
283@Entry
284@Component
285struct DataStyleExample {
286  build() {
287    Column() {
288      // Inline date counter
289      CounterComponent({
290        options: {
291          type: CounterType.INLINE_DATE,
292          dateOptions: {
293            year: 2016,
294            onDateChange: (date: DateData) => {
295              console.log("onDateChange Date: " + date.toString());
296            }
297          }
298        }
299      })
300    }
301  }
302}
303```
304![datestyle](figures/datestyle.gif)
305
306### Example 5
307This example shows a mirrored layout of different types of counters.
308
309```ts
310// xxx.ets
311import { CounterType, CounterComponent, DateData } from '@kit.ArkUI';
312
313@Entry
314@Component
315struct CounterPage {
316  @State currentDirection: Direction = Direction.Rtl
317
318  build() {
319    Column({}) {
320
321      // List counter
322      CounterComponent({
323        options: {
324          direction: this.currentDirection,
325          type: CounterType.LIST,
326          numberOptions: {
327            label: "Price",
328            min: 0,
329            value: 5,
330            max: 10,
331          }
332        }
333      })
334        .width('80%')
335
336      // Compact counter
337      CounterComponent({
338        options: {
339          direction: this.currentDirection,
340          type: CounterType.COMPACT,
341          numberOptions: {
342            label: "Quantity",
343            value: 10,
344            min: 0,
345            max: 100,
346            step: 10
347          }
348        }
349      }).margin({ top: 20 })
350
351      // Inline number counter
352      CounterComponent({
353        options: {
354          type: CounterType.INLINE,
355          direction: this.currentDirection,
356          inlineOptions: {
357            value: 100,
358            min: 10,
359            step: 2,
360            max: 1000,
361            textWidth: 100,
362            onChange: (value: number) => {
363              console.log("onDateChange Date: " + value.toString());
364            }
365          }
366        }
367      }).margin({ top: 20 })
368      // Inline date counter
369      CounterComponent({
370        options: {
371          direction: this.currentDirection,
372          type: CounterType.INLINE_DATE,
373          dateOptions: {
374            year: 2024,
375            onDateChange: (date: DateData) => {
376              console.log("onDateChange Date: " + date.toString());
377            }
378          }
379        }
380      }).margin({ top: 20 })
381    }
382    .width('100%')
383    .height('100%')
384    .justifyContent(FlexAlign.Center)
385    .alignItems(HorizontalAlign.Center)
386  }
387}
388```
389![datestyle](figures/counter_direction.png)
390