@@ -16,12 +16,12 @@ Before you begin, there are some basic concepts that will help you better unders
OpenHarmony provides a UI development framework, known as ArkUI. ArkUI provides capabilities you may need for application UI development, including a wide array of components, layout calculation, animation, UI interaction, and drawing capabilities.
ArkUI comes with two development paradigms: JavaScript-based web-like development paradigm (web-like development paradigm for short) and TypeScript-based declarative development paradigm (declarative development paradigm for short). You can choose whichever development paradigm that aligns with your practice.
ArkUI comes with two development paradigms: eTS-based declarative development paradigm (declarative development paradigm for short) and JavaScript-compatible web-like development paradigm (web-like development paradigm for short). You can choose whichever development paradigm that aligns with your practice.
| Declarative development paradigm | Extended TypeScript (eTS) | Data-driven | Applications involving technological sophistication and teamwork | Mobile application and system application developers |
| Web-like development paradigm | JavaScript | Data-driven | Applications and service widgets with simple UIs | Frontend web developers |
| Declarative development paradigm | Extended TypeScript (eTS) | Data-driven | Applications involving technological sophistication and teamwork | Mobile application and system application developers |
For DevEco Studio V2.2 Beta1 and later versions, both the traditional coding mode and the low-code mode are supported when the JS language is used for development.
> This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
The **\<label>** component defines labels for the **\<input>**, **\<button>**, and **\<textarea>** components. When a label is clicked, the click effect of the component associated with the label will be triggered.
## Required Permissions
None
## Child Component
## Child Components
Not 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 |
| ------ | ------ | ---- | ---- | ----------- |
| target | string | - | No | Attribute ID of the target component.|
| Name | Type | Default Value | Mandatory | Description |
| color | \<color> | #e5000000 | No | Text color. |
| font-size | \<length> | 30px | No | Font size (px). |
| allow-scale | boolean | true | No | Whether the text size changes with the system's font size settings.NOTE: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). |
| font-style | string | normal | No | Font style. Available values are as follows:<br>-**normal**: standard font style<br>-**italic**: italic font style<br/> |
| 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.<br/> |
| 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.NOTE: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> | 0px | No | Text line height. When this parameter is set to **0px**, the text line height is not limited and the font size is adaptive. |
| 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 | - | No | Maximum number of lines in the text. |
| 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** |
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| 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). |
| 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 weight. For the number type, the value ranges from 100 to 900. The default value is 400. A larger value indicates a heavier font weight.<br>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-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> | 0px | No | Text line height. When this parameter is set to **0px**, the text line height is not limited and the font size is adaptive. |
| 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 in the family or the specified [custom font](../arkui-js/js-components-common-customizing-font.md) is used for the text.|
| max-lines | number | - | No | Maximum number of lines in the text. |
| 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: prefer-font-sizes: 12px,14px,16px|
An entrance piece that can contain images and text. It is usually used to display receivers, for example, email recipients or message recipients.
> **NOTE**
>
> This component is supported since API version 5. Updates will be marked with a superscript to indicate their earliest API version.
The **\<piece>** component provides an entrance piece that can contain images and text. It is usually used to display receivers, for example, email recipients or message recipients.
## Child Components
None
Not 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.
| content | string | Yes | Text content of the operational piece. |
| closable | boolean | No | Whether to display the delete icon for the operational piece. When users click the delete icon, it triggers the close event.<br>Default value: **false**|
| icon | string | No | URL of the delete icon for the operational piece. The value can be a local path. |
| Name | Type | Default Value | Mandatory | Description |
| content | string | - | Yes | Text content of the operational piece. |
| closable | boolean | false | No | Whether to display the delete icon for the operational piece. When users click the delete icon, it triggers the close event. |
| icon | string | - | No | URL of the delete icon for the operational piece. The value can be a local path. |
## Styles
Styles in [Universal Styles](js-components-common-styles.md) are supported.
The [universal styles](../arkui-js/js-components-common-styles.md) are supported.
>  **NOTE:** By default, text and images are placed in the middle of the **\<piece>** component.
> **NOTE**
>
> By default, text and images are placed in the middle of the **\<piece>** component.
## Events
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.
> - If the values of **width** and **height** are different, the smaller value is used as the length of the QR code. The generated QR code is centered.
>
>
> - If either **width** or **height** is set, the value is used as the length of the QR code. If neither of them is set, the default length 200 px is used.
>
> - If the values of **width** and **height** are different, the smaller value is used as the length of the QR code. The generated QR code is center displayed.
> - If either **width** or **height** is set, the value is used as the length of the QR code. If neither of them is set, the default length is 200 px.
## Events
Events in [Universal Events](js-components-common-events.md) are supported.
The [universal events](../arkui-js/js-components-common-events.md) are supported.
## 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
```
```html
<!-- xxx.hml -->
<divclass="container">
<qrcodevalue="{{qr_value}}"type="{{qr_type}}"
...
...
@@ -63,6 +70,9 @@ Methods in [Universal Methods](js-components-common-methods.md) are supported.
The **\<span>** child component of **\<[text](js-components-basic-text.md)>** is used as a text modifier.
> **NOTE**
>
> This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
As a child component of **[\<text>](../arkui-js/js-components-basic-text.md)**, the **\<span>** component is used as a text modifier.
## Required Permissions
None
## Child Components
The **\<span>** child component is supported.
Not supported
## Attributes
Attributes in [Universal Attributes](js-components-common-attributes.md) are supported.
The [universal attributes](../arkui-js/js-components-common-attributes.md) are supported.
>  **NOTE:** The **focusable** and **disabled** attributes are not supported.
> **NOTE**
>
> The **focusable** and **disabled** attributes are not supported.
## Styles
Only the following style attributes are supported.
## Styles
Only the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| color | <color> | - | No | Font color of the modified text. |
| font-size | <length> | 30px | No | Font size of the modified text. |
| allow-scale | boolean | true | No | Whether the font size of the modified text 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.|
| font-style | string | normal | No | Font style of the modified text. For details, see **font-style** of the [**\<text>**](../arkui-js/js-components-basic-text.md#styles) component.|
| font-weight | number \| string | normal | No | Font weight of the modified text. For details, see **font-weight** of the [**\<text>**](../arkui-js/js-components-basic-text.md#styles) component.|
| text-decoration | string | none | No | Text decoration of the modified text. For details, see **text-decoration** 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.|
| Name | Type | Default Value | Mandatory | Description |
| color | \<color> | - | No | Font color of the modified text. |
| font-size | \<length> | 30px | No | Font size of the modified text. |
| allow-scale | boolean | true | No | Whether the font size of the modified text 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. |
| font-style | string | normal | No | Font style of the modified text. For details, see [font-style](js-components-basic-text.md) of the **text** component. |
| font-weight | number \| string | normal | No | Font weight of the modified text. For details, see [font-weight](js-components-basic-text.md) of the **text** component. |
| text-decoration | string | none | No | Text decoration of the modified text. For details, see [text-decoration](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 in the family or the font specified by [Custom Font Styles](js-components-common-customizing-font.md) is used for the text. |
## Events
Only the click event in [Universal Events](js-components-common-events.md) is supported.
Only the click event in [Universal Events](../arkui-js/js-components-common-events.md) is supported.
> This component is supported since API version 5. Updates will be marked with a superscript to indicate their earliest API version.
The **\<toggle>** component allows your user to select from a group of options and may display the selection result in real time. Generally, the option group consists of many toggles.
## Required Permissions
None
## Child Component
## Child Components
Not 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 |
| ------- | ------- | ----- | ---- | ---------- |
| value | string | - | Yes | Text value of the toggle. |
| checked | boolean | false | No | Whether the toggle is selected.|
| Name | Type | Default Value | Mandatory | Description |
| text-color | <color> | \#E5000000 | No | Text color of the toggle. |
| font-size | <length> | 16px | No | Font size of the toggle. |
| 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.|
| font-style | string | normal | No | Font style of the toggle. |
| font-weight | number \| string | normal | No | Font weight of the toggle. 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.|
| Name | Type | Default Value | Mandatory | Description |
| text-color | \<color> | #E5000000 | No | Text color of the toggle. |
| font-size | \<length> | 16px | No | Font size of the toggle. |
| 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. |
| font-style | string | normal | No | Font style of the toggle. |
| font-weight | number \| string | normal | No | Font weight of the toggle. For details, see **font-weight** of the [text](js-components-basic-text.md) 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 font specified by [Custom Font Styles](js-components-common-customizing-font.md) is used for the text. |
## 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 | { checked: isChecked } | Triggered when the toggle is selected or unselected. |
## Methods
Methods in [Universal Methods](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.1-Release/en/application-dev/reference/arkui-js/js-components-common-methods.md) are supported.
The [universal methods](../arkui-js/js-components-common-methods.md) are supported.
The **\<toolbar-item>** component is the child component of **\<toolbar>** to display an operation option on the toolbar.
> **NOTE**
>
> This component is supported since API version 5. Updates will be marked with a superscript to indicate their earliest API version.
## Child Component
As a child component of **[\<toolbar>](js-components-basic-toolbar.md)**, the **\<toolbar-item>** component is used to display an operation option on the toolbar.
None
## Attributes
## Child Components
Not 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 | Description |
| value | string | - | Yes | Text content of the operation option. |
| icon | string | - | Yes | Icon image path, which is displayed on the option text. The value can be a local path. Supported image formats are PNG, JPG, and SVG.|
| Name | Type | Default Value | Mandatory | Description |
| value | string | - | Yes | Text content of the operation option. |
| icon | string | - | Yes | Icon image path, which is displayed on the option text. The value is a local path. Supported image formats are PNG, JPG, and SVG. |
## Styles
Only the following style attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| color | \<color> | #e6000000 | No | Text color. |
| font-size | \<length> | 16px | No | Text size. |
| allow-scale | boolean | true | No | Whether the text size changes with the system's font size settings. |
| font-style | string | normal | No | Text font style. Available values are as follows:<br/>-**normal**: standard font style<br/>-**italic**: italic font style |
| font-weight | number\|string | normal | No | Text font weight. The number value must be an exact multiple of 100 ranging from 100 to 900. The default value is 400. A larger value indicates a bigger weight. Available values of the string type are **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. |
| 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 font specified by [Custom Font Styles](js-components-common-customizing-font.md) is used for the text. |
| 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**. Both online and local image resources are supported. |
| background-size | <br/>-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\<length> \<length>\<percentage> \<percentage> | 0px 0px | No | <br/>-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. |
| display | string | flex | No | Type of the box containing an element. Available values are as follows:<br/>-**flex**: flexible layout<br/>-**none**: The box is disabled. |
| visibility | string | visible | No | Whether to display the box containing an element. The invisible box occupies layout space. (To remove the box, set the **display** attribute to **none**.) Available values are as follows:<br/>-**visible**: The box is visible.<br/>-**hidden**: The box is hidden but still takes up space.<br/>NOTE:<br/>If both **visibility** and **display** are set, only **display** takes effect. |
Only the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| color | <color> | \#e6000000 | No | Font color. |
| font-size | <length> | 16px | No | Font size. |
| allow-scale | boolean | true | No | Whether the font size changes with the system's font size settings. |
| 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 weight. The number value must be an exact multiple of 100 ranging from 100 to 900. The default value is 400. A larger value indicates a bigger weight. Available values of the string type are **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.|
| 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.|
| 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. Currently, this attribute is not compatible with **background-color** or **background**. Both online and local image resources are supported.|
| background-size | - string<br>- <length><length><br>- <percentage><percentage> | auto | No | Background image size.<br>- The available values of the **string** type are as follows:<br> - **contain**: extends 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>- Values of the **\<length>** type: The two 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>- Values of the **\<percentage>** type: The two 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 | How a background image is repeatedly drawn. By default, a background image is repeated both horizontally and vertically.<br>- **repeat**: The image is repeated along both the x-axis and y-axis.<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 | Position of the background image.<br>- Values of the **string** type: If you set only one value, the other value is set to **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 in the horizontal or vertical direction.<br>- Values of the **\<length>** type: 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 in px (**0px 0px**). If you only set one value, the other value is set to **50%**.<br>- Values of the **\<percentage>** type: 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%**. For the lower right corner, the value is **100% 100%**. If you only set one value, the other value is set to **50%**.<br>- Values of the **\<percentage>** type and **\<length>** type can be used together.|
| 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. |
| display | string | flex | No | Type of the box containing an element. Available values are as follows:<br>- **flex**: flexible layout<br>- **none**: not rendered|
| visibility | string | visible | No | Whether to display the box containing an element. A hidden box still occupies layout space. (To remove the box, set the **display** attribute to **none**.) Available values are as follows:<br>- **visible**: The box is visible.<br>- **hidden**: The box is hidden but still takes up space.<br>If both **visibility** and **display** are set, only **display** takes effect.|
## Events
Events in [Universal Events](js-components-common-events.md) are supported.
The [universal events](../arkui-js/js-components-common-events.md) are supported.
| type | string | Yes | The value is set to **'2d'**, indicating that a 2D drawing object is returned. This object can be used to draw rectangles, texts, and images on the canvas component. |
| options6+ | [ContextAttrOptions](js-components-canvas-canvas.md) | No | Whether to enable anti-aliasing. By default, anti-aliasing is disabled. |
| type | string | Yes | Object type. The value is set to **'2d'**, indicating that a 2D drawing object is returned. This object can be used to draw rectangles, texts, and images on the canvas component.|
| options<sup>6+</sup> | ContextAttrOptions | No | Whether to enable anti-aliasing. By default, anti-aliasing is disabled. |
**Table 1** ContextAttrOptions
| Name | Type | Description |
| --------- | ------- | ------------------- |
| antialias | boolean | Whether to enable anti-aliasing. The default value is **false**.|
| [CanvasRenderingContext2D](../arkui-js/js-components-canvas-canvasrenderingcontext2d.md) | 2D drawing object, which can be used to draw rectangles, images, and texts on the canvas component.|
| [CanvasRenderingContext2D](js-components-canvas-canvasrenderingcontext2d.md) | 2D drawing object, which can be used to draw rectangles, images, and texts on the canvas component. |
| type | string | No | Image format. The default value is **image/png**. |
| quality | number | No | Image quality, which ranges from 0 to 1, when the image format is **image/jpeg** or **image/webp**. If the set value is beyond the value range, the default value **0.92** is used. |
| type | string | No | Image format. The default value is **image/png**. |
| quality | number | No | Image quality, which ranges from 0 to 1, when the image format is **image/jpeg** or **image/webp**. If the set value is beyond the value range, the default value **0.92** is used.|
| shareid | string | - | Used for the transition of shared elements, which takes effect only when this attribute is set. **\<list-item>**, **\<image>**, **\<text>**, **\<button>**, and **\<label>** components are supported for the transition of shared elements.|
| shareid | string | - | Used for the transition of shared elements, which takes effect only when this attribute is set. **\<list-item>**, **\<image>**, **\<text>**, **\<button>**, and **\<label>** components are supported for the transition of shared elements.|
| shared-transition-effect | string | exchange | Entry style of a shared element during transition.<br>- **exchange** (default): The source page element is moved to the position of the target page element and is zoomed in or out properly.<br>- **static**: The position of the target page element remains unchanged. You can configure the opacity animation. Currently, only the static effect configured on the target page takes effect.|
| shared-transition-effect | string | exchange | Entry style of a shared element during transition.<br>-**exchange** (default): The source page element is moved to the position of the target page element and is zoomed in or out properly.<br>- **static**: The position of the target page element remains unchanged. You can configure the opacity animation. Currently, only the static effect configured on the target page takes effect.|
| shared-transition-name | string | - | During the transition, the style configured on the target page takes effect preferentially. This style is used to configure the animation effect of shared elements. The animation effect is an animation sequence defined by **@keyframes** supporting transform and opacity animations. If the effect of shared elements conflicts with the custom animation, the latter is used.|
| shared-transition-timing-function | string | friction | During the transition, the style configured on the target page takes effect preferentially. This style defines the difference curve during the transition of shared elements. If it is not configured, the friction curve is used.|
...
...
@@ -52,7 +52,7 @@ In the example below, where **PageA** jumps to **PageB**, the shared element is
| transition-effect | string | - | Whether a component on the current page displays the transition effect during a widget transition. Available values are as follows:<br>- **unfold**: The component will move upwards by one widget height if the component is located above the widget tapped by the user, or move downwards by one widget height if the component is located below the widget.<br>- **none**: No transition effect is displayed. |
| transition-effect | string | - | Whether a component on the current page displays the transition effect during a widget transition. Available values are as follows:<br>-**unfold**: The component will move upwards by one widget height if the component is located above the widget tapped by the user, or move downwards by one widget height if the component is located below the widget.<br>- **none**: No transition effect is displayed.|
### Example
...
...
@@ -140,7 +139,7 @@ The **source_page** has a title area on the top and a widget list. Users can tap
| transition-enter | string | - | Works with **@keyframes** and supports transform and opacity animations. For details, see [Attributes available for the @keyframes rule](../arkui-js/js-components-common-animation.md).|
| transition-exit | string | - | Works with **@keyframes** and supports transform and opacity animations. For details, see [Attributes available for the @keyframes rule](../arkui-js/js-components-common-animation.md).|
| transition-duration | string | Follows the default page transition time of the device | The unit can be s or ms. The default unit is ms. If no value is specified, the default value is used. |
| transition-duration | string | Follows the default page transition time of the device| The unit can be s|or ms. The default unit is ms. If no value is specified, the default value is used.|
| transition-timing-function | string | friction | Speed curve of the transition animation, which makes the animation more fluent. For details, see the description of **animation-timing-function **in [Animation Styles](../arkui-js/js-components-common-animation.md).|
| index | number | 0 | No | Index of the child component currently displayed in the container. |
| autoplay | boolean | false | No | Whether to enable autoplay for child component switching. If this attribute is **true**, the indicator does not take effect<sup>5+</sup>. |
| interval | number | 3000 | No | Autoplay interval, in milliseconds, when autoplay is enabled. |
| indicator | boolean | true | No | Whether to enable the indicator. The default value is **true**. |
| digital<sup>5+</sup> | boolean | false | No | Whether to enable the digital indicator. The default value is **false**.<br>The digital indicator takes effect only when **indicator** is set to **true**.|
| indicatordisabled<sup>5+</sup> | boolean | false | No | Whether gesture operations are disabled on the indicator. If this attribute is set to **true**, the indicator does not respond to clicking or dragging operations. |
| loop | boolean | true | No | Whether to enable looping. |
| duration | number | - | No | Duration of the autoplay for child component switching. |
| vertical | boolean | false | No | Whether the swipe gesture is performed vertically. A vertical swipe uses the vertical indicator. |
| cachedsize<sup>7+</sup> | number | -1 | No | Minimum number of cached items during delayed loading of the **\<swiper>** component. The value **-1** indicates that all content is cached. |
| scrolleffect<sup>7+</sup> | string | spring | No | Scroll effect. The options are as follows:<br>- **spring**: Similar to the physical dynamic effect of a spring. When the scrollbar reaches the edge, it can continue to scroll for a distance based on the initial speed or a touch event. It rebounds after being released.<br>- **fade**: Similar to the physical dynamic effect of fade. When the scrollbar reaches the edge, a wave shape fades. The fade changes according to the speed and scrolling distance.<br>- **none**: No effect when the scrollbar reaches the edge.<br>This attribute is valid only when **loop** is set to **false**.|
| Name | Type | Default Value | Mandatory | Description |
| index | number | 0 | No | Index of a child component currently displayed in the container. |
| autoplay | boolean | false | No | Whether to enable autoplay for child component switching. If this attribute is **true**, the indicator does not take effect<sup>5+</sup>. |
| interval | number | 3000 | No | Autoplay interval, in milliseconds, when autoplay is enabled. |
| indicator | boolean | true | No | Whether to enable the indicator. The default value is **true**. |
| digital<sup>5+</sup> | boolean | false | No | Whether to enable the digital indicator. The default value is **false**.<br>NOTE:<br>The digital indicator takes effect only when **indicator** is set to **true**. |
| indicatordisabled<sup>5+</sup> | boolean | false | No | Whether gesture operations are disabled on the indicator. If this attribute is set to **true**, the indicator does not respond to clicking or dragging operations. |
| loop | boolean | true | No | Whether to enable looping. |
| duration | number | - | No | Duration of the autoplay for child component switching. |
| vertical | boolean | false | No | Whether the swipe gesture is performed vertically. A vertical swipe uses the vertical indicator. |
| cachedsize<sup>7+</sup> | number | -1 | No | Minimum number of cached items during delayed loading of the **\<swiper>** component. The value **-1** indicates that all content is cached. |
| scrolleffect<sup>7+</sup> | string | spring | No | Scroll effect. The options 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>- **none**: No effect after the scroll bar is moved to the edge.NOTE:This attribute is valid only when **loop** is set to **false**. |
## 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 |
| muted | boolean | false | No| Whether the video is muted.|
| src | string | - | No| Path of the video content to play.|
| autoplay | boolean | false | No| Whether the video is played automatically after being rendered.|
| controls | boolean | true | No| Whether the control bar is displayed during video playback. If the value is set to **false**, the control bar is not displayed. The default value is **true**, indicating that the platform can either show or hide the control bar.|
| Name | Type | Default Value | Mandatory | Description |
| muted | boolean | false | No | Whether the video is muted. |
| src | string | - | No | Path of the video content to play. |
| autoplay | boolean | false | No | Whether the video is played automatically after being rendered. |
| controls | boolean | true | No | Whether the control bar is displayed during video playback. If the value is set to **false**, the control bar is not displayed. The default value is **true**, indicating that the platform can either show or hide the control bar.|
## Styles
In addition to the [universal styles](../arkui-js/js-components-common-styles.md), the following styles are supported.
| object-fit | string | contain | No| Video scale type. If **poster** has been assigned a value, the setting of this style will affect the scaling type of the video poster. For details, see object-fit enums.|
| Name | Type | Default Value | Mandatory | Description |
| object-fit | string | contain | No| Video scale type. If **poster** has been assigned a value, the setting of this style will affect the scaling type of the video poster. For details, see object-fit enums.|
**Table 1** object-fit enums
| Type| Description|
| -------- | -------- |
| Type | Description |
| ---- | ------------------------- |
| fill | The image is resized to fill the display area, and its aspect ratio is not retained.|
...
...
@@ -54,31 +44,31 @@ In addition to the [universal styles](../arkui-js/js-components-common-styles.md
In addition to the [universal events](../arkui-js/js-components-common-events.md), the following events are supported.
| Name| Parameter| Description|
| -------- | -------- | -------- |
| prepared | { duration: value }<sup>5+</sup> | Triggered when the video preparation is complete. The video duration (in seconds) is obtained from **duration**.|
| start | - | Triggered when the video is played.|
| pause | - | Triggered when the video playback is paused.|
| finish | - | Triggered when the video playback is finished.|
| error | - | Triggered when the video playback fails.|
| seeking | { currenttime: value } | Triggered to report the time (in seconds) when the progress bar is being dragged.|
| seeked | { currenttime: value } | Triggered to report the playback time (in seconds) when the user finishes dragging the progress bar.|
| timeupdate | { currenttime: value } | Triggered once per 250 ms when the playback progress changes. The unit of the current playback time is second.|
| prepared | { duration: value }<sup>5+</sup> | Triggered when the video preparation is complete. The video duration (in seconds) is obtained from **duration**.|
| start | - | Triggered when the video is played. |
| pause | - | Triggered when the video playback is paused. |
| finish | - | Triggered when the video playback is finished. |
| error | - | Triggered when the video playback fails. |
| seeking | { currenttime: value } | Triggered to report the time (in seconds) when the progress bar is being dragged. |
| seeked | { currenttime: value } | Triggered to report the playback time (in seconds) when the user finishes dragging the progress bar. |
| timeupdate | { currenttime: value } | Triggered once per 250 ms when the playback progress changes. The unit of the current playback time is second. |
## Methods
In addition to the [universal methods](../arkui-js/js-components-common-methods.md), the following methods are supported.
| Name| Parameter| Description|
| -------- | -------- | -------- |
| start | - | Starts playing a video.|
| pause | - | Pauses a video.|
| setCurrentTime | { currenttime: value } | Sets the video playback position, in seconds.|
