| type | string | line | No | Chart type. Dynamic modification is not supported. Available values include:<br>-**bar**: bar chart<br>-**line**: line chart<br>-**gauge**: gauge chart<br>-**progress**5+: circle chart of progresses<br>-**loading**5+: circle chart of loading processes<br>-**rainbow**5+: circle chart of proportions |
| options | [ChartOptions](js-components-basic-chart.md) | - | No | Chart parameters. You must set parameters for bar charts and line charts. Parameter settings for gauge charts do not take effect. You can set the minimum value, maximum value, scale, and line width of the x-axis or y-axis, whether to display the x-axis and y-axis, and whether the line is smooth. Dynamic modification is not supported. |
| datasets | Array\<[ChartDataset](js-components-basic-chart.md)> | - | No | Data set. You must set data sets for bar charts and line charts. Data set for a gauge chart does not take effect. You can set multiple datasets and their background colors. |
| segments5+ | [DataSegment](js-components-basic-chart.md)\| Array\<[DataSegment](js-components-basic-chart.md)> | - | No | Data structures used by **progress**, **loading**, and **rainbow** charts.**DataSegment** is available for **progress** and **loading** charts.**Array\<[DataSegment](js-components-basic-chart.md)>** is available for **rainbow** charts. A maximum of nine **DataSegment** are supported in the array. |
| effects5+ | boolean | true | No | Whether to enable the effects for **progress** and **rainbow** charts. |
| animationduration6+ | number | 3000 | No | Animation duration for expanding a **rainbow** chart, in milliseconds. |
| Name | Type | Default Value | Mandatory | Description |
| type | string | line | No | Chart type. Dynamic modification is not supported. Available values include:<br>- **bar**: bar chart<br>- **line**: line chart<br>- **gauge**: gauge chart<br>- **progress**<sup>5+</sup>: circle chart of progresses<br>- **loading**<sup>5+</sup>: circle chart of loading processes<br>- **rainbow**<sup>5+</sup>: circle chart of proportions|
| options | ChartOptions | - | No | Chart parameters. You must set parameters for bar charts and line charts. Parameter settings for gauge charts do not take effect. You can set the minimum value, maximum value, scale, and line width of the x-axis or y-axis, whether to display the x-axis and y-axis, and whether the line is smooth. Dynamic modification is not supported.|
| datasets | Array<ChartDataset> | - | No | Data sets. You must set data sets for bar charts and line charts. Data sets for a gauge chart do not take effect. You can set multiple datasets and their background colors.|
| segments<sup>5+</sup> | DataSegment \| Array<DataSegment> | - | No | Data structures used by **progress**, **loading**, and **rainbow** charts.<br>**DataSegment** is available for **progress** and **loading** charts.<br>**Array<DataSegment>** is available for **rainbow** charts. A maximum of nine **DataSegment**s are supported in the array.|
| effects<sup>5+</sup> | boolean | true | No | Whether to enable the effects for **progress** and **rainbow** charts. |
| animationduration<sup>6+</sup> | number | 3000 | No | Animation duration for expanding a **rainbow** chart, in milliseconds. |
**Table 1** ChartOptions
| Name | Type | Default Value | Mandatory | Description |
| xAxis | [ChartAxis](js-components-basic-chart.md) | - | Yes | X-axis parameters. You can set the minimum value, maximum value, and scale of the x-axis, and whether to display the x-axis. |
| yAxis | [ChartAxis](js-components-basic-chart.md) | - | Yes | Y-axis parameters. You can set the minimum value, maximum value, and scale of the y-axis, and whether to display the y-axis. |
| series | [ChartSeries](js-components-basic-chart.md) | - | No | Data sequence parameters.<br/>-Line style, such as the line width and whether the line is smooth.<br/>-Style and size of the white point at the start of the line.NOTE:Only line charts support this attribute. |
| Name | Type | Default Value | Mandatory | Description |
| xAxis | ChartAxis | - | Yes | X-axis parameters. You can set the minimum value, maximum value, and scale of the x-axis, and whether to display the x-axis. |
| yAxis | ChartAxis | - | Yes | Y-axis parameters. You can set the minimum value, maximum value, and scale of the y-axis, and whether to display the y-axis. |
| series | ChartSeries | - | No | Data sequence parameters. Only line charts support this attribute.<br>- Line style, such as the line width and whether the line is smooth.<br>- Style and size of the white point at the start of the line.|
**Table 2** ChartDataset
| Name | Type | Default Value | Mandatory | Description |
| min | number | 0 | No | Minimum value of the axis.NOTE:Only line charts support negative numbers. |
| max | number | 100 | No | Maximum value of the axis.NOTE:Only line charts support negative numbers. |
| axisTick | number | 10 | No | Number of scales displayed on the axis.NOTE:The value ranges from 1 to 20. The display effect depends on the calculation result of Number of pixels occupied by the image width/(**max**-**min**).In the bar chart, the number of bars in each group of data is the same as the number of scales, and the bars are displayed at the scales. |
| display | boolean | false | No | Whether to display the axis. |
| color | \<color> | #c0c0c0 | No | Axis color. |
| Name | Type | Default Value | Mandatory | Description |
| min | number | 0 | No | Minimum value of the axis. Only line charts support negative numbers. |
| max | number | 100 | No | Maximum value of the axis. Only line charts support negative numbers. |
| axisTick | number | 10 | No | Number of scales displayed on the axis. The value ranges from 1 to 20. The display effect depends on the calculation result of Number of pixels occupied by the image width/(**max** – **min**).<br>In the bar chart, the number of bars in each group of data is the same as the number of scales, and the bars are displayed at the scales.|
| display | boolean | false | No | Whether to display the axis. |
| color | <color> | \#c0c0c0 | No | Axis color. |
**Table 4** ChartSeries
| Name | Type | Default Value | Mandatory | Description |
| margin | <length> | 1 | No | Number of erased points (horizontal distance between the latest drawn point and the earliest point). You are not advised to use **margin** together with **topPoint**, **bottomPoint**, or **headPoint** for mini-, small- and standard-system devices. If you do so, there is a possibility that the point is in the erase area and invisible.|
| gradient | boolean | false | No | Whether to perform gradient erase. |
**Table 8** Point<sup>5+</sup>
| Name | Type | Default Value | Mandatory | Description |
| value | number | 0 | Yes | Y coordinate of the point to draw. |
| pointStyle | PointStyle | - | No | Style of the point. |
| description | string | - | No | Description text of the point. |
| textLocation | string | - | No | Position of the description text relative to the point. Available values are as follows: **top**: above the point<br>**bottom**: below the point<br>**none**: not displayed|
| textColor | <color> | \#000000 | No | Color of the description text. |
| lineDash | string | solid | No | Dashed line pattern. You can set the dash length and space length between the dashes. - **"dashed, 5, 5"**: dashed line with each dash in 5 px and a 5 px space between each two dashes. Default value **"solid"** indicates a solid line.|
| lineColor | <color> | \#000000 | No | Line color. If this attribute is not set, the value of **strokeColor** is used. |
**Table 9** DataSegment<sup>5+</sup>
| Name | Type | Default Value | Mandatory | Description |
| startColor | Color | - | No | Color of the start position. If this attribute is set, **endColor** must be set. If this attribute is not set, the default color array preset in the system is used. For details about the color values, see the next table.|
| endColor | Color | - | No | Color of the end position. If this attribute is set, **startColor** must be set.<br>If this attribute is not set, the default color array preset in the system is used.|
| value | number | 0 | Yes | Percentage for the data segment. The maximum value is **100**. |
| name | string | - | No | Name of the data segment. |
| margin | \<length> | 1 | No | Number of erased points (horizontal distance between the latest drawn point and the earliest point). You are not advised to use **margin** together with **topPoint**, **bottomPoint**, or **headPoint** for lite devices. If you do so, there is a possibility that the point is in the erase area and invisible. |
| gradient | boolean | false | No | Whether to perform gradient erase. |
**Table 8** Point5+
| Name | Type | Default Value | Mandatory | Description |
| value | number | 0 | Yes | Y coordinate of the point to draw. |
| pointStyle | [PointStyle](js-components-basic-chart.md) | - | No | Style of the point. |
| description | string | - | No | Description text of the point. |
| textLocation | string | - | No | Description text position relative to the point. Available values are as follows:**top**: above the point**bottom**: below the point**none**: not displayed |
| textColor | \<color> | #000000 | No | Color of the description text. |
| lineDash | string | solid | No | Dashed line pattern. You can set the dash length and space length between the dashes. For example, **"dashed, 5, 5"** indicates a dashed line with each dash in 5 px and a 5 px space between each two dashes. Default value **"solid"** indicates a solid line. |
| lineColor | \<color> | #000000 | No | Line color. If this attribute is not set, the **strokeColor** is used by default. |
**Table 9** DataSegment5+
| Name | Type | Default Value | Mandatory | Description |
| startColor | Color | - | No | Color of the start position. If this attribute is set, **endColor** must be set. If this attribute is not set, the default color array preset in the system is used. For details about the color values, see the next table. |
| endColor | Color | - | No | Color of the end position. If this attribute is set, **startColor** must be set.If this attribute is not set, the default color array preset in the system is used. |
| value | number | 0 | Yes | Percentage for the current data segment. The maximum value is **100**. |
| name | string | - | No | Name of this data segment. |
| stroke-width | \<length> | 32px (**gauge** charts)24px (**rainbow** charts) | No | Width of the scale bar for **gauge**and **rainbow** charts. |
| start-angle | \<deg> | 240 (**gauge** charts)0 (**rainbow** charts) | No | Start angle of the scale bar for **gauge** and **rainbow** charts, which starts from the direction of zero o'clock. The value ranges from 0 to 360. |
| total-angle | \<deg> | 240 (**gauge** charts)360 (**rainbow** charts) | No | Total length of the scale bar for **gauge** and **rainbow** charts. The value ranges from –360 to 360. A negative number indicates the anticlockwise direction. |
| center-x | \<length> | - | No | Center of the scale bar of the gauge component. This style is supported by the gauge chart only. This style takes precedence over the **position** style in the common styles, and must be used together with **center-y** and **radius**. This style is supported by the gauge chart only. |
| center-y | \<length> | - | No | Center of the scale bar of the gauge component. This style is supported by the gauge chart only. This style takes precedence over the **position** style in the common styles, and must be used together with **center-x** and **radius**. This style is supported by the gauge chart only. |
| radius | \<length> | - | No | Radius of the scale bar of the gauge component. This style is supported by the gauge chart only. This style takes precedence over the **width** and **height** in the common styles, and must be used together with **center-x** and **center-y**. This style is supported by the gauge chart only. |
| colors | Array | - | No | Color of each section for the scale bar of the gauge component.For example, **colors: #ff0000, #00ff00**. This style is supported by the gauge chart only. |
| weights | Array | - | No | Weight of each section for the scale bar of the gauge component.For example, weights: 2, 2. This style is supported by the gauge chart only. |
| font-family5+ | Array | - | No | Font style of the description text. You can use [Custom Font Styles](js-components-common-customizing-font.md). |
| font-size5+ | \<length> | - | No | Font size of the description text. |
| Name | Type | Default Value | Mandatory | Description |
| stroke-width | <length> | 32px (**gauge** charts)<br>24px (**rainbow** charts)| No | Width of the scale bar for **gauge** and **rainbow** charts. |
| start-angle | <deg> | 240 (**gauge** charts)<br>0 (**rainbow** charts) | No | Start angle of the scale bar for **gauge** and **rainbow** charts, which starts from zero o'clock. The value ranges from 0 to 360. |
| total-angle | <deg> | 240 (**gauge** charts)<br>360 (**rainbow** charts) | No | Total length of the scale bar for **gauge** and **rainbow** charts. The value ranges from –360 to 360. A negative number indicates the anticlockwise direction.|
| center-x | <length> | - | No | Center of the scale bar of the gauge component. This style is supported by the gauge chart only. This style takes precedence over the **position** style in the common styles, and must be used together with **center-y** and **radius**. This style is supported by the gauge chart only.|
| center-y | <length> | - | No | Center of the scale bar of the gauge component. This style is supported by the gauge chart only. This style takes precedence over the **position** style in the common styles, and must be used together with **center-x** and **radius**. This style is supported by the gauge chart only.|
| radius | <length> | - | No | Radius of the scale bar of the gauge component. This style is supported by the gauge chart only. This style takes precedence over the **width** and **height** in the common styles, and must be used together with **center-x** and **center-y**. This style is supported by the gauge chart only.|
| colors | Array | - | No | Color of each section for the scale bar of the gauge component.<br>For example, **colors: \#ff0000, \#00ff00**. This style is supported by the gauge chart only.|
| weights | Array | - | No | Weight of each section for the scale bar of the gauge component.<br>For example, **weights: 2, 2**. This style is supported by the gauge chart only.|
| font-family<sup>5+</sup> | Array | - | No | Font style of the description text. You can use a [custom font](../arkui-js/js-components-common-customizing-font.md).|
| font-size<sup>5+</sup> | <length> | - | No | Font size of the description text. |
## Events
Events in [Universal Events](js-components-common-events.md) are supported.
## Events
## Methods
The [universal events](../arkui-js/js-components-common-events.md) are supported.
In addition to the methods in [Universal Methods](js-components-common-methods.md), the following events are supported.
## Methods
In addition to the [universal methods](../arkui-js/js-components-common-methods.md), the following methods are supported.
| append | {serial: number, // Set the data subscript of the line chart to be updated.data: Array\<number>, // Set the new data.} | Data is dynamically added to an existing data sequence. The target sequence is specified based on **serial**, which is the subscript of the datasets array and starts from 0. **datasets[index].data** is not updated. Only line charts support this attribute. The value is incremented by 1 based on the horizontal coordinate and is related to the **xAxis min/max** setting. |
| append | {<br>serial: number, <br>data: Array<number>, <br>} | Data is dynamically added to an existing data sequence. The target sequence is specified based on **serial**, which is the subscript of the datasets array and starts from 0. For example, if the value of **serial** is **index**, use **data** to update **datasets[index].data**. Only line charts support this attribute. The value is incremented by 1 based on the horizontal coordinate and is related to the **xAxis min/max** setting.|
## Example Code
## Example
1. Line chart
```
```html
<!-- xxx.hml -->
<divclass="container">
<stackclass="chart-region">
...
...
@@ -195,7 +176,7 @@ In addition to the methods in [Universal Methods](js-components-common-methods.m
</div>
```
```
```css
/* xxx.css */
.container{
flex-direction:column;
...
...
@@ -221,7 +202,7 @@ In addition to the methods in [Universal Methods](js-components-common-methods.m
}
```
```
```js
// xxx.js
exportdefault{
data:{
...
...
@@ -230,24 +211,24 @@ In addition to the methods in [Universal Methods](js-components-common-methods.m
| src | string | - | No | Image path, which supports local paths. The supported image formats include PNG, JPG, BMP, SVG, and GIF.<br>- The Base64 string<sup>6+</sup> is supported in the following format: data:image/[png \| jpeg \| bmp \| webp];base64, [base64 data], where **[base64 data]** is a Base64 string.<br>- The path prefix of **dataability://** is supported, which allows access to the image path provided by the Data ability.<sup>6+</sup>|
| alt | string | - | No | Alternative information for the image, which is displayed during image loading. |
| Name | Type | Default Value | Mandatory | Description |
| src | string | - | No | Image path, which supports local paths. The supported image formats include PNG, JPG, BMP, SVG, and GIF.Base64 string6+ is supported. The format is data:image/[png \| jpeg \| bmp \| webp];base64, [base64 data],, where [base64 data] is a Base64 string.The path prefix of **dataability://** is supported, which allows access to the image path provided by the Data ability. |
| alt | string | - | No | Placeholder image displayed during image loading. |
## Styles
In addition to the styles in [Universal Styles](js-components-common-styles.md), the following style attributes are supported.
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| object-fit | string | cover | No | Image scale type. This style is not supported for SVG images. For details about available values, see **object-fit**.|
| match-text-direction | boolean | false | No | Whether image orientation changes with the text direction. This style is not supported for SVG images. |
| fit-original-size | boolean | false | No | Whether the **\<image>** component adapts to the image source size when its width and height are not set. If this style is set to **true**, **object-fit** will not take effect. This style is not supported for SVG images.|
| object-position<sup>7+</sup> | string | 0px 0px | No | Position of an image in the component.<br>The options are as follows:<br>1. Pixels. For example, **15px 15px** indicates the moving position along the x-axis or y-axis.<br>2. Characters. Optional values are as follows:<br>- **left**: The image is displayed on the left of the component.<br>- **top** The image is displayed on the top of the component.<br>- **right** The image is displayed on the right of the component.<br>- **bottom** The image is displayed at the bottom of the component.|
| Name | Type | Default Value | Mandatory | Description |
| object-fit | string | cover | No | Image scale type. For details about available values, see [Types of the object-fit style](js-components-basic-image.md). The SVG format is not supported. |
| match-text-direction | boolean | false | No | Whether image orientation changes with the text direction. The SVG format is not supported. |
| fit-original-size | boolean | false | No | Whether the **\<image>** component adapts to the image source size when the width and height are not set. If this attribute is set to **true**, the **object-fit** attribute does not take effect. SVG images do not support this attribute. |
| object-position7+ | string | 0px 0px | No | Position of an image in the component.There are two setting types:1. Pixels. For example, **15px 15px** indicates the moving position along the x-axis or y-axis.2. Characters. Optional values are as follows:<br>-**left**: The image is displayed on the left of the component.<br>-**top** The image is displayed on the top of the component.<br>-**right** The image is displayed on the right of the component.<br>-**bottom** The image is displayed at the bottom of the component. |
| cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries and displayed in the middle.|
| contain | The image is scaled with the aspect ratio retained for the image to be completely displayed within the display boundaries and displayed in the middle. |
| fill | The image is scaled to fill the display area, and its aspect ratio is not retained. |
| none | The image is displayed in the middle with its aspect ratio and size retained. |
| scale-down | The image is displayed in the middle with its aspect ratio retained. The size is equal to or smaller than the original size. |
| cover | The image is scaled with its aspect ratio retained for both sides to be greater than or equal to the display boundaries and displayed in the middle. |
| contain | The image is scaled with the aspect ratio retained for the image to be completely displayed within the display boundaries and displayed in the middle. |
| fill | The image is resized to fill the display area and its aspect ratio is not retained. |
| none | The image is displayed in the middle with its aspect ratio and size retained. |
| scale-down | The image is displayed in the middle with its aspect ratio retained. The size is equal to or smaller than the original size. |
>  **NOTE:** When using an SVG image, note that:
> **NOTE**
>
> - The SVG image will not be drawn if the length or width of the **\<image>** component is infinity.
> - If the image length and width are not specified in the SVG description, the SVG fills the **\<image>** component area.
> - If the image length and width are specified in the SVG description, the following rules are adopted to decide the final display effect:
> When using an SVG image, note that:
>
> 1. If the **\<image>** component is too small to afford the SVG image, the SVG image is cropped and only its upper left part is displayed in the component.
> 2. If the **\<image>** component is big enough to afford the SVG image, this SVG image is displayed in the upper left corner of the component.
## Events
> - The SVG image will not be drawn if the length or width of the **\<image>** component is infinity.
>
> - If the image length and width are not specified in the SVG description, the SVG image fills the **\<image>** component area.
>
> - If the image length and width are specified in the SVG description, the following rules are adopted to decide the final display effect:
>
> 1. If the **\<image>** component is too small to afford the SVG image, the SVG image is cropped and only its upper left part is displayed in the component.
>
> 2. If the **\<image>** component is big enough to afford the SVG image, this SVG image is displayed in the upper left corner of the component.
In addition to the events in [Universal Events](js-components-common-events.md), the following events are supported.
## Events
In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported.
| complete(Rich) | { width: width, height: height } | Triggered when an image is successfully loaded. The loaded image is returned. |
| error(Rich) | { width: width, height: height } | Triggered when an exception occurs during image loading. In this case, the width and height are **0**. |
| complete(Rich) | {<br> width: width,<br> height: height<br> } | Triggered when an image is successfully loaded. The loaded image size is returned.|
| error(Rich) | {<br> width: width,<br> height: height<br> } | Triggered when an exception occurs during image loading. In this case, the width and height are **0**. |
## Methods
Methods in [Universal Methods](js-components-common-methods.md) are supported.
The [universal methods](../arkui-js/js-components-common-methods.md) are supported.
| icon | string | - | No | Search icon. By default, the system search icon is used. The supported icon format is SVG, JPG, and PNG. |
| hint | string | - | No | Hint text. |
| value | string | - | No | Text in the search box. |
| searchbutton5+ | string | - | No | Text on the search button at the end of the search box. |
| menuoptions5+ | Array\<[MenuOption](js-components-basic-search.md)> | - | No | Menu options displayed after users click the **More** button in the pop menu. |
In addition to the [universal attributes](../arkui-js/js-components-common-attributes.md), the following attributes are supported.
**Table 1** MenuOption5+
| Name | Type | Default Value | Mandatory | Description |
| color | <color> | \#e6000000 | No | Font color of the search box. |
| font-size | <length> | 16px | No | Font size of the search box. |
| allow-scale | boolean | true | No | Whether the font size changes with the system's font size settings.<br>If the **config-changes** tag of **fontSize** is configured for abilities in the **config.json** file, the setting takes effect without application restart.|
| placeholder-color | <color> | \#99000000<br>| No | Color of the hint text. |
| font-weight | number \| string | normal | No | Font weight. For details, see **font-weight** of the **[\<text>](../arkui-js/js-components-basic-text.md#styles)** component.|
| font-family | string | sans-serif | No | Font family, in which fonts are separated by commas (,). Each font is set using a font name or font family name. The first font in the family or the specified [custom font](../arkui-js/js-components-common-customizing-font.md) is used for the text.|
| caret-color<sup>6+</sup> | <color> | - | No | Color of the caret. |
| Name | Type | Default Value | Mandatory | Description |
| color | \<color> | #e6000000 | No | Font color of the search box. |
| font-size | \<length> | 16px | No | Font size of the search box. |
| allow-scale | boolean | true | No | Whether the font size changes with the system's font size settings.<br/>NOTE:<br/>If the **config-changes** tag of **fontSize** is configured for abilities in the **config.json** file, the setting takes effect without application restart. |
| placeholder-color | \<color> | #99000000 | No | Color of the hint text. |
| font-weight | number \| string | normal | No | Font weight. For details, see [font-weight](js-components-basic-text.md) of the **text** component. |
| font-family | string | sans-serif | No | Font family, in which fonts are separated by commas (,). Each font is set using a font name or font family name. The first font that exists in the system or the font specified by [Custom Font Styles](js-components-common-customizing-font.md) in the family is selected as the font for the text. |
| caret-color6+ | \<color> | - | No | Color of the input cursor. |
## Events
In addition to the events in [Universal Events](js-components-common-events.md), the following events are supported.
In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported.
| change | { text:newText } | Triggered when the content entered in the text box changes.<br>If you change the **value** attribute directly, this event will not be triggered. |
| submit | { text:submitText } | Triggered when users click the search icon or the search button<sup>5+</sup>, or tap the search button on a soft keyboard. |
| translate<sup>5+</sup> | { value: selectedText } | Triggered when users click the translate button in the menu displayed after they select a text segment. The selected text content is returned.|
| share<sup>5+</sup> | { value: selectedText } | Triggered when users click the share button in the menu displayed after they select a text segment. The selected text content is returned.|
| search<sup>5+</sup> | { value: selectedText } | Triggered when users click the search button in the menu displayed after they select a text segment. The selected text content is returned.|
| optionselect<sup>5+</sup> | { index:optionIndex, value: selectedText } | Triggered when users click a menu option in the menu displayed after they select a text segment. This event is valid only when the **menuoptions** attribute is set. The option index and selected text content are returned.|
| change | { text:newText } | Triggered when the content entered in the text box changes.<br/>NOTE:<br/>If you change the **value** attribute directly, this event will not be triggered. |
| submit | { text:submitText } | Triggered when users click the search icon or the search button5+, or tap the search button on a soft keyboard. |
| translate5+ | { value: selectedText } | Triggered when users click the translate button in the pop menu displayed after they select a text segment. The selected text content is returned. |
| share5+ | { value: selectedText } | Triggered when users click the share button in the pop menu displayed after they select a text segment. The selected text content is returned. |
| search5+ | { value: selectedText } | Triggered when users click the search button in the pop menu displayed after they select a text segment. The selected text content is returned. |
| optionselect5+ | { index:optionIndex, value: selectedText } | Triggered when users click a menu option in the pop menu displayed after they select a text segment. This event is valid only when the **menuoptions** attribute is set. The option index and selected text content are returned. |
## Methods
Methods in [Universal Methods](js-components-common-methods.md) are supported.
The [universal methods](../arkui-js/js-components-common-methods.md) are supported.
| min | number | 0 | No| Minimum value of the slider.|
| max | number | 100 | No| Maximum value of the slider.|
| step | number | 1 | No| Step of each slide.|
| value | number | 0 | No| Initial value of the slider.|
| mode<sup>5+</sup> | string | outset | No| Slider style. Available values are as follows:<br>- **outset**: The slider is on the sliding bar.<br>- **inset**: The slider is inside the sliding bar.|
| min | number | 0 | No | Minimum value of the slider. |
| max | number | 100 | No | Maximum value of the slider. |
| step | number | 1 | No | Step of each slide. |
| value | number | 0 | No | Initial value of the slider. |
| mode5+ | string | outset | No | Slider style. Available values are as follows:<br/>-**outset**: The slider is on the sliding bar.<br/>-**inset**: The slider is inside the sliding bar. |
| showsteps5+ | boolean | false | No | Whether to display slider scales. |
| showtips5+ | boolean | false | No | Whether a pop-up is displayed to show the percentage value on the slider. |
## Styles
In addition to the styles in [Universal Styles](js-components-common-styles.md), the following styles are supported.
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
| change | [ChangeEvent](js-components-basic-slider.md) | Triggered when the value changes. |
| Name| Parameter| Description|
| -------- | -------- | -------- |
| change | ChangeEvent | Triggered when the value changes.|
**Table 1** ChangeEvent
| Attribute| Type| Description|
| -------- | -------- | -------- |
| value<sup>5+</sup> | number | Current value of the slider.|
| mode<sup>5+</sup> | string | Type of the change event. Available values are as follows:<br>- **start**: The **value** starts to change.<br>- **move**: The **value** is changing with users' dragging.<br>- **end**: The **value** stops changing.|
| progress(deprecated5+) | string | Current value of the slider. |
| isEnd(deprecated5+) | string | Whether the dragging operation ends. Available values are as follows:<br/>-**true**: The dragging ends.<br/>-**false**: The dragging is in progress. |
| value5+ | number | Current value of the slider. |
| mode5+ | string | Type of the change event. Available values are as follows:<br/>-**start**: The **value** starts to change.<br/>-**move**: The **value** is changing with users' dragging.<br/>-**end**: The **value** stops changing. |
## Example
```
```html
<!-- xxx.hml -->
<divclass="container">
<text>slider start value is {{startValue}}</text>
<text>slider current value is {{currentValue}}</text>
| color | \<color> | #e5000000 | No | Text color. |
| font-size | \<length> | 30px | No | Font size (px). |
| allow-scale | boolean | true | No | Whether the font size changes with the system's font size settings.<br/>NOTE:<br/>For details about how to make the configuration take effect dynamically, see the **config-changes** attribute in the **config.json** file. |
| letter-spacing | \<length> | 0 px | No | Character spacing (px). |
| word-spacing7+ | \<length> \|\<percentage> \| string | normal | No | Spacing between texts. The options are as follows:**normal**: default spacing. |
| font-style | string | normal | No | Font style. Available values are as follows:<br/>-**normal**: standard font style<br/>-**italic**: italic font style |
| font-weight | number \| string | normal | No | Font width. For the number type, the value ranges from 100 to 900. The default value is 400. A larger value indicates a larger font width.NOTE:The value must be an integer multiple of 100.The value of the string type can be **lighter**, **normal**, **bold**, or **bolder**. |
| text-decoration | string | none | No | Text decoration. Available values are as follows:<br/>-**underline**: An underline is used.<br/>-**line-through**: A strikethrough is used.<br/>-**none**: The standard text is used. |
| text-decoration-color7+ | \<color> | - | No | Color of the text decoration. |
| text-align | string | start | No | Text alignment mode. Available values are as follows:<br/>-**left**: The text is left-aligned.<br/>-**center**: The text is center-aligned.<br/>-**right**: The text is right-aligned.<br/>-**start**: The text is aligned with the direction in which the text is written.<br/>-**end**: The text is aligned with the opposite direction in which the text is written.<br/>NOTE:<br/>If the text width is not specified, the alignment effect may not be obvious when the text width is the same as the width of the parent container. |
| line-height | \<length> \|\<percentage>7+ \| string7+ | 0px1-6normal7+ | No | Text line height. When this parameter is set to **0px**, the text line height is not limited and the font size is adaptive. The **string** values are as follows:**normal**7+: default line height |
| text-overflow | string | clip | No | Takes effect when the maximum number of lines is specified. Available values are as follows:<br/>-**clip**: The text is clipped and displayed based on the size of the parent container.<br/>-**ellipsis**: The text is displayed based on the size of the parent container. The text that cannot be displayed is replaced with ellipsis. This style must be used together with **max-lines**. |
| font-family | string | sans-serif | No | Font family, in which fonts are separated by commas (,). Each font is set using a font name or font family name. The first font that exists in the system or the font specified by [Custom Font Styles](js-components-common-customizing-font.md) in the family is selected as the font for the text. |
| max-lines | number \| string7+ | - | No | Maximum number of text lines. The **string** values are as follows:<br/>-**auto**7+: The number of text lines adapts to the container height. |
| min-font-size | \<length> | - | No | Minimum font size in the text. This style must be used together with **max-font-size**. The font size can be changed dynamically. After the maximum and minimum font sizes are set, **font-size** does not take effect. |
| max-font-size | \<length> | - | No | Maximum font size in the text. This style must be used together with **min-font-size**. The font size can be changed dynamically. After the maximum and minimum font sizes are set, **font-size** does not take effect. |
| font-size-step | \<length> | 1px | No | Step for dynamically adjusting the font size in the text. The minimum and maximum font sizes must be set. |
| prefer-font-sizes | \<array> | - | No | Preset preferred font sizes. For dynamic font size adjustment, the preset sizes are used to match the maximum number of lines in the text. If the preferred font sizes were not set, the font size will be adjusted based on the maximum and minimum font sizes and the step you have set. If the maximum number of lines in the text cannot be met, **text-overflow** is used to truncate the text. If this parameter is set, **font-size**, **max-font-size**, **min-font-size**, and **font-size-step** do not take effect.Example values: **12px,14px,16px** |
| word-break6+ | string | normal | No | Text line breaking mode. The options are as follows:<br/>-**normal**: Allows text line breaks between words as appropriate to the relevant language writing systems. This is the default mode.<br/>-**break-all**: Allows text line breaks between any characters for writing systems other than Chinese, Japanese, and Korean.<br/>-**break-word**: Has the same effect as **break-all**, except that it does not break unbreakable words. |
| text-indent7+ | \<length> | - | No | Indentation of the first line. |
| white-space7+ | string | pre | No | Mode for processing blanks in the component. The options are as follows:<br/>-**normal**: All spaces, carriage returns, and tabs are combined into one space, and the text is automatically wrapped.<br/>-**nowrap**: All spaces, carriage returns, and tabs are combined into one space, and the text is not wrapped.<br/>-**pre**: All contents are output as-is.<br/>-**pre-wrap**: All contents are output as-is with line breaks.<br/>-**pre-line**: All spaces and tabs are combined into one space, the carriage return remains unchanged, and the text is wrapped. |
| adapt-height7+ | boolean | false | No | Whether the text size adapts to the container height.NOTE:The settings take effect after font size auto-adaptation is configured. |
| color | <color> | #e5000000 | No | Font color. |
| font-size | <length> | 30px | No | Font size. |
| allow-scale | boolean | true | No | Whether the font size changes with the system's font size settings.<br>For details about how to make the configuration take effect dynamically, see the **config-changes** attribute in the **config.json** file.|
| letter-spacing | <length> | 0px | No | Character spacing (px). |
| word-spacing<sup>7+</sup> | <length>\|<percentage>\| string | normal | No | Spacing between texts. If the input is a string, the options are as follows:<br>**normal**: default spacing.|
| font-style | string | normal | No | Font style. Available values are as follows:<br>- **normal**: standard font style<br>- **italic**: italic font style|
| font-weight | number \| string | normal | No | Font width. For the number type, the value ranges from 100 to 900. The default value is 400. A larger value indicates a larger font width. The value of the number type must be an integer multiple of 100.<br>The value of the string type can be **lighter**, **normal**, **bold**, or **bolder**.|
| text-decoration | string | none | No | Text decoration. Available values are as follows:<br>- **underline**: An underline is used.<br>- **line-through**: A strikethrough is used.<br>- **none**: The standard text is used.|
| text-decoration-color<sup>7+</sup> | <color> | - | No | Color of the text decoration. |
| text-align | string | start<br> | No | Text alignment mode. Available values are as follows:<br>- **left**: The text is left-aligned.<br>- **center**: The text is center-aligned.<br>- **right**: The text is right-aligned.<br>- **start**: The text is aligned with the direction in which the text is written.<br>- **end**: The text is aligned with the opposite direction in which the text is written.<br>If the text width is not specified, the alignment effect may not be obvious when the text width is the same as the width of the parent container.|
| line-height | <length>\|<percentage><sup>7+</sup>\| string<sup>7+</sup> | 0px<sup>1-6</sup><br>normal<sup>7+</sup> | No | Text line height. When this parameter is set to **0px**, the text line height is not limited and the font size is adaptive. The value of the string type is as follows:<br>**normal**<sup>7+</sup>: default line height |
| text-overflow | string | clip | No | Display mode when the text is too long. This style takes effect when the maximum number of lines is specified. Available values are as follows:<br>- **clip**: The text is clipped and displayed based on the size of the parent container.<br>- **ellipsis**: The text is displayed based on the size of the parent container. The text that cannot be displayed is replaced with ellipsis. This style must be used together with **max-lines**.|
| font-family | string | sans-serif | No | Font family, in which fonts are separated by commas (,). Each font is set using a font name or font family name. The first font in the family or the specified [custom font](../arkui-js/js-components-common-customizing-font.md) is used for the text.|
| max-lines | number \| string<sup>7+</sup> | - | No | Maximum number of text lines. The value of the string type is as follows:<br>- **auto**<sup>7+</sup>: The number of text lines adapts to the container height. |
| min-font-size | <length> | - | No | Minimum font size in the text. This style must be used together with **max-font-size**. The font size can be changed dynamically. After the maximum and minimum font sizes are set, **font-size** does not take effect.|
| max-font-size | <length> | - | No | Maximum font size in the text. This style must be used together with **min-font-size**. The font size can be changed dynamically. After the maximum and minimum font sizes are set, **font-size** does not take effect.|
| font-size-step | <length> | 1px | No | Step for dynamically adjusting the font size in the text. The minimum and maximum font sizes must be set. |
| prefer-font-sizes | <array> | - | No | Preset preferred font sizes. For dynamic font size adjustment, the preset sizes are used to match the maximum number of lines in the text. If the preferred font sizes were not set, the font size will be adjusted based on the maximum and minimum font sizes and the step you have set. If the maximum number of lines in the text cannot be met, **text-overflow** is used to truncate the text. If this parameter is set, **font-size**, **max-font-size**, **min-font-size**, and **font-size-step** do not take effect.<br>Example values: **12px,14px,16px**|
| word-break<sup>6+</sup> | string | normal | No | Text line breaking mode. The options are as follows:<br>- **normal**: Allows text line breaks between words as appropriate to the relevant language writing systems. This is the default mode.<br>- **break-all**: Allows text line breaks between any characters for writing systems other than Chinese, Japanese, and Korean.<br>- **break-word**: Works in the same way as **break-all**, except that it does not break unbreakable words.|
| text-indent<sup>7+</sup> | <length> | - | No | Indentation of the first line. |
| white-space<sup>7+</sup> | string | pre | No | Mode for processing blanks in the component. The options are as follows:<br>- **normal**: All spaces, carriage returns, and tabs are combined into one space, and the text is automatically wrapped.<br>- **nowrap**: All spaces, carriage returns, and tabs are combined into one space, and the text is not wrapped.<br>- **pre**: All contents are output as-is.<br>- **pre-wrap**: All contents are output as-is with line breaks.<br>- **pre-line**: All spaces and tabs are combined into one space, the carriage return remains unchanged, and the text is wrapped.|
| adapt-height<sup>7+</sup> | boolean | false | No | Whether the text size adapts to the container height.<br>The settings take effect after font size auto-adaptation is configured. |
> **NOTE**
> - In dynamic font adjustment, both the preset size set and the minimum/maximum font sizes are used to adjust the font size to display the text within the maximum number of lines. The preset size set is checked from left to right, and the minimum/maximum font sizes are checked from large to small, to find a size meeting the requirement.
>
> - Use the escape character **\r\n** for newline.
>
> - The following escape characters are supported: **\a**, **\b**, **\f**, **\n**, **\r**, **\t**, **\v**, **\'**, **\"**, and **\0**.
>
> - When you use **\<span>** as a child component to form a text paragraph, note that if a **\<span>** style is abnormal, the text paragraph cannot be displayed.
>
> - In dynamic font adjustment, both the preset size set and the minimum/maximum font sizes are used to adjust the font size to display the text within the maximum number of lines. The preset size set is checked from left to right, and the minimum/maximum font sizes are checked from large to small, to find a size meeting the requirement.
> - Use the escape character **\r\n** for newline.
> - The following escape characters are supported: **\a**, **\b**, **\f**, **\n**, **\r**, **\t**, **\v**, **\'**, **\"**, and **\0**.
> - When you use **\<span>** as a child component to form a text paragraph, note that if a **\<span>** style is abnormal, the text paragraph cannot be displayed.
> - The **letter-spacing**, **text-align**, **line-height**, **text-overflow**, and **max-lines** styles take effect on text content held by the **\<text>** component and its child components (**\<span>**).
> - The **\<text>** component does not support the coexistence of the text content and **\<span>** subcomponents. (If both of them exist, only the content in **\<span>** is displayed.)
> - The **letter-spacing**, **text-align**, **line-height**, **text-overflow**, and **max-lines** styles take effect on text content held by the **\<text>** component and its child components (**\<span>**).
>
> - The **\<text>** component cannot contain both the text and the child component **\<span>**. If both of them exist, only the content in **\<span>** is displayed.
## Events
Events in [Universal Events](js-components-common-events.md) are supported.
The [universal events](../arkui-js/js-components-common-events.md) are supported.
## Method
## Methods
Methods in [Universal Methods](js-components-common-methods.md) are supported.
The [universal methods](../arkui-js/js-components-common-methods.md) are supported.
## Example Code
```
## Example
```html
<!-- xxx.hml -->
<divclass="container">
<divclass="content">
...
...
@@ -77,6 +86,9 @@ Methods in [Universal Methods](js-components-common-methods.md) are supported.
</text>
</div>
</div>
```
```css
/* xxx.css */
.container{
display:flex;
...
...
@@ -94,6 +106,9 @@ Methods in [Universal Methods](js-components-common-methods.md) are supported.
The **\<list>** component provides a list container that presents a series of list items arranged in a column with the same width. Lists support presentations of the same data in a multiple and coherent row style, for example, images and texts.
> **NOTE**
>
> This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
The **\<list>** component provides a list container that presents a series of list items arranged in a column with the same width. It supports presentations of the same type of data in a multiple and coherent row style, for example, images or text.
## Required Permissions
N/A
None
## Child Components
\<[list-item](js-components-container-list-item-group.md)> and \<[list-item-group](js-components-container-list-item.md)>
The **[\<list-item-group>](../arkui-js/js-components-container-list-item-group.md)** and **[\<list-item>](../arkui-js/js-components-container-list-item.md)** components are supported.
## Attributes
In addition to the attributes in [Universal Attributes](js-components-common-attributes.md), the following attributes are supported.
## Attributes
In addition to the [universal attributes](../arkui-js/js-components-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| scrollpage | boolean | false | No | Whether to scroll the non-list part on the top of the list page out of the visible area with the list. The value can be **true** (scrolls the non-list part out) or **false** (does not scroll the non-list part out). This attribute is not available when the direction is **row**.|
| cachedcount | number | 0 | No | Minimum number of cached list items when a long list is loaded with delay.<br>When the number of list items cached outside the visible area is less than the value of this attribute, a **requestitem** event is triggered.|
| scrollbar | string | off | No | Display mode of the side scrollbar. (Currently, only the vertical scrollbar is supported.)<br>- **off**: no display.<br>- **auto**: displayed on demand (The side scrollbar is displayed when touched and disappears 2s later.).<br>- **on**: always displayed.|
| scrolleffect | string | spring | No | Scroll effect. Available values are as follows:<br>- **spring**: Similar to the physical dynamic effect of a spring. After scrolling to the edge, you can continue to scroll for a distance based on the initial speed or by touching the knob of the scrollbar. After you release your hand, the knob is rebounded.<br>- **fade**: Similar to the physical dynamic effect of fade. When you scroll to the edge, a wave shape fades. The fade changes according to the speed and scrolling distance.<br>- **no**: No effect after the scrollbar is moved to the edge.|
| indexer | boolean \| Array<string> | false | No | Whether to display the alphabetical index bar on the sidebar. If this attribute is set to **true** or a customized indexer, the index bar is displayed at the right boundary of the list. Example:<br>**"indexer" : "true"** indicates the default alphabetical indexer.<br>**"indexer" : "false"** indicates no indexer.<br>"indexer": ['#', '1', '2', '3', '4', '5', '6', '7', '8'] indicates a customized index. You must include **"#"** when using a customized indexer.<br>This **indexer** attribute is valid only when **flex-direction** is set to **column** and **columns** is set to **1**.<br>This attribute must be used together with the **[section](../arkui-js/js-components-container-list-item.md#attributes)** attribute of **\<list-item>**.|
| indexercircle<sup>5+</sup> | boolean | - | No | Whether to use a circle indexer.<br>The default value is **true** for wearables and **false** for other device types. This attribute is invalid if **indexer** is set to **false**.|
| indexermulti<sup>5+</sup> | boolean | false | No | Whether to use a multi-language indexer.<br>This attribute is invalid if **indexer** is set to **false**. |
| indexerbubble<sup>5+</sup> | boolean | true | No | Whether to display the bubble effect when switching among indexes.<br>This attribute is invalid if **indexer** is set to **false**. |
| divider<sup>5+</sup> | boolean | false | No | Whether list items are separated by dividers.<br>For details about divider styles, see **divider-color**, **divider-height**, **divider-length**, and **divider-origin** in the **Styles** table.|
| shapemode | string | default | No | Shape of the side scrollbar.<br>- **default**: not specified (following the theme).<br>- **rect**: rectangle.<br>- **round**: circle.|
| updateeffect | boolean | false | No | Whether a dynamic effect is displayed when an item in the list is deleted or added.<br>- **false**: No dynamic effect is displayed.<br>- **true**: A dynamic effect is displayed when an item is added or deleted.|
| chainanimation<sup>5+</sup> | boolean | false | No | Whether to display chained animations on this list when it slides or its top and bottom are dragged. The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics.<br>- **false**: Chained animations are displayed.<br>- **true**: No chained animation is displayed.<br>Type of the **Enter** key on the soft keyboard. The value cannot be dynamically updated.<br>This attribute does not take effect if an indexer is used.<br>If this attribute is **true**, the **sticky** attributes set for **\<list-item>** components do not take effect.|
| initialindex | number | 0 | No | Item displayed at the start position of the viewport when the current list is loaded for the first time. The default value is **0**, indicating that the first item is displayed. If the number you set is greater than the index of the last item, the setting does not take effect. When the **initialoffset** attribute is set, this attribute does not take effect. This attribute does not take effect if **indexer** or **scrollpage** is set to **true**.|
| initialoffset | <length> | 0 | No | Start offset of the viewport when the current list is loaded for the first time. The offset must not exceed the scrolling range of the current list. If exceeded, the offset is truncated to the maximum value of the scrolling range. This attribute does not take effect if **indexer** or **scrollpage** is set to **true**.|
| selected<sup>5+</sup> | string | - | No | Selected item in the current list. The value can be a **section** value of any list items.|
| Name | Type | Default Value | Mandatory | Description |
| scrollpage | boolean | false | No | Whether to scroll the non-list part on the top of the list page out of the visible area with the list. The value can be **true** (scrolls the non-list part out) or **false** (does not scroll the non-list part out). This attribute is not available when the direction is **row**. |
| cachedcount | number | 0 | No | Minimum number of cached list items when the long list is loaded with delay.When the number of list items cached outside the visible area is less than the value of this attribute, a **requestitem** event is triggered. |
| scrollbar | string | off | No | Display mode of the side scrollbar. (Currently, only the vertical scrollbar is supported.) <br>- **off**: No display <br>- **auto**: Displayed on demand (The side scrollbar is displayed when touched and disappears 2s later.) <br>- **on**: Always displayed |
| scrolleffect | string | spring | No | Scroll effect. Available values are as follows: <br>- **spring**: Similar to the physical dynamic effect of a spring. After scrolling to the edge, you can continue to scroll for a distance based on the initial speed or by touching the knob of the scrollbar. After you release your hand, the knob is rebounded. <br>- **fade**: Similar to the physical dynamic effect of fade. When you scroll to the edge, a wave shape fades. The fade changes according to the speed and scrolling distance. <br>- **no**: No effect after the scrollbar is moved to the edge. |
| indexer | boolean \| Array\<string> | false | No | Whether to display the alphabetical index bar on the sidebar. If this attribute is set to **true** or a customized indexer, the index bar is displayed at the right boundary of the list. Example:<br>**"indexer" : "true"** indicates the default alphabetical indexer.<br>**"indexer" : "false"** indicates no indexer.<br>"indexer": ['#', '1', '2', '3', '4', '5', '6', '7', '8'] indicates a customized index. You must include **"#"** when using a customized indexer.<br>NOTE:<br>- This attribute is valid only when **flex-direction** is set to **column** and **columns** is set to **1**.<br>- This attribute must be used together with the [section](js-components-container-list-item.md#section2907183951110) attribute of **\<list-item>**. |
| indexercircle<sup>5+</sup> | boolean | - | No | Whether to use a circle indexer.<br>The default value is **true** for wearables and **false** for other device types. This attribute is invalid if **indexer** is set to **false**. |
| indexermulti<sup>5+</sup> | boolean | false | No | Whether to use a multi-language indexer.<br>This attribute is invalid if **indexer** is set to **false**. |
| indexerbubble<sup>5+</sup> | boolean | true | No | Whether to display the bubble effect when switching among indexes.<br>This attribute is invalid if **indexer** is set to **false**. |
| divider<sup>5+</sup> | boolean | false | No | Whether list items are separated by dividers.<br>For details about divider styles, see **divider-color**, **divider-height**, **divider-length**, and **divider-origin** in the [Styles](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.1-Release/en/application-dev/nottoctopics/en-us_topic_0000001131154746.md#section1071433432218) table. |
| shapemode | string | default | No | Shape of the side scrollbar. <br>- **default**: not specified (following the theme) <br>- **rect**: rectangle <br>- **round**: circle |
| updateeffect | boolean | false | No | Whether a dynamic effect is displayed when an item in the list is deleted or added. <br>- **false**: No dynamic effect is displayed. <br>- **true**: A dynamic effect is displayed when an item is added or deleted. |
| chainanimation<sup>5+</sup> | boolean | false | No | Whether to display chained animations on this list when it slides or its top and bottom are dragged. The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics. <br>- **false**: Chained animations are displayed. <br>- **true**: No chained animation is displayed.<br>NOTE:<br> - Dynamic modification is not supported.<br> - This attribute does not take effect if an indexer is used.<br> - If this attribute is **true**, the **sticky** attributes set for **\<list-item>** components do not take effect. |
| initialindex | number | 0 | No | Item to be displayed at the start position of the viewport when the current list is loaded for the first time. The default value is **0**, indicating that the first item is displayed.<br> The setting does not take effect in any of the following cases:<br>- The value you set is greater than the index of the last item.<br>- The **initialoffset** attribute is set. <br>- **indexer** or **scrollpage** is set to **true**. |
| initialoffset | \<length> | 0 | No | Start offset of the viewport when the current list is loaded for the first time. The offset must not exceed the scrolling range of the current list. If exceeded, the offset is truncated to the maximum value of the scrolling range. This attribute does not take effect if **indexer** or **scrollpage** is set to **true**. |
| selected<sup>5+</sup> | string | - | No | Selected item in the current list. The value can be a **section** value of any list items. |
## Styles
In addition to the styles in [Universal Styles](js-components-common-styles.md), the following styles are supported.
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| divider-color<sup>5+</sup> | <color> | transparent | No | Item divider color. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-height<sup>5+</sup> | <length> | 1 | No | Item divider height. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-length<sup>5+</sup> | <length> | Main axis width | No | Item divider length. If this style is not set, the maximum length is the width of the main axis, and the actual length depends on the **divider-origin** parameter. This style is valid only when the **divider** attribute of **\<list>** is set to **true**.|
| divider-origin<sup>5+</sup> | <length> | 0 | No | Item divider offset relative to the start point of the main axis. This style is valid only when the **divider** attribute of **\<list>** is set to **true**.|
| flex-direction | string | column | No | Main axis direction of the flex container. It specifies how items are placed in the flex container.<br>- **column**: The y-axis is the main axis.<br>- **row**: The x-axis is the main axis.<br>For the **\<list>** component, the default value is **column**. For other components, the default value is **row**.|
| columns | number | 1 | No | Number of columns displayed in the cross axis direction of the list. The default value is **1**.<br>When multiple columns are set, the columns are evenly distributed on the cross axis of the **\<list>** component. The size of each column is the same.|
| align-items | string | stretch | No | Alignment of items in each column on the cross axis. Available values are as follows:<br>- **stretch**: Items are stretched to the same height or width as the container in the cross axis direction.<br>- **flex-start**: Items are aligned to the start of the cross axis.<br>- **flex-end**: Items are aligned to the end of the cross axis.<br>- **center**: Items are aligned in the center of the cross axis.<br>This style takes effect only on items of each column. Columns are evenly distributed.|
| item-extent | <length>\|<percentage> | - | No | Size of an internal item. When a percentage is set, the value indicates the percentage of the length in the main axis direction relative to the list viewpoint.|
| fade-color | <color> | grey | No | Color of the physical dynamic effect. This attribute is valid only when **scrolleffect** is set to **fade**. |
| scrollbar-color<sup>6+</sup> | <color> | - | No | Color of the scrollbar. |
| scrollbar-width<sup>6+</sup> | <length> | - | No | Width of the scrollbar. |
| scrollbar-offset<sup>6+</sup> | <length> | 0 | No | Offset between the scrollbar and the default position of the list. The value must be a positive number. The default position is on the right edge of the list. You can adjust the horizontal position of the scrollbar by setting this offset. If the scrollbar is drawn outside the list and the parent component of the list is capable of cropping, the scrollbar will be cropped.|
| Name | Type | Default Value | Mandatory | Description |
| divider-color<sup>5+</sup> | \<color> | transparent | No | Item divider color. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-height<sup>5+</sup> | \<length> | 1 | No | Item divider height. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-length<sup>5+</sup> | \<length> | The main axis width | No | Item divider length. If this style is not set, the maximum length is the width of the main axis, and the actual length depends on the **divider-origin** parameter. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-origin<sup>5+</sup> | \<length> | 0 | No | Item divider offset relative to the start point of the main axis. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| flex-direction | string | column | No | Main axis direction of the flex container. It specifies how items are placed in the flex container.<br>- **column**: The y-axis is the maim axis.<br>- **row**: The x-axis is the main axis.<br>For the **\<list>** component, the default value is **column**. For other components, the default value is **row**. |
| columns | number | 1 | No | Number of columns displayed in the cross axis direction of the list. The default value is **1**.<br>NOTE:<br>When multiple columns are set, the columns are evenly distributed on the cross axis of the **\<list>** component. The size of each column is the same. |
| align-items | string | stretch | No | Alignment of items in each column on the cross axis. Available values are as follows: <br>- **stretch**: Items are stretched to the same height or width as the container in the cross axis direction. <br>- **flex-start**: Items are aligned to the start of the cross axis. <br>- **flex-end**: Items are aligned to the end of the cross axis. <br>- **center**: Items are aligned in the middle of the cross axis.NOTE:This style takes effect only on items of each column. Columns are evenly distributed. |
| item-extent | \<length> \|\<percentage> | - | No | Size of an internal item. When a percentage is set, the value indicates the percentage of the length in the main axis direction relative to the list viewpoint. |
| fade-color | \<color> | grey | No | Color of the physical dynamic effect. This attribute is valid only when **scrolleffect** is set to **fade**. |
| scrollbar-color<sup>6+</sup> | \<color> | - | No | Color of the scrollbar. |
| scrollbar-width<sup>6+</sup> | \<length> | - | No | Width of the scrollbar. |
| scrollbar-offset<sup>6+</sup> | \<length> | 0 | No | Offset between the scrollbar and the default position of the list. The value must be a positive number. The default position is on the right edge of the list. You can adjust the horizontal position of the scrollbar by setting this offset. If the scrollbar is drawn outside the list and the parent component of the list is capable of cropping, the scrollbar will be cropped. |
## Events
In addition to the events in [Universal Events](js-components-common-events.md), the following events are supported.
In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported.
| indexerchange<sup>5+</sup> | { local: booleanValue } | Triggered when the indexer switches between local and alphabetic indexers. This parameter takes effect only when both **indexer** and **indexermulti** are set to **true**. The values of **booleanValue** can be:<br>- **true**: The local index is displayed.<br>- **false**: The alphabetic index is displayed.|
| scroll | { scrollX: scrollXValue, scrollY: scrollYValue, scrollState: stateValue } | Triggered to indicate the offset and status of list scrolling.<br>**stateValue: 0**: The list is not scrolling.<br>**stateValue: 1**: The list is scrolling along with user's touches.<br>**stateValue: 2**: The list is scrolling after the touches stop.|
| scrollbottom | - | Triggered when the list is scrolled to the bottom. |
| scrolltop | - | Triggered when the list is scrolled to the top. |
| scrollend | - | Triggered when the list stops scrolling. |
| scrolltouchup | - | Triggered when the list continues scrolling after the user lifts their fingers. |
| requestitem | - | Triggered for a request to create a list-item.<br>This event is triggered when the number of cached list-items outside the visible area is less than the value of **cachedcount** during long list loading with delay.|
| rotate<sup>7+</sup> | { rotateValue: number } | Triggered to indicate the incremental value of the rotation angle of the watch crown. This parameter is only supported by wearables. |
| indexerchange<sup>5+</sup> | { local: booleanValue } | Triggered when the indexer switches between local and alphabetic indexers. This parameter takes effect only when both **indexer** and **indexermulti** are set to **true**. The value of **booleanValue** can be: <br>- **true**: The local index is displayed. <br>- **false**: The alphabetic index is displayed. |
| scroll | { scrollX: scrollXValue, scrollY: scrollYValue, scrollState: stateValue } | Triggered to indicate the offset and status of list scrolling. <br>- **stateValue: 0**: The list is not scrolling.<br>- **stateValue: 1**: The list is scrolling along with user's touches. <br>- **stateValue: 2**: The list is scrolling after the touches stop. |
| scrollbottom | - | Triggered when the list is scrolled to the bottom. |
| scrolltop | - | Triggered when the list is scrolled to the top. |
| scrollend | - | Triggered when the list stops scrolling. |
| scrolltouchup | - | Triggered when the list continues scrolling after the user lifts their fingers. |
| requestitem | - | Triggered for a request to create a list-item.This event is triggered when the number of cached list-items outside the visible area is less than the value of **cachedcount** during long list loading with delay. |
| rotate<sup>7+</sup> | { rotateValue: number } | Triggered to indicate the incremental value of the rotation angle of the watch crown. This parameter is only supported by wearables. |
## Methods
In addition to the methods in [Universal Methods](js-components-common-methods.md), the following events are supported.
| scrollTo | { index: number(specified position) } | Scrolls the list to the position of the item at the specified index. |
| scrollBy | [ScrollParam](js-components-container-list.md#t54327f53ea104788bc430b9047ecb47b) | Scrolls the list for a certain distance.<br>This method applies only to smart TVs. |
| scrollTop | { smooth: boolean } | If **smooth** is set to **false** (default value), the list is directly scrolled to the top.<br>If **smooth** is set to **true**, the list is smoothly scrolled to the top. |
| scrollBottom | { smooth: boolean } | If **smooth** is set to **false** (default value), the list is directly scrolled to the bottom.<br/>If **smooth** is set to **true**, the list is smoothly scrolled to the bottom. |
| scrollPage | { reverse: boolean, smooth: boolean } | If **reverse** is set to **false** (default value), the next page is displayed.If there is no next page, the list scrolls to the bottom.<br/>If **reverse** is set to **true**, the previous page is displayed. If there is no previous page, the list scrolls to the top.<br/>If **smooth** is set to **false** (default value), the list is directly scrolled to another page.<br/>If **smooth** is set to **true**, the list is smoothly scrolled to another page. |
| scrollArrow | { reverse: boolean, smooth: boolean } | If **reverse** is set to **false** (default value), the list scrolls towards the bottom for a certain distance. If there is no sufficient distance, the list scrolls to the bottom.<br/>If **reverse** is set to **true**, the list scrolls towards the top for a certain distance. If there is no sufficient distance, the list scrolls to the top.<br/>If **smooth** is set to **false** (default value), the list is directly scrolled.<br/>If **smooth** is set to **true**, the list is smoothly scrolled. |
| collapseGroup | { groupid: string } | Collapses a group.<br/>**groupid**: ID of the group to collapse.<br/>All groups are collapsed when **groupid** is not specified. |
| expandGroup | { groupid: string } | Expands a group.<br/>**groupid**: ID of the group to expand.<br/>All groups are expanded when **groupid** is not specified. |
| currentOffset | - | Returns the offset of the current scrolling. The return value type is **Object**. For details, see [Table 2](js-components-container-list.md). |
**Table 1** ScrollParam
| Name | Type | Mandatory | Default Value | Remarks |
| scrollTo | { index: number(specified position) } | Scrolls the list to the position of the item at the specified index. |
| scrollTop | { smooth: boolean } | If **smooth** is set to **false** (default value), the list is directly scrolled to the top.<br>If **smooth** is set to **true**, the list is smoothly scrolled to the top.|
| scrollBottom | { smooth: boolean } | If **smooth** is set to **false** (default value), the list is directly scrolled to the bottom.<br>If **smooth** is set to **true**, the list is smoothly scrolled to the bottom.|
| scrollPage | { reverse: boolean, smooth: boolean } | If **reverse** is set to **false** (default value), the next page is displayed. If there is no next page, the list scrolls to the bottom.<br>If **reverse** is set to **true**, the previous page is displayed. If there is no previous page, the list scrolls to the top.<br>If **smooth** is set to **false** (default value), the list is directly scrolled to another page.<br>If **smooth** is set to **true**, the list is smoothly scrolled to another page.|
| scrollArrow | { reverse: boolean, smooth: boolean } | If **reverse** is set to **false** (default value), the list scrolls towards the bottom for a certain distance. If there is no sufficient distance, the list scrolls to the bottom.<br>If **reverse** is set to **true**, the list scrolls towards the top for a certain distance. If there is no sufficient distance, the list scrolls to the top.<br>If **smooth** is set to **false** (default value), the list is directly scrolled.<br>If **smooth** is set to **true**, the list is smoothly scrolled.|
| collapseGroup | { groupid: string } | Collapses a group.<br>**groupid**: ID of the group to collapse.<br>All groups are collapsed when **groupid** is not specified.|
| expandGroup | { groupid: string } | Expands a group.<br>**groupid**: ID of the group to expand.<br>All groups are expanded when **groupid** is not specified.|
| currentOffset | - | Returns the offset of the current scrolling. The return value type is Object. For details, see **currentOffset**.|
**Table 1** currentOffset
| Name | Type | Remarks |
| ---- | ------ | ---------------- |
| x | number | Scrolling offset in the x-axis, in px|
| y | number | Scrolling offset in the y-axis, in px|
The **\<panel>** component is a slidable panel. It provides a lightweight content display window with flexible sizes. The **\<panel>** component pops up when it is displayed.
> **NOTE**
>
> This component is supported since API version 5. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
The **\<panel>** component is a slidable, pop-up component that provides a lightweight content display window with flexible sizes.
Yes
## Attributes
## Child Components
Supported
In addition to the attributes in [Universal Attributes](js-components-common-attributes.md), the following attributes are supported.
## Attributes
In addition to the [universal attributes](../arkui-js/js-components-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Triggered when |
| type | string | foldable | Yes | Type of the slidable panel. This attribute cannot be dynamically changed. Available values are as follows: <br>- **minibar**: A minibar panel displays content in the minibar area or a large (fullscreen-like) area. <br>- **foldable**: A foldable panel displays permanent content in a large (fullscreen-like), medium-sized (halfscreen-like), or small area. <br>- **temporary**: A temporary panel displays content in a large (fullscreen-like) or medium-sized (halfscreen-like) area. |
| mode | string | full | No | Initial status of the slidable panel. Available values are as follows: <br>- **mini**: Displays a **minibar** or **foldable** panel in its minimum size. This attribute does not take effect for **temporary** panels. <br>- **half**: Displays a **foldable** or **temporary** panel in a medium-sized (halfscreen-like) area. This attribute does not take effect for **minibar** panels. <br>- **full**: Displays a panel in a large (fullscreen-like) area. |
| dragbar | boolean | true | No | Whether to enable a drag bar. The value **true** indicates that the drag bar will be displayed, and **false** indicates the opposite. |
| fullheight | \<length> | - | No | Panel height in the **full** mode. The default value is the screen height minus 8 px. |
| halfheight | \<length> | - | No | Panel height in the **half** mode. The default value is half of the screen height. |
| miniheight | \<length> | - | No | Panel height in the **mini** mode. The default value is **48px**. |
| Name | Type | Default Value | Mandatory | Description |
| type | string | foldable | Yes | Type of the slidable panel. This attribute cannot be dynamically changed. Available values are as follows:<br>- **minibar**: A minibar panel displays content in the minibar area or a large (fullscreen-like) area.<br>- **foldable**: A foldable panel displays permanent content in a large (fullscreen-like), medium-sized (halfscreen-like), or small area.<br>- **temporary**: A temporary panel displays content in a large (fullscreen-like) or medium-sized (halfscreen-like) area.|
| mode | string | full | No | Initial status of the slidable panel. Available values are as follows:<br>1. **mini**: Displays a **minibar** or **foldable** panel in its minimum size. This attribute does not take effect for **temporary** panels.<br>2. **half**: Displays a **foldable** or **temporary** panel in a medium-sized (halfscreen-like) area. This attribute does not take effect for **minibar** panels.<br>3. **full**: Displays a panel in a large (fullscreen-like) area.|
| dragbar | boolean | true | No | Whether to enable a drag bar. The value **true** means that the drag bar will be displayed, and **false** means the opposite. |
| fullheight | <length> | - | No | Panel height in the **full** mode. The default value is the screen height minus 8 px. |
| halfheight | <length> | - | No | Panel height in the **half** mode. The default value is half of the screen height. |
| miniheight | <length> | - | No | Panel height in the **mini** mode. The default value is **48px**. |
| padding | \<length> | 0 | No | The attribute can have one to four values:<br>- If you set only one value, it specifies the padding for four sides.<br>- If you set two values, the first value specifies the top and bottom padding, and the second value specifies the left and right padding.<br>- If you set three values, the first value specifies the top padding, the second value specifies the left and right padding, and the third value specifies the bottom padding.<br>- If you set four values, they respectively specify the padding for top, right, bottom, and left sides (in clockwise order). |
| padding-[left\|top\|right\|bottom] | \<length> | 0 | No | Left, top, right, and bottom padding. |
| padding-[start\|end] | \<length> | 0 | No | Start and end padding. |
| margin | \<length> | 0 | No | Shorthand attribute to set margins for all sides in a declaration. The attribute can have one to four values:<br>- If you set only one value, it specifies the margin for all the four sides.<br>- If you set two values, the first value is for the top and bottom sides and the second value for the left and right sides.<br>- If you set three values, the first value is for the top, the second value for the left and right, and the third value for the bottom.<br>- If you set four values, they are margins for top, right, bottom, and left sides, respectively. |
| margin-[left\|top\|right\|bottom] | \<length> | 0 | No | Left, top, right, and bottom margins. |
| margin-[start\|end] | \<length> | 0 | No | Start and end margins. |
| border | - | 0 | No | Shorthand attribute to set all borders. Set **border-width**, **border-style**, and **border-color** in sequence. Default values are used for attributes that are not set. |
| border-style | string | solid | No | Shorthand attribute to set the style for all borders. Available values are as follows: <br>- **dotted**: dotted border. The radius of a dot is half of **border-width**. <br>- **dashed**: dashed border <br>- **solid**: solid border |
| border-[left\|top\|right\|bottom]-style | string | solid | No | Styles of the left, top, right, and bottom borders. The available values are **dotted**, **dashed**, and **solid**. |
| border-[left\|top\|right\|bottom] | - | - | No | Shorthand attribute to set the borders for every side respectively. You set **border-width**, **border-style**, and **border-color** in sequence. Default values are used for attributes that are not set. |
| border-width | \<length> | 0 | No | Shorthand attribute to set the width of all borders, or separately set the width of each border. |
| border-[left\|top\|right\|bottom]-width | \<length> | 0 | No | Attribute to set widths of left, top, right, and bottom borders. |
| border-color | \<color> | black | No | Shorthand attribute to set the color of all borders, or separately set the color of each border. |
| border-[left\|top\|right\|bottom]-color | \<color> | black | No | Attribute to set colors of left, top, right, and bottom borders. |
| border-radius | \<length> | - | No | Attribute to set the radius of round-corner borders. This attribute cannot be used to set the width or color of a specific border. To set the width or color, you need to set **border-width** or **border-color** for all the borders at the same time. |
| border-[top\|bottom]-[left\|right]-radius | \<length> | - | No | Attribute to receptively set the radii of upper-left, upper-right, lower-right, and lower-left rounded corners |
| background | \<linear-gradient> | - | No | This attribute supports [Gradient Styles](js-components-common-gradient.md) only but is not compatible with **background-color** or **background-image**. |
| background-image | string | - | No | Background image. Currently, this attribute is not compatible with **background-color** or **background**. Local image resources are supported. |
| background-size | - string<br>- \<length> \<length><br>- \<percentage> \<percentage> | auto | No | Background image size.<br>- The **string** values are as follows: <br> - **contain**: Expands the image to the maximum size so that the height and width of the image are applicable to the content area. <br> - **cover**: Extends the background image to a large enough size so that the background image completely covers the background area. Some parts of the image may not be displayed in the background area. <br> - **auto**: The original image width-height ratio is retained.<br>- The two **\<length>** values are as follows:Width and height of the background image. The first value indicates the width, and the second value indicates the height. If you only set one value, the other value is set to **auto** by default.<br>- The two **\<percentage>** values are as follows:Width and height of the background image in percentage of the parent element. The first value indicates the width, and the second value indicates the height. If you only set one value, the other value is set to **auto** by default. |
| background-repeat | string | repeat | No | Repeating attribute of a background image. By default, a background image is repeated both horizontally and vertically. <br>- **repeat**: Repeatedly draws images along the x-axis and y-axis at the same time. <br>- **repeat-x**: Repeatedly draws images along the x-axis. <br>- **repeat-y**: Repeatedly draws images along the y-axis. <br>- **no-repeat**: The image is not drawn repeatedly. |
| background-position | - string string<br/>- \<length> \<length><br/>- \<percentage> \<percentage> | 0px 0px | No | - Using keywords: If only one keyword is specified, the other value is **center** by default. The two values define the horizontal position and vertical position, respectively.<br> - **left**: leftmost in the horizontal direction<br> - **right**: rightmost in the horizontal direction<br> - **top**: top in the vertical direction<br> - **bottom**: bottom in the vertical direction<br> - **center**: center position<br>- Using **\<length>**: The first value indicates the horizontal position, and the second value indicates the vertical position. **0 0** indicates the upper left corner. The unit is pixel. If only one value is specified, the other one is **50%**.<br>- Using **\<percentage>**: The first value indicates the horizontal position, and the second value indicates the vertical position. **0% 0%** indicates the upper left corner. **100% 100%** indicates the lower right corner. If only one value is specified, the other one is **50%**.<br>- Using both **\<percentage>** and **\<length>**. |
| opacity | number | 1 | No | Opacity of an element. The value ranges from **0** to **1**. The value **1** means opaque, and **0** means completely transparent. |
Only the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| padding | <length> | 0 | No | The attribute can have one to four values:<br>- If you set only one value, it specifies the padding for all the four sides.<br>- If you set two values, the first value specifies the top and bottom padding, and the second value specifies the left and right padding.<br>- If you set three values, the first value specifies the top padding, the second value specifies the left and right padding, and the third value specifies the bottom padding.<br>- If you set four values, they respectively specify the padding for top, right, bottom, and left sides (in clockwise order).|
| padding-[left\|top\|right\|bottom] | <length> | 0 | No | Left, top, right, and bottom padding. |
| padding-[start\|end] | <length> | 0 | No | Start and end padding. |
| margin | <length> | 0 | No | Shorthand attribute to set the margin for all sides in a declaration. The attribute can have one to four values:<br>- If you set only one value, it specifies the margin for all the four sides.<br>- If you set two values, the first value specifies the top and bottom margins, and the second value specifies the left and right margins.<br>- If you set three values, the first value specifies the top margin, the second value specifies the left and right margins, and the third value specifies the bottom margin.<br>- If you set four values, they respectively specify the margin for top, right, bottom, and left sides (in clockwise order).|
| margin-[left\|top\|right\|bottom] | <length> | 0 | No | Left, top, right, and bottom margins. |
| margin-[start\|end] | <length> | 0 | No | Start and end margins. |
| border | - | 0 | No | Shorthand attribute to set all borders. Set **border-width**, **border-style**, and **border-color** in sequence. Default values are used for attributes that are not set.|
| border-style | string | solid | No | Shorthand attribute to set the style for all borders. Available values are as follows:<br>- **dotted**: dotted border. The radius of a dot is half of **border-width**.<br>- **dashed**: dashed border.<br>- **solid**: solid border.|
| border-[left\|top\|right\|bottom]-style | string | solid | No | Styles of the left, top, right, and bottom borders. The available values are **dotted**, **dashed**, and **solid**.|
| border-[left\|top\|right\|bottom] | - | - | No | Shorthand attribute to set the borders for every side respectively. Set **border-width**, **border-style**, and **border-color** in sequence. Default values are used for attributes that are not set.|
| border-width | <length> | 0 | No | Shorthand attribute to set the width for all borders, or separately set the width for each border. |
| border-[left\|top\|right\|bottom]-width | <length> | 0 | No | Attribute to set widths of left, top, right, and bottom borders. |
| border-color | <color> | black | No | Shorthand attribute to set the color for all borders, or separately set the color for each border. |
| border-[left\|top\|right\|bottom]-color | <color> | black | No | Attribute to set colors for left, top, right, and bottom borders. |
| border-radius | <length> | - | No | Attribute to set the radius of round-corner borders. This attribute cannot be used to set the width or color of a specific border. To set the width or color, you must set **border-width** or **border-color** for all the borders at the same time. |
| border-[top\|bottom]-[left\|right]-radius | <length> | - | No | Attribute to respectively set the radii of upper-left, upper-right, lower-right, and lower-left rounded corners |
| background | <linear-gradient> | - | No | Background. This attribute supports [gradient styles](../arkui-js/js-components-common-gradient.md) only and is not compatible with **background-color** or **background-image**.|
| background-image | string | - | No | Background image. This attribute is not compatible with **background-color** or **background**. Local image resources are supported. |
| background-size | - string<br>- <length><length><br>- <percentage><percentage> | auto | No | Background image size.<br>- The **string** values are as follows:<br> - **contain**: Expands the image to the maximum size so that its height and width are fully applicable to the content area.<br> - **cover**: Extends the background image to a large enough size so that it completely covers the background area. Some parts of the image may not be displayed in the background area.<br> - **auto**: Retains the original aspect ratio of the image.<br>- The two **length** values are width and height of the background image. The first value indicates the width, and the second value indicates the height. If you only set one value, the other value is set to **auto** by default.<br>- The two **percentage** values are width and height of the background image in percentage of the parent element. The first value indicates the width, and the second value indicates the height. If you only set one value, the other value is set to **auto** by default. |
| background-repeat | string | repeat | No | Repeating attribute of a background image. By default, a background image is repeated both horizontally and vertically.<br>- **repeat**: The image is repeated along the x-axis and y-axis at the same time.<br>- **repeat-x**: The image is repeated along the x-axis.<br>- **repeat-y**: The image is repeated along the y-axis.<br>- **no-repeat**: The image is not repeated.|
| background-position | - string string<br>- <length><length><br>- <percentage><percentage> | 0px 0px | No | - Using keywords: If only one keyword is specified, the other value is **center** by default. The two values define the horizontal position and vertical position, respectively.<br> - **left**: leftmost in the horizontal direction.<br> - **right**: rightmost in the horizontal direction.<br> - **top**: top in the vertical direction.<br> - **bottom**: bottom in the vertical direction.<br> - **center**: center position.<br>- Using **length** values: The first value indicates the horizontal position, and the second value indicates the vertical position. For the upper left corner, the value is **0 0**. The unit is pixel. If only one value is specified, the other one is **50%**.<br>- Using **percentage** values: The first value indicates the horizontal position, and the second value indicates the vertical position. **0% 0%** indicates the upper left corner. **100% 100%** indicates the lower right corner. If only one value is specified, the other one is **50%**.<br>- Using both **percentage** and **length** values.|
| opacity | number | 1 | No | Opacity of an element. The value ranges from **0** to **1**. The value **1** means opaque, and **0** means completely transparent. |
| sizechange | { size: { height: heightLength, width: widthLength }, mode: modeStr } | Triggered when the status of the slidable panel changes. Available **mode** values are as follows:<br>- **mini**: Displays a **minibar** or **foldable** panel in its minimum size.<br>- **half**: Displays a **foldable** panel in a medium-sized (halfscreen-like) area.<br>- **full**: Displays a panel in a large (fullscreen-like) area.<br>The returned **height** value indicates the content area height. However, when the **dragbar** attribute is **true**, the **height** value is the height of the drag bar plus that of the content area.|
| sizechange | { size: { height: heightLength, width: widthLength }, mode: modeStr } | Triggered when the status of the slidable panel changes. Available **mode** values are as follows: <br>- **mini**: Displays a **minibar** or **foldable** panel in its minimum size. <br>- **half**: Displays a **foldable** panel in a medium-sized (halfscreen-like) area. <br>- **full**: Displays a panel in a large (fullscreen-like) area.NOTE:The returned **height** value indicates the content area height. However, when the **dragbar** attribute is **true**, the **height** value is the height of the drag bar plus that of the content area. |
## Methods
Only the following methods are supported.
The following methods are supported.
| Name | Parameter | Description |
| ----- | ---- | ------------- |
| show | - | Pops the slidable panel up.|
| close | - | Closes the slidable panel that has been popped up.|
| target | string | - | Yes | ID of the target element. Dynamic switch is not supported. |
| placement | string | bottom | No | Position of the pop-up. Available values are as follows: <br>- **left**: The pop-up is displayed on the left of the target item. <br>- **right**: The pop-up is displayed on the right of the target item. <br>- **top**: The pop-up is displayed at the top of the target item. <br>- **bottom**: The pop-up is displayed at the bottom of the target item. <br>- **topLeft**: The pop-up is displayed on the upper left of the target item. <br>- **topRight**: The pop-up is displayed on the upper right of the target item. <br>- **bottomLeft**: The pop-up is displayed on the bottom left of the target item. <br>- **bottomRight**: The pop-up is displayed on the bottom right of the target item. |
| keepalive<sup>5+</sup> | boolean | false | No | Whether to retain this pop-up. <br>- **true**: The pop-up does not disappear when users tap other areas or switch the page. To hide the pop-up, you need to call the **hide** method. <br>- **false**: The pop-up disappears when users tap other areas or switch the page. |
| clickable<sup>5+</sup> | boolean | true | No | Whether to display the pop-up when users click the bound control. If this parameter is set to **false**, the pop-up can be triggered only by a method call. |
| arrowoffset<sup>5+</sup> | \<length> | 0 | No | Offset of the pop-up arrow. By default, the arrow is centered. A positive value means that the arrow moves along the language direction (LTR or RTL), and a negative value means that the arrow moves along the opposite direction of the language direction. |
| target | string | - | Yes| ID of the target element. Dynamic switch is not supported.|
| placement | string | bottom | No| Position of the pop-up. Available values are as follows:<br>- **left**: The pop-up is displayed on the left of the target item.<br>- **right**: The pop-up is displayed on the right of the target item.<br>- **top**: The pop-up is displayed at the top of the target item.<br>- **bottom**: The pop-up is displayed at the bottom of the target item.<br>- **topLeft**: The pop-up is displayed on the upper left of the target item.<br>- **topRight**: The pop-up is displayed on the upper right of the target item.<br>- **bottomLeft**: The pop-up is displayed on the bottom left of the target item.<br>- **bottomRight**: The pop-up is displayed on the bottom right of the target item.|
| keepalive<sup>5+</sup>| boolean | false | No| Whether to retain this pop-up. **true**: The pop-up does not disappear when users tap other areas or switch the page. To hide the pop-up, call the **hide** method.<br>**false**: The pop-up disappears when users tap other areas or switch the page.|
| clickable<sup>5+</sup>| boolean | true | No| Whether to display the pop-up when users click the bound control. If this parameter is set to **false**, the pop-up can be triggered only by a method call.|
| arrowoffset<sup>5+</sup> | <length> | 0 | No| Offset of the pop-up arrow. By default, the arrow is centered. A positive value means that the arrow moves along the language direction (LTR or RTL), and a negative value means that the arrow moves along the opposite direction of the language direction.|
> 1. Attributes and styles of a **\<popup>** component cannot be dynamically updated.
>
> 2. Margins of a pop-up take effect depending on its position relative to the target element. For example, if the pop-up is below the target element, only **margin-top** takes effect; if the pop-up displays on the upper left of the target element, only **margin-bottom** and **margin-right** take effect.
>
> 3. Styles set for the four borders of a pop-up must be the same. If they are different and the border radius is **0**, the first configured border style (in the sequence of left, top, right, and bottom) takes effect. Otherwise, the **border** attribute does not take effect.
>
> 4. The click event bound to the target element of a pop-up does not take effect.
## Example Code
```
## Example
```html
<!-- xxx.hml -->
<divclass="container">
<textid="text">Click to show the pop-up</text>
<!-- popup supports single child of any type<sup>5+</sup> -->
<!-- popup supports single child of any type5+ -->
| offset | <length> | - | No| Distance to the top of the parent component from the **<Refresh\>** component that comes to rest after a successful pull-down gesture.|
| refreshing | boolean | false | No| Whether the **\<refresh>** component is being used for refreshing.|
| type | string | auto | No| Dynamic effect when the component is refreshed. Two options are available and cannot be modified dynamically.<br>- **auto**: default effect. When the list is pulled to the top, the list does not move. When the list is pulled to the bottom, a circle is displayed.<br>- **pulldown**: When the list is pulled to the top, users can continue to pull down to trigger a refresh. The rebound effect will appear after the refresh. If the child component contains a list, set **scrolleffect** of the list to **no** to prevent drop-down effect conflicts.|
| lasttime | boolean | false | No| Whether to display the last update time. The character string format is **last update time: XXXX**, where **XXXX** is displayed based on the certain time and date formats and cannot be dynamically modified. (It is recommended that this attribute be used when **type** is set to **pulldown**. The fixed distance is at the bottom of the content drop-down area. Pay attention to the **offset** attribute setting to prevent overlapping.)|
| timeoffset<sup>6+</sup> | <length> | - | No| Distance between the update time and the top of the parent component.|
| friction | number | 42 | No| Pull-down friction coefficient. The value ranges from 0 to 100. A larger value indicates a more responsive component. For example, if a user pulls the component down 100 px, it will actually move 100 * **friction**% px.|
| Name | Type | Default Value | Mandatory | Description |
| offset | \<length> | - | No | Distance to the top of the parent component from the **\<refresh>** component that comes to rest after a successful swipe gesture. |
| refreshing | boolean | false | No | Whether the **\<refresh>** component is being used for refreshing. |
| type | string | auto | No | Dynamic effect when the component is refreshed. Two options are available and cannot be modified dynamically. <br>- **auto**: default effect. When the list is pulled to the top, the list does not move. When the list is pulled to the bottom, a circle is displayed. <br>- **pulldown**: When the list is pulled to the top, users can continue to pull down to trigger a refresh. The rebound effect will appear after the refresh. If the child component contains a list, set **scrolleffect** of the list to **no** to prevent drop-down effect conflicts. |
| lasttime | boolean | false | No | Whether to display the last update time. The character string format is **last update time: XXXX**, where **XXXX** is displayed based on the time and date display specifications and cannot be dynamically modified. (It is recommended that this attribute be used when **type** is set to **pulldown**. The fixed distance is at the bottom of the content drop-down area. Pay attention to the **offset** attribute setting to prevent overlapping.) |
| timeoffset<sup>6+</sup> | \<length> | - | No | Sets the distance between the update time and the top of the parent component. |
| friction | number | 42 | No | Pull-down friction coefficient. The value ranges from **0** to **100**. A larger value indicates a more responsive component. For example, if a user pulls the component down 100 px, it will actually move 100 * **friction**% px. |
## Styles
In addition to the styles in [Universal Styles](js-components-common-styles.md), the following styles are supported.
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
| background-color | \<color> | white | No | Background color of the **\<refresh>** component. |
| progress-color | \<color> | black | No | Loading color of the **\<refresh>** component. |
## Events
The following events are supported.
| Name| Parameter| Description|
| -------- | -------- | -------- |
| refresh | { refreshing: refreshingValue } | Triggered when the **\<refresh>** component is pulled down and the refresh status changes. Available values are as follows:<br>- **false**: The **\<refresh>** component is being pulled down.<br>- **true**: The **\<refresh>** component is not being pulled down.|
| pulldown | { state: string } | Triggered when a user starts or stops pulling down the **\<refresh>** component. Available values are as follows:<br>- **start**: The pull-down starts.<br>- **end**: The pull-down ends.|
| refresh | { refreshing: refreshingValue } | Triggered when the **\<refresh>** component is pulled down and the refresh status changes. Available values are as follows: <br>- **false**: The **\<refresh>** component is being pulled down. <br>- **true**: The **\<refresh>** component is not being pulled down. |
| pulldown | { state: string } | Triggered when a user starts or stops pulling down the **\<refresh>** component. Available values are as follows: <br>- **start**: The pull-down starts. <br>- **end**: The pull-down ends. |
## Methods
Methods in [Universal Methods](js-components-common-methods.md) are not supported.
The [universal methods](../arkui-js/js-components-common-methods.md) are not supported.
| fingers | number | No| Minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.<br>Default value: **1**|
| direction | PanDirection | No| Pan direction. The enumerated value supports the AND (&) and OR (\|) operations.<br>Default value: **PanDirection.All**|
| distance | number | No| Minimum pan distance to trigger the gesture, in vp.<br>Default value: **5**<br>**NOTE**<br>If a pan gesture and tab swipe occur at the same time, set **distance** to **1** so that the gesture can be more easily recognized.|
| distance | number | No| Minimum pan distance to trigger the gesture, in vp.<br>Default value: **5**<br>**NOTE**<br>If a pan gesture and [tab](ts-container-tabs.md) swipe occur at the same time, set **distance** to **1** so that the gesture can be more easily recognized. |
@@ -41,7 +41,7 @@ Use the following attributes to bind gesture recognition to a component. When a
## Gesture Response Event
The component uses the **gesture** method to bind the gesture object and uses the events provided in this object to respond to the gesture operation. For example, the **onAction** event of the **TapGesture** object can be used to respond to a click event. For details about the event definitions of other gestures, see the corresponding gesture sections.
The component uses the **gesture** method to bind the gesture object and uses the events provided in this object to respond to the gesture operation. For example, the **onAction** event of the **TapGesture** object can be used to respond to a click event. For details about the event definitions of other gestures, see the corresponding gesture sections. To bind multiple gestures, use [combined gestures](ts-combined-gestures.md).
