• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ArcSlider
2
3The **ArcSlider** component is designed for circular screens to quickly adjust settings, such as the volume and brightness.
4
5>  **NOTE**
6>
7>  This component is supported since API version 18. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import {
13  ArcSlider,
14  ArcSliderPosition,
15  ArcSliderOptions,
16  ArcSliderValueOptions,
17  ArcSliderLayoutOptions,
18  ArcSliderStyleOptions,
19  ArcSliderValueOptionsConstructorOptions,
20  ArcSliderLayoutOptionsConstructorOptions,
21  ArcSliderStyleOptionsConstructorOptions,
22  ArcSliderOptionsConstructorOptions
23} from '@kit.ArkUI'
24```
25
26## Child Components
27
28Not supported
29
30## Attributes
31
32The [universal attributes](ts-component-general-attributes.md) are not supported.
33
34## Events
35
36The [universal events](ts-component-general-events.md) are not supported.
37
38## ArcSlider
39
40ArcSlider({ options: ArcSliderOptions })
41
42Creates an **ArcSlider** instance. The input parameter is the configuration for the arc slider.
43
44**Decorator**: @Component
45
46**Atomic service API**: This API can be used in atomic services since API version 18.
47
48**System capability**: SystemCapability.ArkUI.ArkUI.Circle
49
50**Parameters**
51
52| Name   | Type                                 | Mandatory| Description                                                        |
53| ------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
54| options | [ArcSliderOptions](#arcslideroptions) | Yes  | Parameters of the arc slider.<br>Default value: default values of all properties of [ArcSliderOptions](#arcslideroptions)|
55
56## ArcSliderOptions
57
58Defines the properties of the arc slider.
59
60**Decorator type**: @ObservedV2
61
62**Atomic service API**: This API can be used in atomic services since API version 18.
63
64**System capability**: SystemCapability.ArkUI.ArkUI.Circle
65
66| Name| Type| Mandatory| Decorator| Description|
67| -------- | -------- | -------- | -------- | -------- |
68| valueOptions | [ArcSliderValueOptions](#arcslidervalueoptions) | No| @Trace | Value of the arc slider.<br>Default value: default values of all properties of [ArcSliderValueOptions](#arcslidervalueoptions)|
69| layoutOptions | [ArcSliderLayoutOptions](#arcsliderlayoutoptions) | No| @Trace | Layout of the arc slider.<br>Default value: default values of all properties of [ArcSliderLayoutOptions](#arcsliderlayoutoptions)|
70| styleOptions | [ArcSliderStyleOptions](#arcsliderstyleoptions) | No| @Trace | Style of the arc slider.<br>Default value: default values of all properties of [ArcSliderStyleOptions](#arcsliderstyleoptions)|
71| digitalCrownSensitivity | [CrownSensitivity](ts-appendix-enums.md#crownsensitivity18) | No| @Trace | Sensitivity to the digital crown rotation.<br>Default value: **CrownSensitivity.MEDIUM**|
72| onTouch | [ArcSliderTouchHandler](#arcslidertouchhandler) | No| @Trace | Callback invoked to notify the application when the arc slider is touched.<br>If no value is provided, no callback is performed.|
73| onChange | [ArcSliderChangeHandler](#arcsliderchangehandler) | No| @Trace | Callback invoked to notify the application when the progress value of the arc slider changes.<br>If no value is provided, no callback is performed.|
74| onEnlarge | [ArcSliderEnlargeHandler](#arcsliderenlargehandler) | No| @Trace | Callback invoked to notify the application when the arc slider is zoomed in or out.<br>If no value is provided, no callback is performed.|
75
76### constructor
77
78constructor(options?: ArcSliderOptionsConstructorOptions)
79
80A constructor used to create an **ArcSliderOptions** instance.
81
82**Atomic service API**: This API can be used in atomic services since API version 18.
83
84**System capability**: SystemCapability.ArkUI.ArkUI.Circle
85
86**Parameters**
87
88| Name | Type                                                        | Mandatory| Description                        |
89| ------- | ------------------------------------------------------------ | ---- | ---------------------------- |
90| options | [ArcSliderOptionsConstructorOptions](#arcslideroptionsconstructoroptions) | No  | Construction information for **ArcSliderOptions**.|
91
92## ArcSliderValueOptions
93
94Defines the value of the arc slider.
95
96**Decorator type**: @ObservedV2
97
98**Atomic service API**: This API can be used in atomic services since API version 18.
99
100**System capability**: SystemCapability.ArkUI.ArkUI.Circle
101
102| Name | Type  | Mandatory| Decorator| Description                                                        |
103| ----- | ------ | ---- | ---------- | ------------------------------------------------------------ |
104| progress | number | No  | @Trace     | Current progress.<br>Default value: same as the value of **min**           |
105| min   | number | No  | @Trace     | Minimum value.<br>Default value: **0**                                 |
106| max   | number | No  | @Trace     | Maximum value.<br>Default value: **100**<br>**NOTE**<br>If the value of **min** is greater than or equal to that of **max**, **min** is set to **0** and **max** **100**.<br>If the value is not within the [min, max] range, the value of **min** or **max** is used, whichever is closer.|
107
108### constructor
109
110constructor(options?: ArcSliderValueOptionsConstructorOptions)
111
112A constructor used to create an **ArcSliderValueOptions** instance.
113
114**Atomic service API**: This API can be used in atomic services since API version 18.
115
116**System capability**: SystemCapability.ArkUI.ArkUI.Circle
117
118**Parameters**
119
120| Name | Type                                                        | Mandatory| Description                             |
121| ------- | ------------------------------------------------------------ | ---- | --------------------------------- |
122| options | [ArcSliderValueOptionsConstructorOptions](#arcslidervalueoptionsconstructoroptions) | No  | Construction information for **ArcSliderValueOptions**.|
123
124## ArcSliderLayoutOptions
125
126Defines the layout of the arc slider.
127
128**Decorator type**: @ObservedV2
129
130**Atomic service API**: This API can be used in atomic services since API version 18.
131
132**System capability**: SystemCapability.ArkUI.ArkUI.Circle
133
134| Name    | Type                                   | Mandatory| Decorator| Description                                                        |
135| -------- | --------------------------------------- | ---- | ---------- | ------------------------------------------------------------ |
136| reverse  | boolean                                 | No  | @Trace     | Whether the value range of the arc slider is reversed.<br>Default value: **true** (swipe from bottom to top)|
137| position | [ArcSliderPosition](#arcsliderposition) | No  | @Trace     | Position of the arc slider on the screen.<br>Default value: **ArcSliderPosition.RIGHT**|
138
139### constructor
140
141constructor(options?: ArcSliderLayoutOptionsConstructorOptions)
142
143A constructor used to create an **ArcSliderLayoutOptions** instance.
144
145**Atomic service API**: This API can be used in atomic services since API version 18.
146
147**System capability**: SystemCapability.ArkUI.ArkUI.Circle
148
149**Parameters**
150
151| Name | Type                                                        | Mandatory| Description                              |
152| ------- | ------------------------------------------------------------ | ---- | ---------------------------------- |
153| options | [ArcSliderLayoutOptionsConstructorOptions](#arcsliderlayoutoptionsconstructoroptions) | No  | Construction information for **ArcSliderLayoutOptions**.|
154
155## ArcSliderStyleOptions
156
157Defines the style of the arc slider.
158
159**Decorator type**: @ObservedV2
160
161**Atomic service API**: This API can be used in atomic services since API version 18.
162
163**System capability**: SystemCapability.ArkUI.ArkUI.Circle
164
165| Name                | Type  | Mandatory| Decorator| Description                                                        |
166| -------------------- | ------ | ---- | ---------- | ------------------------------------------------------------ |
167| trackThickness       | number | No  | @Trace     | Stroke width of the arc slider in the normal state, in vp.<br>Default value: **5**<br>The value ranges from 5 to 16. If an invalid value is set, the default value is used.|
168| activeTrackThickness | number | No  | @Trace     | Stroke width of the arc slider when it is zoomed in, in vp.<br>Default value: **24**<br>The value ranges from 24 to 36. If an invalid value is set, the default value is used.|
169| trackColor           | string | No  | @Trace     | Background color of the stroke.<br>Default value: **#33FFFFFF**                     |
170| selectedColor        | string | No  | @Trace     | Highlight color of the stroke.<br>Default value: **#FF5EA1FF**                     |
171| trackBlur            | number | No  | @Trace     | Blur effect applied to the stroke background, in vp.<br>Default value: **20**<br>If a value less than 0 is set, the default value is used.|
172
173### constructor
174
175constructor(options?: ArcSliderStyleOptionsConstructorOptions)
176
177A constructor used to create an **ArcSliderStyleOptions** instance.
178
179**Atomic service API**: This API can be used in atomic services since API version 18.
180
181**System capability**: SystemCapability.ArkUI.ArkUI.Circle
182
183**Parameters**
184
185| Name | Type                                                        | Mandatory| Description                             |
186| ------- | ------------------------------------------------------------ | ---- | --------------------------------- |
187| options | [ArcSliderStyleOptionsConstructorOptions](#arcsliderstyleoptionsconstructoroptions) | No  | Construction information for **ArcSliderStyleOptions**.|
188
189## ArcSliderPosition
190
191Defines the position of the arc slider on the screen.
192
193**Atomic service API**: This API can be used in atomic services since API version 18.
194
195**System capability**: SystemCapability.ArkUI.ArkUI.Circle
196
197| Name | Value  | Description                            |
198| ----- | ---- | -------------------------------- |
199| LEFT  | 0    | The arc slider is displayed on the left.|
200| RIGHT | 1    | The arc slider is displayed on the right.|
201
202## ArcSliderTouchHandler
203
204type ArcSliderTouchHandler = (event: TouchEvent) => void
205
206Defines the callback invoked to notify the application when the arc slider is touched.
207
208**Atomic service API**: This API can be used in atomic services since API version 18.
209
210**System capability**: SystemCapability.ArkUI.ArkUI.Circle
211
212**Parameters**
213
214| Name| Type                                                        | Mandatory| Description                |
215| ------ | ------------------------------------------------------------ | ---- | -------------------- |
216| event  | [TouchEvent](ts-universal-events-touch.md#touchevent) | Yes  | **TouchEvent** object.|
217
218## ArcSliderChangeHandler
219
220type ArcSliderChangeHandler = (progress: number) => void
221
222Defines the callback invoked to notify the application when the progress value of the arc slider changes.
223
224**Atomic service API**: This API can be used in atomic services since API version 18.
225
226**System capability**: SystemCapability.ArkUI.ArkUI.Circle
227
228**Parameters**
229
230| Name  | Type  | Mandatory| Description                |
231| -------- | ------ | ---- | -------------------- |
232| progress | number | Yes  | Current progress of the slider.|
233
234## ArcSliderEnlargeHandler
235
236type ArcSliderEnlargeHandler = (isEnlarged: boolean) => void
237
238Defines the callback invoked to notify the application when the arc slider is zoomed in or out.
239
240**Atomic service API**: This API can be used in atomic services since API version 18.
241
242**System capability**: SystemCapability.ArkUI.ArkUI.Circle
243
244**Parameters**
245
246| Name    | Type   | Mandatory| Description                                                        |
247| ---------- | ------- | ---- | ------------------------------------------------------------ |
248| isEnlarged | boolean | Yes  | Whether the arc slider is zoomed in.<br>**false**: The arc slider is zoomed out.<br>**true**: The arc slider is zoomed in.|
249
250## ArcSliderOptionsConstructorOptions
251
252Defines the construction information for **ArcSliderOptions**.
253
254**Atomic service API**: This API can be used in atomic services since API version 18.
255
256**System capability**: SystemCapability.ArkUI.ArkUI.Circle
257
258| Name                   | Type                                                       | Mandatory| Description                                                        |
259| ----------------------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
260| valueOptions            | [ArcSliderValueOptions](#arcslidervalueoptions)             | No  | Value of the arc slider.<br>Default value: default values of all properties of [ArcSliderValueOptions](#arcslidervalueoptions)|
261| layoutOptions           | [ArcSliderLayoutOptions](#arcsliderlayoutoptions)           | No  | Layout of the arc slider.<br>Default value: default values of all properties of [ArcSliderLayoutOptions](#arcsliderlayoutoptions)|
262| styleOptions            | [ArcSliderStyleOptions](#arcsliderstyleoptions)             | No  | Style of the arc slider.<br>Default value: default values of all properties of [ArcSliderStyleOptions](#arcsliderstyleoptions)|
263| digitalCrownSensitivity | [CrownSensitivity](ts-appendix-enums.md#crownsensitivity18) | No  | Sensitivity to the digital crown rotation.<br>Default value: **CrownSensitivity.MEDIUM**  |
264| onTouch                 | [ArcSliderTouchHandler](#arcslidertouchhandler)             | No  | Callback invoked to notify the application when the arc slider is touched.<br>If no value is provided, no callback is performed.|
265| onChange                | [ArcSliderChangeHandler](#arcsliderchangehandler)           | No  | Callback invoked to notify the application when the progress value of the arc slider changes.<br>If no value is provided, no callback is performed.|
266| onEnlarge               | [ArcSliderEnlargeHandler](#arcsliderenlargehandler)         | No  | Callback invoked to notify the application when the arc slider is zoomed in or out.<br>If no value is provided, no callback is performed.|
267
268## ArcSliderValueOptionsConstructorOptions
269
270Defines the construction information for **ArcSliderValueOptions**.
271
272**Atomic service API**: This API can be used in atomic services since API version 18.
273
274**System capability**: SystemCapability.ArkUI.ArkUI.Circle
275
276| Name | Type  | Mandatory| Description                                                        |
277| ----- | ------ | ---- | ------------------------------------------------------------ |
278| progress | number | No  | Current progress.<br>Default value: same as the value of **min**          |
279| min   | number | No  | Minimum value.<br>Default value: **0**                                 |
280| max   | number | No  | Maximum value.<br>Default value: **100**<br>**NOTE**<br>If the value of **min** is greater than or equal to that of **max**, **min** is set to **0** and **max** **100**.<br>If the value is not within the [min, max] range, the value of **min** or **max** is used, whichever is closer.|
281
282## ArcSliderLayoutOptionsConstructorOptions
283
284Defines the construction information for **ArcSliderStyleOptions**.
285
286**Atomic service API**: This API can be used in atomic services since API version 18.
287
288**System capability**: SystemCapability.ArkUI.ArkUI.Circle
289
290| Name    | Type                                   | Mandatory| Description                                                        |
291| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
292| reverse  | boolean                                 | No  | Whether the value range of the arc slider is reversed.<br>Default value: **true** (swipe from bottom to top)|
293| position | [ArcSliderPosition](#arcsliderposition) | No  | Position of the arc slider on the screen.<br>Default value: **ArcSliderPosition.RIGHT**|
294
295## ArcSliderStyleOptionsConstructorOptions
296
297Defines the construction information for **ArcSliderStyleOptions**.
298
299**Atomic service API**: This API can be used in atomic services since API version 18.
300
301**System capability**: SystemCapability.ArkUI.ArkUI.Circle
302
303| Name                | Type  | Mandatory| Description                                                        |
304| -------------------- | ------ | ---- | ------------------------------------------------------------ |
305| trackThickness       | number | No  | Stroke width of the arc slider in the normal state, in vp.<br>Default value: **5**<br>The value ranges from 5 to 16. If an invalid value is set, the default value is used.|
306| activeTrackThickness | number | No  | Stroke width of the arc slider when it is zoomed in, in vp.<br>Default value: **24**<br>The value ranges from 24 to 36. If an invalid value is set, the default value is used.|
307| trackColor           | string | No  | Background color of the stroke.<br>Default value: **#33FFFFFF**                     |
308| selectedColor        | string | No  | Highlight color of the stroke.<br>Default value: **#FF5EA1FF**                     |
309| trackBlur            | number | No  | Blur effect applied to the stroke background, in vp.<br>Default value: **20**<br>If a value less than 0 is set, the default value is used.|
310
311## Example
312
313```ts
314// xxx.ets
315import {
316  ArcSlider,
317  ArcSliderPosition,
318  ArcSliderOptions,
319  ArcSliderValueOptions,
320  ArcSliderLayoutOptions,
321  ArcSliderStyleOptions,
322  ArcSliderValueOptionsConstructorOptions,
323  ArcSliderLayoutOptionsConstructorOptions,
324  ArcSliderStyleOptionsConstructorOptions,
325  ArcSliderOptionsConstructorOptions
326} from '@kit.ArkUI'
327
328@Entry
329@ComponentV2
330struct ArcSliderExample {
331  valueOptionsConstructorOptions: ArcSliderValueOptionsConstructorOptions = {
332    progress: 60,
333    min: 10,
334    max: 110
335  }
336
337  layoutOptionsConstructorOptions: ArcSliderLayoutOptionsConstructorOptions = {
338    reverse: true,
339    position: ArcSliderPosition.RIGHT
340  }
341  styleOptionsConstructorOptions: ArcSliderStyleOptionsConstructorOptions = {
342    trackThickness: 8,
343    activeTrackThickness: 30,
344    trackColor: '#ffd5d5d5',
345    selectedColor: '#ff2787d9',
346    trackBlur: 20
347  }
348  valueOptions: ArcSliderValueOptions = new ArcSliderValueOptions(this.valueOptionsConstructorOptions)
349  layoutOptions: ArcSliderLayoutOptions = new ArcSliderLayoutOptions(this.layoutOptionsConstructorOptions)
350  styleOptions: ArcSliderStyleOptions = new ArcSliderStyleOptions(this.styleOptionsConstructorOptions)
351  arcSliderOptionsConstructorOptions: ArcSliderOptionsConstructorOptions = {
352    valueOptions: this.valueOptions,
353    layoutOptions: this.layoutOptions,
354    styleOptions: this.styleOptions,
355    digitalCrownSensitivity:CrownSensitivity.LOW,
356    onTouch: (event: TouchEvent) => {
357    },
358    onChange: (progress: number) => {
359    },
360    onEnlarge: (isEnlarged: boolean) => {
361    }
362  }
363  arcSliderOptions: ArcSliderOptions = new ArcSliderOptions(this.arcSliderOptionsConstructorOptions)
364
365  build() {
366    Column() {
367      ArcSlider({ options: this.arcSliderOptions })}
368      .width('100%')
369  }
370}
371```
372
373![arcslider](figures/arcslider.gif)
374