提交 b5302f66 编写于 作者: E ester.zhou

Add js-service-widget-ui folder

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 123c8a9e
...@@ -4,7 +4,9 @@ You can apply background blur effects to a component. ...@@ -4,7 +4,9 @@ You can apply background blur effects to a component.
> **NOTE** > **NOTE**
> >
>The APIs of this module are supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version. > The APIs of this module are supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
>
> The APIs provided by this module are system APIs.
## Attributes ## Attributes
...@@ -14,11 +16,11 @@ You can apply background blur effects to a component. ...@@ -14,11 +16,11 @@ You can apply background blur effects to a component.
## BlurStyle ## BlurStyle
| Name | Description | | Name | Description |
| ------- | ---------- | | ------- | ---------- |
| Thin | Thin material. | | Thin | Thin material. |
| Regular | Regular material. | | Regular | Regular material. |
| Thick | Thick material. | | Thick | Thick material. |
## Example ## Example
......
# JS Service Widget UI Components
- JS Service Widget UI Framework
- [File Organization](js-service-widget-file.md)
- Syntax
- [HML](js-service-widget-syntax-hml.md)
- [CSS](js-service-widget-syntax-css.md)
- [Multi-Language Capability](js-service-widget-multiple-languages.md)
- [Version Compatibility Adaptation](js-service-widget-version-compatibility.md)
- [Theme Configuration](js-service-widget-theme.md)
- Components
- Universal
- [Universal Attributes](js-service-widget-common-attributes.md)
- [Universal Styles](js-service-widget-common-styles.md)
- [Universal Events](js-service-widget-common-events.md)
- [Gradient Styles](js-service-widget-common-gradient.md)
- [Media Query](js-service-widget-common-mediaquery.md)
- [Custom Font Styles](js-service-widget-common-customizing-font.md)
- [Accessibility](js-service-widget-common-accessibility.md)
- [Atomic Layout](js-service-widget-common-atomic-layout.md)
- Container Components
- [badge](js-service-widget-container-badge.md)
- [div](js-service-widget-container-div.md)
- [list](js-service-widget-container-list.md)
- [list-item](js-service-widget-container-list-item.md)
- [stack](js-service-widget-container-stack.md)
- [swiper](js-service-widget-container-swiper.md)
- Basic Components
- [button](js-service-widget-basic-button.md)
- [calendar](js-service-widget-basic-calendar.md)
- [chart](js-service-widget-basic-chart.md)
- [clock](js-service-widget-basic-clock.md)
- [divider](js-service-widget-basic-divider.md)
- [image](js-service-widget-basic-image.md)
- [input](js-service-widget-basic-input.md)
- [progress](js-service-widget-basic-progress.md)
- [span](js-service-widget-basic-span.md)
- [text](js-service-widget-basic-text.md)
- [Custom Component Basic Usage](js-service-widget-custom-basic-usage.md)
- [Data Types](js-service-widget-appendix-types.md)
# Data Types
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Length Type
| Name | Type | Description |
| ---------- | -------------------------- | ---------------------------------------- |
| length | string \| number | Size unit. When the type is **number**, the unit is px. When the type is **string**, the pixel unit must be explicitly specified. Currently, the following pixel units are supported:<br>- **px**: logical size unit.<br>- **fp**: font pixel unit, which varies according to the system font size. This unit is only available for text components.|
| percentage | string | Unit in percentage, for example, **'50%'**. |
## Color Type
| Name | Type | Description |
| ----- | ------------------ | ---------------------------------------- |
| color | string \|Color enumeration| Color information.<br>The string format is as follows:<br>- 'rgb(255, 255, 255)'<br>- 'rgba(255, 255, 255, 1.0)'<br>- HEX format: '\#rrggbb', '\#aarrggbb'<br>- Enumeration format: 'black','white'<br>The enumeration format is not supported in the JS script.|
**Table 1** Color enums
| Name | Hexadecimal Code | Color |
| -------------------- | -------- | ---------------------------------------- |
| aliceblue | \#f0f8ff | ![aliceblue](figures/aliceblue.png) |
| antiquewhite | \#faebd7 | ![antiquewhite](figures/antiquewhite.png) |
| aqua | \#00ffff | ![aqua](figures/aqua.png) |
| aquamarine | \#7fffd4 | ![aquamarine](figures/aquamarine.png) |
| azure | \#f0ffff | ![azure](figures/azure.png) |
| beige | \#f5f5dc | ![beige](figures/beige.png) |
| bisque | \#ffe4c4 | ![bisque](figures/bisque.png) |
| black | \#000000 | ![#000000](figures/000000.png) |
| blanchedalmond | \#ffebcd | ![blanchedalmond](figures/blanchedalmond.png) |
| blue | \#0000ff | ![blue](figures/blue.png) |
| blueviolet | \#8a2be2 | ![blueviolet](figures/blueviolet.png) |
| brown | \#a52a2a | ![brown](figures/brown.png) |
| burlywood | \#deB887 | ![burlywood](figures/burlywood.png) |
| cadetblue | \#5f9ea0 | ![cadetblue](figures/cadetblue.png) |
| chartreuse | \#7fff00 | ![chartreuse](figures/chartreuse.png) |
| chocolate | \#d2691e | ![chocolate](figures/chocolate.png) |
| coral | \#ff7f50 | ![coral](figures/coral.png) |
| cornflowerblue | \#6495ed | ![cornflowerblue](figures/cornflowerblue.png) |
| cornsilk | \#fff8dc | ![cornsilk](figures/cornsilk.png) |
| crimson | \#dc143c | ![crimson](figures/crimson.png) |
| cyan | \#00ffff | ![cyan](figures/cyan.png) |
| darkblue | \#00008b | ![darkblue](figures/darkblue.png) |
| darkcyan | \#008b8b | ![darkcyan](figures/darkcyan.png) |
| darkgoldenrod | \#b8860b | ![darkgoldenrod](figures/darkgoldenrod.png) |
| darkgray | \#a9a9a9 | ![darkgray](figures/darkgray.png) |
| darkgreen | \#006400 | ![darkgreen](figures/darkgreen.png) |
| darkgrey | \#a9a9a9 | ![darkgrey](figures/darkgrey.png) |
| darkkhaki | \#bdb76b | ![darkkhaki](figures/darkkhaki.png) |
| darkmagenta | \#8b008b | ![darkmagenta](figures/darkmagenta.png) |
| darkolivegreen | \#556b2f | ![darkolivegreen](figures/darkolivegreen.png) |
| darkorange | \#ff8c00 | ![darkorange](figures/darkorange.png) |
| darkorchid | \#9932cc | ![darkorchid](figures/darkorchid.png) |
| darkred | \#8b0000 | ![darkred](figures/darkred.png) |
| darksalmon | \#e9967a | ![darksalmon](figures/darksalmon.png) |
| darkseagreen | \#8fbc8f | ![darkseagreen](figures/darkseagreen.png) |
| darkslateblue | \#483d8b | ![darkslateblue](figures/darkslateblue.png) |
| darkslategray | \#2f4f4f | ![darkslategray](figures/darkslategray.png) |
| darkslategrey | \#2f4f4f | ![darkslategrey](figures/darkslategrey.png) |
| darkturquoise | \#00ced1 | ![darkturquoise](figures/darkturquoise.png) |
| darkviolet | \#9400d3 | ![darkviolet](figures/darkviolet.png) |
| deeppink | \#ff1493 | ![deeppink](figures/deeppink.png) |
| deepskyblue | \#00bfff | ![deepskyblue](figures/deepskyblue.png) |
| dimgray | \#696969 | ![dimgray](figures/dimgray.png) |
| dimgrey | \#696969 | ![dimgrey](figures/dimgrey.png) |
| dodgerblue | \#1e90ff | ![dodgerblue](figures/dodgerblue.png) |
| firebrick | \#b22222 | ![firebrick](figures/firebrick.png) |
| floralwhite | \#fffaf0 | ![floralwhite](figures/floralwhite.png) |
| forestgreen | \#228b22 | ![forestgreen](figures/forestgreen.png) |
| fuchsia | \#ff00ff | ![fuchsia](figures/fuchsia.png) |
| gainsboro | \#dcdcdc | ![gainsboro](figures/gainsboro.png) |
| ghostwhite | \#f8f8ff | ![ghostwhite](figures/ghostwhite.png) |
| gold | \#ffd700 | ![gold](figures/gold.png) |
| goldenrod | \#daa520 | ![goldenrod](figures/goldenrod.png) |
| gray | \#808080 | ![gray](figures/gray.png) |
| green | \#008000 | ![green](figures/green.png) |
| greenyellow | \#adff2f | ![greenyellow](figures/greenyellow.png) |
| grey | \#808080 | ![grey](figures/grey.png) |
| honeydew | \#f0fff0 | ![honeydew](figures/honeydew.png) |
| hotpink | \#ff69b4 | ![hotpink](figures/hotpink.png) |
| indianred | \#cd5c5c | ![indianred](figures/indianred.png) |
| indigo | \#4b0082 | ![indigo](figures/indigo.png) |
| ivory | \#fffff0 | ![ivory](figures/ivory.png) |
| khaki | \#f0e68c | ![khaki](figures/khaki.png) |
| lavender | \#e6e6fa | ![lavender](figures/lavender.png) |
| lavenderblush | \#fff0f5 | ![lavenderblush](figures/lavenderblush.png) |
| lawngreen | \#7cfc00 | ![lawngreen](figures/lawngreen.png) |
| lemonchiffon | \#fffacd | ![lemonchiffon](figures/lemonchiffon.png) |
| lightblue | \#add8e6 | ![lightblue](figures/lightblue.png) |
| lightcoral | \#f08080 | ![lightcoral](figures/lightcoral.png) |
| lightcyan | \#e0ffff | ![lightcyan](figures/lightcyan.png) |
| lightgoldenrodyellow | \#fafad2 | ![lightgoldenrodyellow](figures/lightgoldenrodyellow.png) |
| lightgray | \#d3d3d3 | ![lightgray](figures/lightgray.png) |
| lightgreen | \#90ee90 | ![lightgreen](figures/lightgreen.png) |
| lightpink | \#ffb6c1 | ![lightpink](figures/lightpink.png) |
| lightsalmon | \#ffa07a | ![lightsalmon](figures/lightsalmon.png) |
| lightseagreen | \#20b2aa | ![lightseagreen](figures/lightseagreen.png) |
| lightskyblue | \#87cefa | ![lightskyblue](figures/lightskyblue.png) |
| lightslategray | \#778899 | ![lightslategray](figures/lightslategray.png) |
| lightslategrey | \#778899 | ![lightslategrey](figures/lightslategrey.png) |
| lightsteelblue | \#b0c4de | ![lightsteelblue](figures/lightsteelblue.png) |
| lightyellow | \#ffffe0 | ![lightyellow](figures/lightyellow.png) |
| lime | \#00ff00 | ![lime](figures/lime.png) |
| limegreen | \#32cd32 | ![limegreen](figures/limegreen.png) |
| linen | \#faf0e6 | ![linen](figures/linen.png) |
| magenta | \#ff00ff | ![magenta](figures/magenta.png) |
| maroon | \#800000 | ![maroon](figures/maroon.png) |
| mediumaquamarine | \#66cdaa | ![mediumaquamarine](figures/mediumaquamarine.png) |
| mediumblue | \#0000cd | ![mediumblue](figures/mediumblue.png) |
| mediumorchid | \#ba55d3 | ![mediumorchid](figures/mediumorchid.png) |
| mediumpurple | \#9370db | ![mediumpurple](figures/mediumpurple.png) |
| mediumseagreen | \#3cb371 | ![mediumseagreen](figures/mediumseagreen.png) |
| mediumslateblue | \#7b68ee | ![mediumslateblue](figures/mediumslateblue.png) |
| mediumspringgreen | \#00fa9a | ![mediumspringgreen](figures/mediumspringgreen.png) |
| mediumturquoise | \#48d1cc | ![mediumturquoise](figures/mediumturquoise.png) |
| mediumvioletred | \#c71585 | ![mediumvioletred](figures/mediumvioletred.png) |
| midnightblue | \#191970 | ![midnightblue](figures/midnightblue.png) |
| mintcream | \#f5fffa | ![mintcream](figures/mintcream.png) |
| mistyrose | \#ffe4e1 | ![mistyrose](figures/mistyrose.png) |
| moccasin | \#ffe4b5 | ![moccasin](figures/moccasin.png) |
| navajowhite | \#ffdead | ![navajowhite](figures/navajowhite.png) |
| navy | \#000080 | ![navy](figures/navy.png) |
| oldlace | \#fdf5e6 | ![oldlace](figures/oldlace.png) |
| olive | \#808000 | ![olive](figures/olive.png) |
| olivedrab | \#6b8e23 | ![olivedrab](figures/olivedrab.png) |
| orange | \#ffa500 | ![orange](figures/orange.png) |
| orangered | \#ff4500 | ![orangered](figures/orangered.png) |
| orchid | \#da70d6 | ![orchid](figures/orchid.png) |
| palegoldenrod | \#eee8aa | ![palegoldenrod](figures/palegoldenrod.png) |
| palegreen | \#98fb98 | ![palegreen](figures/palegreen.png) |
| paleturquoise | \#afeeee | ![paleturquoise](figures/paleturquoise.png) |
| palevioletred | \#db7093 | ![palevioletred](figures/palevioletred.png) |
| papayawhip | \#ffefd5 | ![papayawhip](figures/papayawhip.png) |
| peachpuff | \#ffdab9 | ![peachpuff](figures/peachpuff.png) |
| peru | \#cd853f | ![peru](figures/peru.png) |
| pink | \#ffc0cb | ![pink](figures/pink.png) |
| plum | \#dda0dd | ![plum](figures/plum.png) |
| powderblue | \#b0e0e6 | ![powderblue](figures/powderblue.png) |
| purple | \#800080 | ![purple](figures/purple.png) |
| rebeccapurple | \#663399 | ![rebeccapurple](figures/rebeccapurple.png) |
| red | \#ff0000 | ![red](figures/red.png) |
| rosybrown | \#bc8f8f | ![rosybrown](figures/rosybrown.png) |
| royalblue | \#4169e1 | ![royalblue](figures/royalblue.png) |
| saddlebrown | \#8b4513 | ![saddlebrown](figures/saddlebrown.png) |
| salmon | \#fa8072 | ![salmon](figures/salmon.png) |
| sandybrown | \#f4a460 | ![sandybrown](figures/sandybrown.png) |
| seagreen | \#2e8b57 | ![seagreen](figures/seagreen.png) |
| seashell | \#fff5ee | ![seashell](figures/seashell.png) |
| sienna | \#a0522d | ![sienna](figures/sienna.png) |
| silver | \#c0c0c0 | ![silver](figures/silver.png) |
| skyblue | \#87ceeb | ![skyblue](figures/skyblue.png) |
| slateblue | \#6a5acd | ![slateblue](figures/slateblue.png) |
| slategray | \#708090 | ![slategray](figures/slategray.png) |
| slategrey | \#708090 | ![slategray](figures/slategray.png) |
| snow | \#fffafa | ![snow](figures/snow.png) |
| springgreen | \#00ff7f | ![springgreen](figures/springgreen.png) |
| steelblue | \#4682b4 | ![steelblue](figures/steelblue.png) |
| tan | \#d2b48c | ![tan](figures/tan.png) |
| teal | \#008080 | ![teal](figures/teal.png) |
| thistle | \#d8Bfd8 | ![thistle](figures/thistle.png) |
| tomato | \#ff6347 | ![tomato](figures/tomato.png) |
| turquoise | \#40e0d0 | ![turquoise](figures/turquoise.png) |
| violet | \#ee82ee | ![violet](figures/violet.png) |
| wheat | \#f5deb3 | ![wheat](figures/wheat.png) |
| white | \#ffffff | ![white](figures/white.png) |
| whitesmoke | \#f5f5f5 | ![whitesmoke](figures/whitesmoke.png) |
| yellow | \#ffff00 | ![yellow](figures/yellow.png) |
| yellowgreen | \#9acd32 | ![yellowgreen](figures/yellowgreen.png) |
# button
The **\<button>** component includes capsule, circle, and text buttons.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Not supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| type | string | capsule | No| Type of the **Enter** key on the soft keyboard. The value cannot be dynamically updated. If this attribute is not set, a capsule-like button is displayed. Unlike the capsule button, the capsule-like button allows its corners to be configured using **border-radius**. Available button types are as follows:<br>- **capsule**: capsule button with fillets, background color, and text.<br>- **circle**: circle button that can accommodate icons.<br>- **text**: text button, which displays only text.|
| value | string | - | No| Text value of the button. This attribute is unavailable for circle buttons.|
| icon | string | - | No| Path of the button icon. The supported icon formats are JPG, PNG, and SVG.|
| placement | string | end | No| Position of the button icon in text. This attribute is valid only when **type** is not set. Available values are as follows:<br>- **start**: The button icon is at the beginning of the text.<br>- **end**: The button icon is at the end of the text.<br>- **top**: The button icon is at the top of the text.<br>- **bottom**: The button icon is at the bottom of the text.|
| waiting | boolean | false | No| Whether the button is in waiting state. The value **true** means that the button is in waiting state, and a loading animation is displayed on the left of the text.|
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| text-color | &lt;color&gt; | - | No| Text color of the button.|
| font-size | &lt;length&gt; | - | No| Font size of the button.|
| font-style | string | normal | No| Font style of the button.|
| font-weight | number \| string | normal | No| Font weight of a button. For details, see the **font-weight** style of the **[\<text>](js-service-widget-basic-text.md#styles)** component.|
| font-family | &lt;string&gt; | 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](js-service-widget-common-customizing-font.md) is used for the text.|
| icon-width | &lt;length&gt; | - | No| Width of the internal icon of a circle button. By default, the icon takes up the entire width of the button.<br>This style must be set when the icon uses an SVG image.|
| icon-height | &lt;length&gt; | - | No| Height of the internal icon of a circle button. By default, the icon takes up the entire height of the button.<br>This style must be set when the icon uses an SVG image.|
| radius | &lt;length&gt; | - | No| Radius of a circle button or fillet radius of a capsule button. For a circle button, this style takes precedence over **width** and **height** in the universal styles.|
> **NOTE**
> - For capsule buttons, border-related styles are not supported.
>
> - For circle buttons, text-related styles are not supported.
>
> - For text buttons, the text size is automatically adaptive, and **radius**, **width**, and **height** cannot be set. The **background-color** style is not supported when the background is completely transparent.
## Example
```html
<!-- xxx.hml -->
<div class="div-button">
<button class="button" type="capsule" value="Capsule button"></button>
<button class="button circle" type="circle" icon="common/ic_add_default.png"></button>
<button class="button text" type="text">Text button</button>
</div>
```
```css
/* xxx.css */
.div-button {
flex-direction: column;
align-items: center;
}
.button {
margin-top: 15px;
}
.circle {
background-color: #007dff;
radius: 72px;
icon-width: 72px;
icon-height: 72px;
}
.text {
text-color: red;
font-size: 40px;
font-weight: 900;
font-family: sans-serif;
font-style: normal;
}
```
**4 x 4 widget**
![button](figures/button.jpg)
# calendar
The **\<calendar>** component is used to display the calendar page.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Not supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| -------------- | ------ | ----- | ---- | ---------------------------------------- |
| date | string | Current date | No | Date selected on the current page. The default value is the current date in the format of YYYY-MM-DD, for example, 2019-11-22.|
| cardcalendar | bool | false | No | Whether the current calendar is a widget calendar. |
| startdayofweek | int | 6 | No | Start day of a week on the widget calendar. The default value is Sunday. The value ranges from 0 to 6. |
| offdays | string | 5, 6 | No | Rest days of a week on the widget calendar. The default value is Saturday and Sunday. The value ranges from 0 to 6. |
| calendardata | string | - | Yes | Data to be displayed on the monthly widget calendar. You can pass data of 5*7 or 6*7 days in the JSON format. For details about the **"data"** attribute, see Table 1.|
| showholiday | bool | true | No | Whether to display holiday information. |
**Table 1** "data" attributes of calendardata
| Name | Type | Description |
| -------------- | ------ | --------------------------------------- |
| index | int | Index of the data, indicating the sequence number of the date. |
| day | int | Day. |
| month | int | Month. |
| year | int | Year. |
| isFirstOfLuanr | bool | Whether the day is the first day of the lunar calendar. The first day is underlined. |
| hasSchedule | bool | Whether there is an event scheduled for the day. If there is, a circle is drawn around the date number. |
| markLunarDay | bool | Whether the day is a holiday, on which lunar calendar data is marked in blue. |
| lunarDay | string | Lunar date. |
| lunarMonth | string | Lunar month. |
| dayMark | string | Day mark.<br>- **work**: workday.<br>- **off**: rest day.|
| dayMarkValue | string | Text to be displayed for a workday or a rest day. |
Example of **calendardata**:
```
{
"year":2021,
"month":1,
"data": [{
"index": 0,
"lunarMonth": "11",
"lunarDay": "13",
"year": 2020,
"month ": 12,
"day": 27,
"dayMark": "work",
"dayMarkValue": "On-duty",
"isFirstOfLunar": true,
"hasSchedule": true,
"markLunarDay": true
}, {
"index": 1,
"lunarMonth": "11",
"lunarDay": "14",
"year": 2020,
"month ": 12,
"day": 28,
"dayMark": "work",
"dayMarkValue": "On-duty",
"isFirstOfLunar": true,
"hasSchedule": true,
"markLunarDay": true
}, {
"index": 2,
"lunarMonth": "11",
"lunarDay": "15",
"year": 2020,
"month ": 12,
"day": 29,
"dayMark": "work",
"dayMarkValue": "On-duty",
"isFirstOfLunar": true,
"hasSchedule": true,
"markLunarDay": true
},
...
]
}
```
## Styles
| Name | Type | Default Value | Mandatory | Description |
| ---------------- | ------------- | ---- | ---- | ------- |
| background-color | &lt;color&gt; | - | No | Background color.|
## Events
| Name | Parameter | Description |
| -------------- | ------------ | --------------- |
| selectedchange | changeEvent | A user clicks a date or switches between months.|
| requestdata | requestEvent | A date is requested. |
**Table 2** changeEvent
| Name | Type | Description |
| ------------ | ------ | ------ |
| $event.day | string | Selected day.|
| $event.month | string | Selected month.|
| $event.year | string | Selected year.|
**Table 3** requestEvent
| Name | Type | Description |
| ------------------- | ------ | -------- |
| $event.month | string | Requested month. |
| $event.year | string | Requested year. |
| $event.currentYear | string | Current year.|
| $event.currentMonth | string | Current month.|
## Example
The following examples are not intended as copy-paste-ready. Further customization is required.
```html
<!-- xxx.hml -->
<div class="container">
<calendar class="container_test"
cardcalendar="true"
onselectedchange="clickOneDay"
onrequestdata="messageEventData"
date="{{currentDate}}"
offdays="{{offDays}}"
showholiday="{{showHoliday}}"
startdayofweek="{{startDayOfWeek}}"
calendardata="{{calendarData}}">
</calendar>
</div>
```
```css
/* xxx.css */
.container {
flex-direction:column;
width: 100%;
height: 100%;
align-items:center;
padding-start: 4px;
padding-end: 4px;
}
.container_test {
background-color: white;
}
```
```json
{
"data": {
"currentDate": "",
"offDays": "",
"startDayOfWeek": 6,
"showHoliday": true,
"calendarData": ""
},
"actions": {
"clickOneDay": {
"action": "router",
"bundleName": "com.example.calendar",
"abilityName": "com.example.calendar.MainAbility",
"params": {
"action": "click_month_view_event",
"day": "$event.day",
"month": "$event.month",
"year": "$event.year"
}
},
"messageEventData": {
"action": "message",
"params": {
"month": "$event.month",
"year": "$event.year",
"currentMonth": "$event.currentMonth",
"currentYear": "$event.currentYear"
}
}
}
}
```
# chart
The **\<chart>** component displays line charts, gauge charts, and bar charts.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Not supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| 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**: circle chart of progresses<br>- **loading**: circle chart of loading processes<br>- **rainbow**: circle chart of proportions.|
| options | ChartOptions | - | No | Chart parameters. 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. Data sets for a gauge chart do not take effect. You can set multiple datasets and their background colors. |
| segments | DataSegment \| Array\<DataSegment> | | No | Data structures used by **progress**, **loading**, and **rainbow** charts.<br>The **DataSegment** type is applicable to **progress** and **loading** charts. The **Array\<DataSegment>** type is applicable to **rainbow** charts. A maximum of nine **DataSegment**s are supported.|
| effects | boolean | true | No | Whether to enable the effects for **progress** and **rainbow** charts. |
| animationduration | number | 3000 | No | Animation duration for expanding a **rainbow** chart, in milliseconds. |
**Table 1** ChartOptions
| 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 | ChartAxis | - | No | Data series. Only line charts support this attribute. Available values include:<br>- Line styles, 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 |
| ----------- | ---------------------------------------- | -------- | ---- | -------------------- |
| strokeColor | &lt;color&gt; | \#ff6384 | No | Line color. Only line charts support this attribute. |
| fillColor | &lt;color&gt; | \#ff6384 | No | Fill color. For line charts, this attribute indicates a gradient fill color. |
| data | Array&lt;number&gt; \| Array\<Point&gt; | - | Yes | Data of the drawn line or bar. |
| gradient | boolean | false | No | Whether to display the gradient fill color. Only line charts support this attribute.|
**Table 3** ChartAxis
| Name | Type | Default Value | Mandatory | Description |
| -------- | ------------- | -------- | ---- | ---------------------------------------- |
| min | number | 0 | No | Minimum value of the axis. Negative numbers are not supported. Only line charts support this attribute. |
| max | number | 100 | No | Maximum value of the axis. Negative numbers are not supported. Only line charts support this attribute. |
| axisTick | number | 10 | No | Number of scales displayed on the axis.<br>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 | &lt;color&gt; | \#c0c0c0 | No | Axis color. |
**Table 4** ChartSeries
| Name | Type | Default Value | Mandatory | Description |
| ----------- | -------------- | ---- | ---- | -------------------- |
| lineStyle | ChartLineStyle | - | No | Line style, such as the line width and whether the line is smooth. |
| headPoint | PointStyle | - | No | Style and size of the white point at the start of the line. |
| topPoint | PointStyle | - | No | Style and size of the top point. |
| bottomPoint | PointStyle | - | No | Style and size of the bottom point. |
| loop | ChartLoop | - | No | Whether to start drawing again when the screen is looped.|
**Table 5** ChartLineStyle
| Name | Type | Default Value | Mandatory | Description |
| ------ | -------------- | ----- | ---- | ----- |
| width | &lt;length&gt; | 1px | No | Line width.|
| smooth | boolean | false | No | Whether the line is smooth.|
**Table 6** PointStyle
| Name | Type | Default Value | Mandatory | Description |
| ----------- | -------------- | -------- | ---- | ---------------------------------------- |
| shape | string | circle | No | Shape of the highlight point. Available values are as follows:<br>- circle<br>- square<br>- triangle|
| size | &lt;length&gt; | 5px | No | Size of the highlight point. |
| strokeWidth | &lt;length&gt; | 1px | No | Stroke width. |
| strokeColor | &lt;color&gt; | \#ff0000 | No | Stroke color. |
| fillColor | &lt;color&gt; | \#ff0000 | No | Fill color. |
**Table 7** ChartLoop
| Name | Type | Default Value | Mandatory | Description |
| -------- | -------------- | ----- | ---- | ---------------------------------------- |
| margin | &lt;length&gt; | 1 | No | Number of erased points (horizontal distance between the latest drawn point and the earliest point).<br>You are not advised to use **margin** together with **topPoint**, **bottomPoint**, or **headPoint**. If you do so, there is a possibility that the point is in the erase area and is invisible.|
| gradient | boolean | false | No | Whether to perform gradient erase. |
**Table 8** Point
| 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 of the point. |
| textLocation | string | - | No | Location of the description. Available values are as follows:<br>- **"top"**: The description is above the point.<br>- **"bottom"**: The description is below the point.<br>- **"none"**: The description is not displayed.|
| textColor | &lt;color&gt; | \#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.<br>- **"dashed, 5, 5"**: dashed line with each dash in 5 px and a 5 px space between dashes.<br>- **"solid"**: solid line.|
| lineColor | &lt;color&gt; | \#000000 | No | Line color. If this attribute is not set, the value of **strokeColor** is used. |
**Table 9** DataSegment
| 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 following 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 current data segment. The maximum value is **100**. |
| name | string | - | No | Name of the data segment. |
| Data Segment | Light Theme | Dark Theme |
| ---- | --------------------------- | --------------------------- |
| 0 | Start color: \#f7ce00; end color: \#f99b11| Start color: \#d1a738; end color: \#eb933d|
| 1 | Start color: \#f76223; end color: \#f2400a| Start color: \#e67d50; end color: \#d9542b|
| 2 | Start color: \#f772ac; end color: \#e65392| Start color: \#d5749e; end color: \#d6568d|
| 3 | Start color: \#a575eb; end color: \#a12df7| Start color: \#9973d1; end color: \#5552d9|
| 4 | Start color: \#7b79f7; end color: \#4b48f7| Start color: \#7977d9; end color: \#f99b11|
| 5 | Start color: \#4b8af3; end color: \#007dff| Start color: \#4c81d9; end color: \#217bd9|
| 6 | Start color: \#73c1e6; end color: \#4fb4e3| Start color: \#5ea6d1; end color: \#4895c2|
| 7 | Start color: \#a5d61d; end color: \#69d14f| Start color: \#91c23a; end color: \#70ba5d|
| 8 | Start color: \#a2a2b0; end color: \#8e8e93| Start color: \#8c8c99; end color: \#6b6b76|
For the **gauge** charts, the following attributes are also supported.
| Name | Type | Default Value | Mandatory | Description |
| ------- | ------ | ---- | ---- | ---------------------- |
| percent | number | 0 | No | Percentage of the current value to the total value. The value ranges from 0 to 100.|
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| ------------ | -------------- | -------------------------- | ---- | ---------------------------------------- |
| stroke-width | &lt;length&gt; | 32px (**gauge** charts)<br>24px (**rainbow** charts)| No | Width of the scale bar for **gauge** and **rainbow** charts. |
| start-angle | &lt;deg&gt; | 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 | &lt;deg&gt; | 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 | &lt;length&gt; | - | No | X-coordinate of the scale bar center position for **gauge** charts. This style takes precedence over the **position** universal style and<br>must be used together with **center-y** and **radius**.|
| center-y | &lt;length&gt; | - | No | Y-coordinate of the scale bar center position for **gauge** charts. This style takes precedence over the **position** universal style and<br>must be used together with **center-x** and **radius**.|
| radius | &lt;length&gt; | - | No | Radius of the scale bar for **gauge** charts. This style takes precedence over the **width** and **height** universal style and<br>must be used together with **center-x** and **center-y**.|
| colors | Array | - | No | Colors of ranges on the scale bar for **gauge** charts.<br>For example, **colors: \#ff0000, \#00ff00**.|
| weights | Array | - | No | Weights of ranges on the scale bar for **gauge** charts.<br>For example, **weights: 2, 2**.|
| font-family | Array | - | No | Font style of the description text. You can use a [custom font](js-service-widget-common-customizing-font.md).|
| font-size | &lt;length&gt; | - | No | Font size of the description text. |
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
1. Line chart
```html
<!-- xxx.hml -->
<div class="container">
<stack class="chart-region">
<image class="chart-background" src="common/background.png"></image>
<chart class="chart-data" type="line" ref="linechart" options="{{lineOps}}" datasets="{{lineData}}"></chart>
</stack>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
}
.chart-region {
height: 400px;
width: 700px;
}
.chart-background {
object-fit: fill;
}
.chart-data {
width: 700px;
height: 600px;
}
```
```json
// xxx.json
{
"data": {
"lineData": [
{
"strokeColor": "#0081ff",
"fillColor": "#cce5ff",
"data": [
763,
550,
551,
554,
731,
654,
525,
696,
595,
628,
791,
505,
613,
575,
475,
553,
491,
680,
657,
716
],
"gradient": true
}
],
"lineOps": {
"xAxis": {
"min": 0,
"max": 20,
"display": false
},
"yAxis": {
"min": 0,
"max": 1000,
"display": false
},
"series": {
"lineStyle": {
"width": "5px",
"smooth": true
},
"headPoint": {
"shape": "circle",
"size": 20,
"strokeWidth": 5,
"fillColor": "#ffffff",
"strokeColor": "#007aff",
"display": true
},
"loop": {
"margin": 2,
"gradient": true
}
}
}
}
}
```
**4 x 4 widget**
![en-us_image_0000001185652902](figures/en-us_image_0000001185652902.png)
2. Bar chart
```html
<!-- xxx.hml -->
<div class="container">
<stack class="data-region">
<image class="data-background" src="common/background.png"></image>
<chart class="data-bar" type="bar" id="bar-chart" options="{{barOps}}" datasets="{{barData}}"></chart>
</stack>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
}
.data-region {
height: 400px;
width: 700px;
}
.data-background {
object-fit: fill;
}
.data-bar {
width: 700px;
height: 400px;
}
```
```json
{
"data": {
"barData": [
{
"fillColor": "#f07826",
"data": [763, 550, 551, 554, 731, 654, 525, 696, 595, 628]
},
{
"fillColor": "#cce5ff",
"data": [535, 776, 615, 444, 694, 785, 677, 609, 562, 410]
},
{
"fillColor": "#ff88bb",
"data": [673, 500, 574, 483, 702, 583, 437, 506, 693, 657]
}
],
"barOps": {
"xAxis": {
"min": 0,
"max": 20,
"display": false,
"axisTick": 10
},
"yAxis": {
"min": 0,
"max": 1000,
"display": false
}
}
}
}
```
**4 x 4 widget**
![barchart](figures/barchart.PNG)
3. Gauge chart
```html
<!-- xxx.hml -->
<div class="container">
<div class="gauge-region">
<chart class="data-gauge" type="gauge" percent = "50"></chart>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
}
.gauge-region {
height: 400px;
width: 400px;
}
.data-gauge {
colors: #83f115, #fd3636, #3bf8ff;
weights: 4, 2, 1;
}
```
**4 x 4 widget**
![gauge](figures/gauge.PNG)
# clock
The **\<clock>** component provides a clock face.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Not supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| ----------- | ----------- | ---- | ---- | ---------------------------------------- |
| clockconfig | ClockConfig | - | Yes | Image resources and styles used by this **\<clock>** component, including one set for the daytime (6:00 to 18:00) and one set for the nighttime (18:00 to 6:00 of the next day).<br>Each set of resources contains four images for the clock face, hour hand, minute hand, and second hand, respectively. Each set of styles is used for specifying number colors for the daytime and nighttime.<br>This attribute is mandatory for the daytime. If you do not set this attribute for the nighttime, the daytime images are reused at the nighttime.<br>Object members cannot be dynamically updated. However, You can dynamically update the object.<br>You are advised to use PNG images.<br>SVG images are not supported.|
| showdigit | boolean | true | No | Whether to draw clock face numbers based on **clockconfig**.<br>If you set this attribute to **true**, ensure that **digitRadiusRatio** and **digitSizeRatio** parameters of **clockconfig** match the clock face.<br>The numbers generated by the **\<clock>** component support multiple number formats in different locales.|
| hourswest | number | - | No | Time offset of the clock to the Coordinated Universal Time (UTC). The local time zone is UTC minus **hourswest**.<br>The value range is [-12, 12]. For example, the value **-8** means UTC+8. If this parameter is not set, the current system time zone is used.|
**Table 1** ClockConfig
| Name | Type | Default Value | Mandatory | Description |
| ---------------- | -------------- | --------------- | ---- | ---------------------------------------- |
| face | &lt;string&gt; | - | Yes | Path of clock face images used in the daytime.<br>The clock face resources must be square images that contain the clock scale, and the clock face area must be an inscribed circle of the image or a concentric circle of the inscribed circle. If the clock face area is a concentric circle of the inscribed circle, you need to change the **digitRadiusRatio** and **digitSizeRatio** values accordingly.|
| hourHand | &lt;string&gt; | - | Yes | Path of hour hand images used in the daytime.<br>- The height of the hour hand images must be the same as that of the clock face images.<br>- You are advised to set the aspect ratio of the hour hand images to **0.062**.<br>- The rotation center of the hour hand must be the same as the center (diagonal intersection point) of the hour hand images.<br>- To specify the hour hand resources for the nighttime, set **hourHandNight**.|
| minuteHand | &lt;string&gt; | - | Yes | Path of minute hand images used in the daytime.<br>- The height of the minute hand images must be the same as that of the clock face images.<br>- You are advised to set the aspect ratio of the minute hand images to **0.062**.<br>- The rotation center of the minute hand must be the same as the center (diagonal intersection point) of the minute hand images.<br>- To specify the minute hand resources for the nighttime, set **minuteHandNight**.|
| secondHand | &lt;string&gt; | - | Yes | Path of second hand images used in the daytime.<br>- The height of the second hand images must be the same as that of the clock face images.<br>- You are advised to set the aspect ratio of the second hand images to **0.062**.<br>- The rotation center of the second hand must be the same as the center (diagonal intersection point) of the second hand images.<br>- To specify the second hand resources for the nighttime, set **secondHandNightSrc**.|
| digitColor | &lt;color&gt; | \#FF000000 | No | Text color on the clock face during the daytime (6:00 to 18:00). |
| digitColorNight | &lt;color&gt; | Same as that of **digitColor**| No | Text color on the clock face during the nighttime (18:00 to 06:00 of the following day).<br>- If this attribute is not set, the value of **digitColor** is used as the value of **digitColorNight**.<br>In this case, you should ensure the text color of the nighttime clock face matches the color of the nighttime clock face images (stored in **faceNight**).|
| faceNight | &lt;string&gt; | - | No | Path of clock face images used in the nighttime.<br>If this parameter is not set, the path of clock face images for the daytime is used as the value of this parameter.|
| hourHandNight | &lt;string&gt; | - | No | Path of hour hand images used in the nighttime.<br>If this parameter is not set, the path of hour hand images for the daytime is used as the value of this parameter.|
| minuteHandNight | &lt;string&gt; | - | No | Path of minute hand images used in the nighttime.<br>If this parameter is not set, the path of minute hand images for the daytime is used as the value of this parameter.|
| secondHandNight | &lt;string&gt; | - | No | Path of second hand images used in the nighttime.<br>If this parameter is not set, the path of second hand images for the daytime is used as the value of this parameter.|
| digitRadiusRatio | number | 0.7 | No | Distance between the center of the clock face numbers and the center of the clock face circle/Half of the side length of the clock face image.<br>- The value range is (0, 1].<br>- This parameter is used to calculate the distance between the numbers on the clock face and the center of the clock face circle.<br>- This parameter ensures that the same set of clock face images have the same relative position in components of different sizes. You do not need to change the position for components of different sizes.<br>- If this parameter is set to **1**, the numbers may exceed the clock face area. In this case, you should change the **digitRadiusRatio** value based on the clock face size.|
| digitSizeRatio | number | 0.08 | No | Font size of the watch face numbers/Side length of the watch face<br>- The value range is (0, 0.142].<br>- This parameter is used to calculate the font size of clock face numbers relative to the size of the clock face.<br>- This parameter ensures that the same set of clock face images have the same relative size in components of different sizes. You do not need to change the font size for components of different sizes.|
![clock](figures/clock.png)
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| ----------- | -------------- | ---------- | ---- | ---------------------------------------- |
| font-family | &lt;string&gt; | sans-serif | No | Font family used for clock face numbers, 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 a custom font style is used for the text.|
> **NOTE**
>
> The **\<clock>** component keeps the aspect ratio of the display area to **1**. The side length of the final square display area is **min(width, height)**. The square display area is centered in the component (**width** x **height**).
## Events
| Name | Parameter | Description |
| ---- | ------------------- | --------- |
| hour | {hour: number} | Triggered on the hour.|
## Example
```html
<!-- xxx.hml -->
<div class="container">
<div class="row">
<clock class="clk" style="font-family:Courier;" hourswest="-8" clockconfig="{{clockconfig}}">
</clock>
<clock class="clk" style="font-family:Courier;" hourswest="4" clockconfig="{{clockconfig}}">
</clock>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction:column;
align-items:center;
}
.clk {
width:350px;
height:350px;
}
.row {
flex-direction:row;
align-items:center;
justify-content: space-around;
border-radius: 40px;
padding-top: 20px;
padding-bottom: 20px;
background-color: #4169E1;
}
```
```json
{
"data": {
"clockconfig": {
"digitRadiusRatio": 0.7,
"digitSizeRatio": 0.08,
"face": "common/clock_widget.png",
"hourHand": "common/clock_widget_hour.png",
"minuteHand": "common/clock_widget_minute.png",
"secondHand": "common/clock_widget_second.png",
"faceNight": "common/black_clock_widget.png",
"hourHandNight": "common/black_clock_widget_hour.png",
"minuteHandNight": "common/black_clock_widget_minute.png",
"digitColor": "#000000",
"digitColorNight": "#FFFFFF"
}
}
}
```
**2 x 4 widget**
![clockshow](figures/clockshow.png)
# divider
The **\<Divider>** component is used to separate content blocks and content elements. It can be used in a list or for UI layout.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| vertical | boolean | false | No| Whether to use the vertical divider. The default value is **false**, indicating that the horizontal divider is used.|
## Styles
Only the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| margin | &lt;length&gt; | 0 | No| Shorthand attribute to set the margin for all sides in a declaration. The attribute can have one to four values.|
| margin-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | No| Shorthand attribute of the length type to set left, top, right, and bottom margins attributes. Its unit is px and default value is **0**.|
| color | &lt;color&gt; | - | No| Color of the divider.|
| stroke-width | &lt;length&gt; | 1 | No| Stroke width of the divider.|
| display | string | flex | No| Type of the bounding box generated by the divider. The value can be **flex** or **none**. The default value is **flex**.|
| visibility | string | visible | No| Whether to display the divider. Invisible dividers also occupy space. **visible** indicates that the divider is displayed, and **hidden** indicates that the divider is not displayed.|
| line-cap | string | butt | No| Cap style of the divider. The default value is **"butt"**. Available values are as follows:<br>- **"butt"**: The ends of the divider are squared off.<br>- **"round"**: A rounded cap is added to each end of the divider.<br>- **"square"**: A square cap is added to each end of the divider.<br>If the value is **"round"** or **"square"**, the divider length increases by the stroke width.|
| flex | number | - | No| How to divide available space of the parent component for each divider. This is a shorthand attribute to set the **flex-grow** attribute.<br>This attribute takes effect only when the parent component is **\<div>**, **\<list-item>**, or **\<tabs>**.|
| flex-grow | number | 0 | No| How much the divider will grow. The value specifies allocation of the remaining space on the main axis of the parent component. Size of available space = Container size - Total size of all child components. The value **0** indicates that the child component does not grow.<br>This attribute takes effect only when the parent component is **\<div>**, **\<list-item>**, or **\<tabs>**.|
| flex-shrink | number | 1 | No| How much the divider will shrink. The shrink occurs only when the sum of default element widths is greater than that of the parent component. The value **0** indicates that the divider does not shrink.<br>This attribute takes effect only when the parent component is **\<div>**, **\<list-item>**, or **\<tabs>**.|
| flex-basis | &lt;length&gt; | - | No| Initial length of the divider on the main axis.<br>This attribute takes effect only when the parent component is **\<div>**, **\<list-item>**, or **\<tabs>**.|
## Events
Not supported
## Example
```html
<!-- xxx.hml -->
<div class="container">
<div class="content">
<divider class="divider" vertical="false"></divider>
</div>
</div>
```
```css
/* xxx.css */
.container {
margin: 20px;
flex-direction:column;
width:100%;
height:100%;
align-items:center;
}
.content{
width:80%;
height:40%;
margin-top:100px;
border:1px solid #000000;
align-items: center;
justify-content: center;
flex-direction:column;
}
.divider {
margin: 10px;
color: #ff0000ff;
stroke-width: 3px;
line-cap: round;
}
```
**4 x 4 widget**
![divider](figures/divider.png)
# image
The **\<image>** component is used to render and display images.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Not supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| src | string | - | No| Image path.<br>- The local path is supported. Supported formats are as follows: PNG, JPG, BMP, SVG, and GIF.<br>- The path to the in-memory image is also supported in the scheme format of **memory://**.|
| alt | string | - | No| Placeholder image displayed during image loading.|
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| object-fit | string | cover | No| Image scale type. For details about available values, see **object-fit**. This style is not supported for SVG images.|
| 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.|
**Table 1** object-fit
| Type| Description|
| -------- | -------- |
| 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, in the size equal to or smaller than the original size.|
> **NOTE**
>
> When using an SVG image, note that:
>
> - The SVG image will not be drawn if the length or width of the parent component is infinity. Therefore, you are advised to set the length and width for the **\<image>** component.
>
> - 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:
>
> - 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.
>
> - If the **\<image>** component is big enough to afford the SVG image, the SVG image is displayed in the upper left corner of the component.
## Events
| Name| Parameter| Description|
| -------- | -------- | -------- |
| click | - | Triggered when the component is clicked.|
| complete | - | Triggered when the image is successfully loaded.|
| error | - | Triggered when an exception occurs during image loading.|
## Example
```html
<!-- xxx.hml -->
<stack class="content">
<image src="/common/bg3.jpg" class="img"></image>
</stack>
```
```css
/* xxx.css */
.img{
object-fit: contain
}
```
**4 x 4 widget**
![image.jpg](figures/image.jpg)
# input
The **\<input>** component provides a radio button to receive user input.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| ------- | ------- | ----- | ---- | ---------------------------------------- |
| type | string | radio | Yes | Type of the **\<input>** component. Currently, only the radio button is supported.<br>- **radio**: a radio button that allows users to select one from multiple others with the same name.|
| checked | boolean | false | No | Whether the component is checked or not. |
| name | string | - | No | Name of the **\<input>** component. |
| value | string | - | No | Value of the **<input>** component. When **type** is **radio**, this attribute is mandatory and the value must be unique for radio buttons with the same name.|
## Styles
The [universal styles](js-service-widget-common-styles.md) are supported.
## Events
| Name | Parameter | Description |
| ------ | ------------------ | ---------------------------------------- |
| change | $event.checkedItem | Triggered when the **checked** status of a radio button changes. This event returns the value of the selected **\<input>** component.|
| click | - | Triggered when the component is clicked. |
## Example
```html
<!-- xxx.hml -->
<div class="content">
<input type="radio" checked='true' name="radioSample" value="radio1" onchange="onRadioChange"></input>
<input type="radio" checked='false' name="radioSample" value="radio2" onchange="onRadioChange"></input>
<input type="radio" checked='false' name="radioSample" value="radio3" onchange="onRadioChange"></input>
</div>
```
```css
/* xxx.css */
.content{
width: 100%;
height: 200px;
justify-content: center;
align-items: center;
}
```
```json
{
"actions": {
"onRadioChange":{
"action": "message",
"params": {
"checkedRadio": "$event.checkedItem"
}
}
}
}
```
**4 x 4 widget**
![input](figures/input.gif)
# progress
The **\<Progress>** component is used to provide a progress bar that displays the progress of content loading or an operation.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Not supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| type | string | horizontal | No| Type of the progress bar, which cannot be changed dynamically. Available values are as follows:<br>- **horizontal**: linear progress bar.<br>- **circular**: loading progress bar.<br>- **ring**: ring progress bar.<br>- **scale-ring**: ring progress bar with a scale.<br>- **arc**: arc progress bar.<br>- **eclipse**: eclipse progress bar.|
Different types of progress bars support different attributes.
- When the type is **horizontal**, **ring**, or **scale-ring**, the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | No| Current progress. The value ranges from 0 to 100.|
| secondarypercent(Rich) | number | 0 | No| Secondary progress. The value ranges from 0 to 100.|
- When the type is **ring** or **scale-ring**, the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| clockwise | boolean | true | No| Whether the ring progress bar moves in a clockwise direction.|
- When the type is **arc**, the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | No| Current progress. The value ranges from 0 to 100.|
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
When the type is **horizontal**, the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#ff007dff | No| Color of the progress bar.|
| stroke-width | &lt;length&gt; | 4px | No| Stroke width of the progress bar.|
| background-color | &lt;color&gt; | - | No| Background color of the progress bar.|
| secondary-color | &lt;color&gt; | - | No| Color of the secondary progress bar.|
When the type is **circular**, the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | No| Color of the dot on the loading progress bar.|
When the type is **ring** or **scale-ring**, the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt;&nbsp;\|&nbsp;&lt;linear-gradient&gt; | - | No| Color of the ring progress bar. The **ring** type supports the linear gradient<br>defined by two colors, for example, **color&nbsp;=&nbsp;linear-gradient(\#ff0000,&nbsp;\#00ff00)**.|
| background-color | &lt;color&gt; | - | No| Background color of the ring progress bar.|
| secondary-color | &lt;color&gt; | - | No| Color of the secondary ring progress bar.|
| stroke-width | &lt;length&gt; | 10px | No| Width of the ring progress bar.|
| scale-width | &lt;length&gt; | - | No| Scale thickness of the ring progress bar with a scale. This style takes effect only when the type is **scale-ring**.|
| scale-number | number | 120 | No| Number of scales of the ring progress bar with a scale. This style takes effect only when the type is **scale-ring**.|
When the type is **arc**, the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | No| Color of the arc progress bar.|
| background-color | &lt;color&gt; | - | No| Background color of the arc progress bar.|
| stroke-width | &lt;length&gt; | - | No| Stroke width of the arc progress bar.<br>A larger width value means that the progress bar is closer to the center of the circle. The width is always within the radius range.|
| start-angle | &lt;deg&gt; | 240 | No| Start angle of the arc progress bar, which starts from the direction of zero o'clock. The value ranges from 0 to 360 degrees (clockwise).|
| total-angle | &lt;deg&gt; | 240 | No| Total length of the arc progress bar. The value ranges from –360 to 360. A negative number indicates anticlockwise.|
| center-x | &lt;length&gt; | - | No| Center of the arc progress bar (with the upper left corner of this widget as the coordinate origin). This style must be used together with **center-y** and **radius**.|
| center-y | &lt;length&gt; | - | No| Center of the arc progress bar (with the upper left corner of this widget as the coordinate origin). This style must be used together with **center-x** and **radius**.|
| radius | &lt;length&gt; | - | No| Radius of the arc progress bar. This style must be used together with **center-x** and **center-y**.|
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
```html
<!--xxx.hml -->
<div class="container">
<progress class="min-progress" type="scale-ring" percent= "10" secondarypercent="50"></progress>
<progress class="min-progress" type="horizontal" percent= "10" secondarypercent="50"></progress>
<progress class="min-progress" type="arc" percent= "10"></progress>
<progress class="min-progress" type="ring" percent= "10" secondarypercent="50"></progress>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
height: 100%;
width: 100%;
align-items: center;
}
.min-progress {
width: 300px;
height: 300px;
}
```
**4 x 4 widget**
![progress](figures/progress.png)
# span
The **\<span>** component is a child component of [\<text>](js-service-widget-basic-text.md) and is used as a text modifier.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
The child component **[\<span>](js-service-widget-basic-span.md)** is supported.
## attributes
The [universal attributes](js-service-widget-common-attributes.md) are supported.
## Styles
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | No| Font color of the modified text.|
| font-size | &lt;length&gt; | 30px | No| Font size of the modified text.|
| font-style | string | normal | No| Font style of the modified text. For details, see **font-style** of the [**\<text>**](js-service-widget-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>**](js-service-widget-basic-text.md##styles) component.|
| text-decoration | string | none | No| Text decoration of the modified text. For details, see **text-decoration** of the [**\<text>**](js-service-widget-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](js-service-widget-common-customizing-font.md) is used for the text.|
## Events
Not supported
## Example
For details, see [Example of the \<text> component](js-service-widget-basic-text.md#example).
# text
The **\<text>** component is used to display a piece of textual information.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
The child component **[\<span>](js-service-widget-basic-span.md)** is supported.
## Attributes
The [universal attributes](js-service-widget-common-attributes.md) are supported.
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | - | No| Font color.|
| font-size | &lt;length&gt; | 30px | No| Font size.|
| letter-spacing | &lt;length&gt; | 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 | 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 | &lt;length&gt; | 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<br><br>| 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](js-service-widget-common-customizing-font.md) is used for the text.|
| max-lines | number | - | No| Maximum number of lines in the text.|
| min-font-size | &lt;length&gt; | - | 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 | &lt;length&gt; | - | 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 | &lt;length&gt; | 1px | No| Step for dynamically adjusting the font size in the text. The minimum and maximum font sizes must be set.|
| prefer-font-sizes | &lt;array&gt; | - | 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 text cannot be displayed in full in the maximum number of lines, **text-overflow** is used to clip 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 | 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.|
> **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.
>
> - 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
The [universal events](js-service-widget-common-events.md) are supported.
## Example
```html
<div class="container">
<text class="line_height">
<span>This is the text for which the line height is set. </span>
</text>
<text class="letter_spacing">This is the text for which the character spacing is set. </text>
<text class="font_style">This is the text that is set to italics. </text>
<text class="text_decoration_style">This is the underlined text. </text>
<text class="text_over_flow">If the text is too long, the text can be clipped. </text>
</div>
```
```css
.container{
flex-direction: column;
width: 100%;
height: 100%;
margin-top: 10px;
margin-left: 30px;
}
.line_height{
font-size: 20px;
line-height: 40px;
}
.letter_spacing{
font-size: 20px;
letter-spacing: 5px;
}
.font_style{
font-size: 20px;
font-style: italic;
}
.text_decoration_style{
font-size: 20px;
text-decoration: underline;
text-decoration-color: red;
}
.text_over_flow{
font-size: 20px;
width: 40%;
max-lines: 1;
text-overflow: ellipsis;
}
```
**4 x 4 widget**
![progress](figures/text.png)
# Accessibility
You can set accessibility attributes and events for components.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Attributes
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| accessibilitygroup | boolean | false | Accessibility group. If this attribute is set to **true**, the component and all its child components form an entire selectable component, and the accessibility service will no longer be available for the content of its child components.|
| accessibilitytext | string | - | Accessibility text. If a component does not contain text information, it will not be read when the component is selected by the screen reader. In this case, the screen reader user cannot know which component is selected. To solve this problem, you can set this attribute for components without text information. When the component is selected by the screen reader, the specified accessibility text will be read, informing the user which component is selected. If a component with this attribute set contains text information, only the accessibility text will be read.|
| accessibilitydescription | string | - | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. You can set a detailed description text for the attribute of the component to help users understand the operation to be performed. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.|
| accessibilityimportance | string | auto | Accessibility importance, which is used to decide whether a component can be identified by the accessibility service. The value can be **auto**, **yes**, **no**, or **no-hide-descendants**. The last value forces the screen reader to ignore the current component and all its subcomponents.<br>**yes**: The current component is selectable for the accessibility service.<br>**no**: The current component cannot be selected for the barrier-free auxiliary service. |
- accessibilitygroup
```html
<div accessibilitygroup="true">
<text>text1</text>
<text>text2</text>
</div>
```
- accessibilitytext
```html
<image src="common/image/barrierfree.jpg" accessibilitytext=" This is a landscape image. "></image>
```
- accessibilitydescription
```html
<button accessibilitydescription="Click to open a dialog box." onclick="DialogShow">Show dialog</button>
```
- accessibilityimportance
In the following **accessibilityImportance** example, **\<div>** and **\<text>** are not selected by the accessibility service. To select a component that is unselected by default, add **accessibilityimportance="yes"** to the component.
```html
<div accessibilityimportance="no-hide-descendants">
<text>text</text>
</div>
```
## Accessibility Events
| Name| Parameter| Description|
| -------- | -------- | -------- |
| accessibility | AbilityEvent | Event dispatched by the accessibility service.|
**Table 1** AbilityEvent attributes
| Name| Type| Description|
| -------- | -------- | -------- |
| eventType | number | Event type.<br>- **0**: custom event.<br>- **1**: accessibility focus.<br>- **2**: clear accessibility focus<br>For non-focus-related events dispatched by the accessibility system, the **eventType** value is **0**. For onfocus events dispatched by the accessibility system, the **eventType** value is **1**. For onblur events dispatched by the accessibility system, the **eventType** value is **2**. |
| param | Object | Parameter that accessibility applications need to pass when sending custom events. |
# Atomic Layout
The atomic layout implements adaptive layout for screens of different sizes and types. Designers can use the atomic layout to define adaptive rules for components on UIs of different widgets. Developers can use the atomic layout to implement the adaptive UI features matching the design effect for a variety of screens.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Hiding Components
You can set priority flags for a flex layout that does not support cross-row display to define the display priorities for components in the horizontal or vertical direction. The components are hidden based on available space of the container.
| Style | Type | Default Value | Description |
| ------------- | ------ | ---- | ---------------------------------------- |
| display-index | number | 0 | When the space of a container on the flex main axis is insufficient to display all content, the child components are hidden in ascending order of their **display-index** values. Child components with the same **display-index** value are hidden at the same time. The default value of this style is **0**, indicating that the child component is hidden. This style is applicable to child components in a container that supports flex layout, such as **\<div>**. |
## Proportion
In a flex layout that does not support cross-row display, components with the proportion style configured are always arranged with the set proportions in the container.
| Style | Type | Default Value | Description |
| ----------- | ------ | ---- | ---------------------------------------- |
| flex-weight | number | - | Size weight of the component on the flex main axis. Component size = Container main axis size x flex-weight / Sum of all component size weights. This style takes effect only when it is set for all components in the container.|
## Fixed Ratio
A component with fixed ratio can be scaled up and down while retaining its aspect ratio.
| Style | Type | Default Value | Description |
| ------------ | ------ | ---- | ---------------------------------------- |
| aspect-ratio | number | - | Aspect ratio of the component. The value is a floating-point value greater than 0.<br>The value is subjective to the upper and lower limits of the component size.<br>In a flex layout, the main axis size is adjusted first, based on which the cross axis size is adjusted.|
# Universal Attributes
> **NOTE**
>
>The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Common Attributes
Common attributes are used to set component identities and appearance.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | No| Unique ID of the component.|
| style | string | - | No| Style declaration of the component.|
| class | string | - | No| Style class of the component, which is used to refer to a style table.|
| ref | string | - | No| Reference information of child elements or child components, which is registered with the parent component on **$refs**.|
| disabled | boolean | false | No| Whether the component is disabled. If it is disabled, it cannot respond to user interactions.|
| dir | string | auto | No| Component layout mode. Available values are as follows:<br>- **rtl**: right-to-left layout.<br>- **ltr**: left-to-right layout.<br>- **auto**: follows the system language environment.|
## Rendering Attributes
Rendering attributes are used to set whether a component is rendered.
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| for | Array | - | Expands the component based on the configured data list.|
| if | boolean | - | Whether the component is added or removed.|
| show | boolean | - | Whether the component is displayed or hidden.|
> **NOTE**
>
> Do not set styles in attribute fields.
# Custom Font Styles
**font-face** is used to define the font style. You can define **font-face** in **style** to specify a font name and resource for your application and then reference this font from **font-family**.
The custom font can be loaded from the font file in a project or a network font file.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
>
> The font format can be .ttf or .otf.
## Defining @font-face
```css
@font-face {
font-family: HWfont;
src: url('/common/HWfont.ttf');
}
```
**font-family**: name of the custom font.
**src**: source of the custom font, which can be a font file in the project or an online font file.
- Font file in the project: Specify the absolute path of the font file in the project through **url**. For details, see [File Organization](js-service-widget-file.md).
- Online font file: Specify the address of the online font through **url**.
- You can set only one **src** attribute.
## Using font-face
You can set **font-face** in **style** and specify the name of the **font-face** using **font-family**. The code snippet is as follows:
- Page layout
```html
<div>
<text class="demo-text">Test the custom font.</text>
</div>
```
- Page style
```css
@font-face {
font-family: HWfont;
src: url("/common/HWfont.ttf");
}
.demo-text {
font-family: HWfont;
}
```
# Universal Events
Unlike private events, universal events can be bound to most components. (If a keyup event needs to be triggered to respond to the input of carriage return and space characters on the keyboard, add the click event to the outermost component.)
> **NOTE**
>
>The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
| Name| Parameter| Description|
| -------- | -------- | -------- |
| click | - | Triggered when a component is clicked.|
# Gradient Styles
Gradient styles are commonly supported and can be set in the **style** attribute or a **.css** file. Gradients enable smooth transition between two or more specified colors.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
The development framework supports two gradient styles: linear gradient and repeating linear gradient.
## Linear Gradient/Repeating Linear Gradient
To use the gradient style, you must specify the transition direction and transition color.
### Transition Direction
You can specify the transition direction through **direction** or **angle**.
- **direction**: gradient by direction.
- **angle**: gradient by angle.
```css
background: linear-gradient(direction/angle, color, color, ...);
background: repeating-linear-gradient(direction/angle, color, color, ...);
```
### Transition Color
The color can be specified in any of the following formats: \#ff0000, \#ffff0000, rgb(255, 0, 0), and rgba(255, 0, 0, 1). At least two colors must be specified.
- Parameters
| Name | Type | Default Value | Mandatory | Description |
| --------- | ---------------------------------------- | ---------------------------- | ---- | ---------------------------------------- |
| direction | to &lt;side-or-corner&gt; &lt;side-or-corner&gt; = [left \| right] \|\| [top \| bottom] | to bottom (gradient from top to bottom)| No | Transition direction. For example, **to left** (gradient from right to left) or **to bottom right** (gradient from upper left corner to lower right corner).|
| angle | &lt;deg&gt; | 180deg | No | Transition direction, which is the angle between the gradient line and the y-axis (in the clockwise direction), with the geometric center of the element being the origin of coordinates and the horizontal axis being the x-axis.|
| color | &lt;color&gt; [&lt;length&gt;\|&lt;percentage&gt;] | - | Yes | Colors among which smooth transitions are rendered. |
- Example
1. Gradient from top to bottom (default)
```css
#gradient {
height: 300px;
width: 600px;
/* Gradient starts from red at the top to green at the bottom. */
background: linear-gradient(red, #00ff00);
}
```
![111](figures/111.PNG)
2. Gradient at an angle of 45°
```css
/* Gradient at an angle of 45°, changing from red to green */
background: linear-gradient(45deg, rgb(255, 0, 0),rgb(0, 255, 0));
```
![222](figures/222.PNG)
3. Gradient from left to right
```css
/* Gradient from left to right, which is available in the 270 px width between the left 90 px and the left 360 px (600*0.6) */
background: linear-gradient(to right, rgb(255, 0, 0) 90px, rgb(0, 255, 0) 60%);
```
![333](figures/333.PNG)
4. Repeating gradient
```css
/* Repeating gradient from left to right, the area of which is 30 px (60 – 30) and the opacity is 0.5 */
background: repeating-linear-gradient(to right, rgba(255, 255, 0, 1) 30vp,rgba(0, 0, 255, .5) 60vp);
```
![444](figures/444.PNG)
# Media Query
Media queries are widely used on mobile devices. You can use them to modify the application style based on the device type or specific features and device parameters (such as the screen resolution). Specifically, media queries allow you to:
1. Design a layout style based on the device and app attributes.
2. Update the page layout to adapt to dynamic screen changes (for example, screen splitting or switching between landscape and portrait modes).
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
>
> The **media** attribute uses the actual size, physical pixel, and screen resolution of the device by default. Do not confuse them with the configuration based on basic screen width 720 px.
## CSS Syntax Rules
Use **\@media** to import query statements. The rule is as follows:
```css
@media [media-type] [and|not|only] [(media-feature)] {
CSS-Code;
}
```
Example:
\@media screen and (round-screen: true) { … } // The condition is met when the device screen is round.
\@media (max-height: 800) { … } // Range query. CSS level 3 is used.
\@media (height &lt;= 800) { ... } // Range query. CSS level 4 is used, and the statement is equivalent to that of CSS level 3.
\@media screen and (device-type: tv) or (resolution &lt; 2) { … } // Multi-condition query that contains the media type and multiple media features.
## Referencing Resources on a Page
Use **@import** to import a media query. The rule is as follows:
```
@import url [media-type] [and|not|only] [(media-feature)];
```
Example:
```
@import '../common/style.css' screen and (min-width: 600) and (max-width: 1200);
```
## Media Type
| Type| Description|
| -------- | -------- |
| screen | Media query based on screen-related parameters.|
## Media Logical Operation
Media logical operators (and, or, not, and only) are used to implement complex media query. They can also be combined using comma (,). The following table describes the operators.
**Table 1** Media logical operators
| Type| Description|
| -------- | -------- |
| and | The **and** operator is used to combine multiple media features into one media query, in a logical AND operation. The query is valid only when all media features are true. It can also combine media types and media functions.<br>For example, **screen and (device-type: wearable) and (max-height: 600) ** indicates that the query is valid when the device type is wearable and the maximum height of the application is 600 pixel units.|
| not | The **not** operator is used to perform a logical negation for a media query. **true** is returned if the query condition is not met. Otherwise, **false** is returned. In a media query list, logical negation is performed only for the media query using the **not** operator.<br>For example, **not screen and (min-height: 50) and (max-height: 600) ** indicates that the query is valid when the height of the application is less than 50 pixel units or greater than 600 pixel units.<br>You must specify the media type when using the **not** operator.|
| only | The **only** operator applies the selected style only when the entire expression is matched. It can be used to prevent ambiguity on browsers of earlier versions. The statements that contain both media types and media features produce ambiguity when they are received by some browsers of earlier versions. For example:<br>screen and (min-height: 50)<br>The browsers of earlier versions would mislead this sentence into screen, causing the fact that the specified style is applied when only the media type is matched. In this case, the **only** operator can be used to avoid this problem.<br>You must specify the media type when using the **only** operator.|
| ,(comma) | The **or** operator is used to combine multiple media features into one media query, in a logical OR operation. The query is valid if a media feature is true. The effect of a comma operator is equivalent to that of the **or** operator.<br>For example, **screen and (min-height: 1000), (round-screen: true) ** indicates that the query is valid when the minimum height of the application is 1000 pixel units or the device screen is round.|
| or | The **or** operator is used to combine multiple media features into one media query, in a logical OR operation. The query is valid if a media feature is true.<br>For example, **screen and (max-height: 1000) or (round-screen: true)** indicates that the query is valid when the maximum height of the application is 1000 pixel units or the device screen is round.|
At MediaQuery Level 4, range query is imported so that you can use the operators including &lt;=, &gt;=, &lt;, and &gt; besides the max- and min-operators.
**Table 2** Logical operators for range query
| Type| Description|
| -------- | -------- |
| &lt;= | Less than or equal to, for example, **screen and (height &lt;= 50)**.|
| &gt;= | Greater than or equal to, for example, **screen and (height &gt;= 600)**.|
| &lt; | Less than, for example, **screen and (height &lt; 50)**.|
| &gt; | Greater than, for example, **screen and (height &gt; 600)**.|
## Media Features
| Type| Description|
| -------- | -------- |
| height | Height of the display area on the application page.|
| min-height | Minimum height of the display area on the application page.|
| max-height | Maximum height of the display area on the application page.|
| width | Width of the display area on the application page.|
| min-width | Minimum width of the display area on the application page.|
| max-width | Maximum width of the display area on the application page.|
| resolution | Resolution of the device. The unit can be dpi, dppx, or dpcm. Where:<br>- **dpi** indicates the number of physical pixels per inch. 1 dpi ≈ 0.39 dpcm.<br>- **dpcm** indicates the number of physical pixels per centimeter. 1 dpcm ≈ 2.54 dpi.<br>- **dppx** indicates the number of physical pixels in each pixel. (This unit is calculated based on this formula: 96 px = 1 inch, which is different from the calculation method of the px unit on the page.) 1 dppx = 96 dpi.|
| min-resolution | Minimum device resolution.|
| max-resolution | Maximum device resolution.|
| orientation | Screen orientation.<br>Options are as follows:<br>- orientation: portrait<br>- orientation: landscape|
| aspect-ratio | Ratio of the width to the height of the display area on the application page.<br>Example: **aspect-ratio:1/2**|
| min-aspect-ratio | Minimum ratio of the width to the height of the display area on the application page.|
| max-aspect-ratio | Maximum ratio of the width to the height of the display area on the application page.|
| device-height | Height of the device.|
| min-device-height | Minimum height of the device.|
| max-device-height | Maximum height of the device.|
| device-width | Width of the device.|
| min-device-width | Minimum width of the device.|
| max-device-width | Maximum width of the device.|
| round-screen | Screen type. The value **true** means that the screen is round, and **false** means the opposite.|
| dark-mode<sup>6+</sup> | Whether the device is in dark mode. The value **true** means that the device is in dark mode, and **false** means the opposite.|
## Sample Code
```html
<!-- xxx.hml -->
<div>
<div class="container">
<text class="title">Hello World</text>
</div>
</div>
```
```css
/* xxx.css */
.container {
width: 300px;
height: 600px;
background-color: #008000;
}
@media (device-type: wearable) {
.container-inner {
justify-content: center;
align-items: center;
padding: 40px 26px;
}
.title {
text-align: center;
}
.detail_text {
max-lines: 2;
text-align: center;
}
}
@media (device-type: tv) {
.title {
font-size: 16px;
}
.detail_text {
font-size: 12px;
}
}
@media (device-type: car) {
.title {
font-size: 12px;
color: #FFFFFF;
font-family: @id_text_font_family_medium;
}
.detail_text {
font-size: 12px;
margin-top: 2px;
font-family: @id_text_font_family_regular;
color: #FFFFFF;
}
}
```
# Universal Styles
You can set universal styles for components in the **style** attribute or **.css** files. None of the style attributes are mandatory.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| width | &lt;length&gt; \| &lt;percentage&gt; | - | Component width.<br>If this attribute is not set, the width required for the element content is used.<br>If this attribute is not set, default value **0** is used.|
| height | &lt;length&gt; \| &lt;percentage&gt; | - | Component height.<br>If this attribute is not set, the height required for the element content is used.<br>If this attribute is not set, default value **0** is used.|
| min-width | &lt;length&gt; \| &lt;percentage&gt; | 0 | Minimum component width.|
| min-height | &lt;length&gt; \| &lt;percentage&gt; | 0 | Minimum component height.|
| max-width | &lt;length&gt; \| &lt;percentage&gt; | - | Maximum component width, which has no restriction by default.|
| max-height | &lt;length&gt; \| &lt;percentage&gt; | - | Maximum component height, which has no restriction by default.|
| padding | &lt;length&gt; \| &lt;percentage&gt; | 0 | Shorthand attribute to set the padding for all sides in a declaration.<br>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 top, right, bottom, and left paddings (in clockwise order). |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; \| &lt;percentage&gt; | 0 | Left, top, right, and bottom padding.|
| padding-[start\|end] | &lt;length&gt; \| &lt;percentage&gt; | 0 | Start and end padding.|
| margin | &lt;length&gt; \| &lt;percentage&gt; | 0 | 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 top, right, bottom, and left margins (in clockwise order).|
| margin-[left\|top\|right\|bottom] | &lt;length&gt; \| &lt;percentage&gt; | 0 | Left, top, right, and bottom margins.|
| margin-[start\|end] | &lt;length&gt; \| &lt;percentage&gt; | 0 | Start and end margins.|
| border | - | 0 | 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 | 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 | Styles of the left, top, right, and bottom borders. The available values are **dotted**, **dashed**, and **solid**.|
| border-[left\|top\|right\|bottom] | - | - | 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 | &lt;length&gt; | 0 | Shorthand attribute to set the width for all borders, or separately set the width for each border.|
| border-[left\|top\|right\|bottom]-width | &lt;length&gt; | 0 | Attribute to set widths of left, top, right, and bottom borders.|
| border-color | &lt;color&gt; | black | Shorthand attribute to set the color for all borders, or separately set the color for each border.|
| border-[left\|top\|right\|bottom]-color | &lt;color&gt; | black | Attribute to set colors for left, top, right, and bottom borders.|
| border-radius | &lt;length&gt; | - | Attribute to set the radius for round borders of an element. This attribute cannot be used to set the width, color, or style of a specific border. You can use **border-width**, **border-color**, or **border-style** to set the color, width, or style for all the borders at the same time. |
| border-[top\|bottom]-[left\|right]-radius | &lt;length&gt; | - | Attribute to respectively set the radii of upper-left, upper-right, lower-right, and lower-left rounded corners. |
| background | &lt;linear-gradient&gt; | - | Background. This attribute supports [gradient styles](js-service-widget-common-gradient.md) only and is not compatible with **background-color** or **background-image**.|
| background-color | &lt;color&gt; | - | Background color.|
| background-image | string | - | Background image. This attribute is not compatible with **background-color** or **background**. Local image resources are supported.<br>Example:<br>- background-image: url("/common/background.png")<br>The SVG format is not supported.|
| background-size | - string<br>- &lt;length&gt; &lt;length&gt;<br>- &lt;percentage&gt; &lt;percentage&gt; | auto | 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>- The two **\<length>** values are as follows: <br>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:<br>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 | 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>- &lt;length&gt; &lt;length&gt;<br>- &lt;percentage&gt; &lt;percentage&gt; | 0px 0px | - 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 in the horizontal or vertical direction.<br>- Using **\<length>**: 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 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. For the upper left corner, the value is 0% 0%. For the lower right corner, the value is **100% 100%**. If only one value is specified, the other one is **50%**.<br>- Using both **\<percentage>** and **\<length>**.|
| box-shadow | string | 0 | Syntax: box-shadow: h-shadow v-shadow blur spread color<br>Shadow style of the current component. The value includes the horizontal position (mandatory), vertical position (mandatory), fuzzy radius (optional, default value: **0**), extension distance (optional, default value: **0**), and color (optional, default value: **black**) of the shadow.<br>Example:<br>- box-shadow :10px 20px 5px 10px \#888888<br>- box-shadow :100px 100px 30px red<br>- box-shadow :-100px -100px 0px 40px |
| filter | string | - | Syntax: filter: blur(px)<br>Radius of the blur area within the component layout. If this style is not set, the default value **0** (no blur) is used. Percentage values are not supported.<br>Example: filter: blur(10px)|
| backdrop-filter | string | - | Syntax: backdrop-filter: blur(px)<br>Radius of the background blur area within the component layout. If this style is not set, the default value **0** (no blur) is used. Percentage values are not supported.<br>Example: backdrop-filter: blur(10px)|
| opacity | number | 1 | Opacity of an element. The value ranges from **0** to **1**. The value **1** means opaque, and **0** means completely transparent.|
| display | string | flex | Type of the box containing an element. Available values are as follows:<br>- **flex**: flexible layout<br>- **none**: not rendered|
| visibility | string | visible | 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 element 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.|
| flex | number \| string | - | How to divide available space of the parent component for each child component.<br>You can set one to three values for this style.<br>Set one value in either of the following ways:<br>- A unitless number to set **flex-grow**.<br>- A valid width value to set **flex-basis**.<br>Set two values in the following ways:<br>The first value must be a unitless number used to set **flex-grow**. The second value must be either of the following:<br>- A unitless number to set **flex-shrink**.<br>- A valid width value to set **flex-basis**.<br>Set three values in the following ways:<br>The first value must be a unitless number used to set **flex-grow**. The second value must be a unitless number used to set **flex-shrink**. The third value must be a valid width value used to set **flex-basis**.<br>This style is valid when the parent container is **\<div>** or **\<list-item>**.|
| flex-grow | number | 0 | How much a child component will grow. The value specifies allocation of the remaining space on the main axis of the parent component. Size of available space = Container size - Total size of all child components. Value **0** indicates that the child component does not grow.<br>This style is valid when the parent container is **\<div>** or **\<list-item>**.|
| flex-shrink | number | 1 | How much a child component will shrink. The shrink occurs only when the sum of default child component widths is greater than that of the parent component. Value **0** indicates that the child component does not shrink.<br>This style is valid when the parent container is **\<div>** or **\<list-item>**.|
| flex-basis | &lt;length&gt; | - | Initial length of the flex item on the main axis.<br>This style is valid when the parent container is **\<div>** or **\<list-item>**.|
| align-self | string | - | Alignment mode on the cross axis of the parent element. This style overwrites the align-items style of the parent element. The align-items style is used only in the div and list styles of the parent container. Available values are as follows:<br>- **stretch**: Items are stretched to the same height or width as the container along the cross axis.<br>- **flex-start**: Items are packed toward the start edge of the cross axis.<br>- **flex-end**: Items are packed toward the end edge of the cross axis.<br>- **center**: Items are packed toward the center of the cross axis.<br>- **baseline**: Items are aligned at the baseline of the cross axis.|
| position | string | relative | Positioning type of the component. Dynamic changes are not supported.<br>- **fixed**: The component is positioned related to the browser window.<br>**absolute**: The component is positioned absolutely to its parent element.<br>- **relative**: The component is positioned relative to its normal position.<br>The **absolute** attribute takes effect only when the parent component is **\<div>**.|
| [left\|top\|right\|bottom | &lt;length&gt; \| &lt;percentage&gt; | - | left\|top\|right\|bottom must be used together with **position** to determine the offset of the component.<br>- The **left** attribute specifies the left edge position of the component. This attribute defines the offset between the left edge of the margin area of a positioned component and left edge of its containing block.<br>- The **top** attribute specifies the top edge position of the component. This attribute defines the offset between the top edge of a positioned component and that of a block included in the component.<br>- The **right** attribute specifies the right edge position of the component. This attribute defines the offset between the right edge of a positioned component and that of a block included in the component.<br>- The **bottom** attribute specifies the bottom edge position of the component. This attribute defines the offset between the bottom edge of a positioned component and that of a block included in the component.|
| [start \| end] | &lt;length&gt; \| &lt;percentage&gt; | - | start \|end must be used together with **position** to determine the offset of the component.<br>- The **start** attribute specifies the start edge position of the component. This attribute defines the offset between the start edge of a positioned component and that of a block included in the component.<br>- The **end** attribute specifies the end edge position of the component. This attribute defines the offset between the end edge of a positioned component and that of a block included in the component.|
| z-index | number | - | Render sequence of child nodes under the same parent node. A child node with a larger value will be rendered later.<br>This style does not support **auto**, and other styles, such as **opacity**, do not affect the render sequence of a child node.|
| image-fill | &lt;color&gt; | - | Fill color for SVG images. The following components (and attributes) are supported: **button** (**icon** attribute) and **image** (**src** attribute).<br>The **fill** color value in the SVG image file is replaced with the value of **image-fill** during rendering, and is valid only for the fill attribute that is declared in the SVG image.|
| clip-path | [ &lt;geometry-box&gt; \|&lt;basic-shape&gt; ] \| none | - | Clip area of the component. Only the content within this area is displayed.<br>**\<geometry-box>**: applicable scope of the clip area's width and height. The default value is **border-box**. Available values are as follows:<br>- **margin-box**: The width and height includes the margin.<br>- **border-box**: The width and height includes the border.<br>- **padding-box**: The width and height includes the padding.<br>- **content-box**: The width and height does not include any margin, border, or padding.<br>**\<basic-shape>**: shape of the clip area. Available values include:<br>- **inset**, in the format of inset( &lt;percentage&gt;{1,4} [ round &lt;'border-radius'&gt; ]? )<br>- **circle**, in the format of circle( [ &lt;percentage&gt; ]? [ at &lt;percentage&gt; &lt;percentage&gt; ]? )<br>- **ellipse**, in the format of ellipse( [ &lt;percentage&gt;{2} ]? [ at &lt;percentage&gt; &lt;percentage&gt; ]? )<br>- **polygon**, in the format of polygon( [ &lt;percentage&gt; &lt;percentage&gt; ]\# )<br>- **path**, in the format of path( &lt;string&gt; )|
| mask-image | - &lt;linear-gradient&gt;<br>- string | - | Image used for the mask of the component:<br>Gradient color mask, for example, **linear-gradient(to left, black, white)**.<br>Solid color mask, for example, **linear-gradient(to right, grey , grey)**.<br>Mask filled by a local SVG image, for example, **url(common/mask.svg)**|
| mask-size | - string<br>- &lt;length&gt;&lt;length&gt;<br>- &lt;percentage&gt; &lt;percentage&gt; | auto | Display size of the mask image. The setting is valid only when **mask-image** is set to an image source.<br>The **string** values 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 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 as follows: 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 indicate the image size in relative to the original image size. 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.|
| mask-position | - string string<br>- &lt;length&gt; &lt;length&gt;<br>- &lt;percentage&gt; &lt;percentage&gt; | 0px 0px | Display position of the mask image. The setting is valid only when **mask-image** is set to an image source. 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>The **string** values are as follows:<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. For the upper left corner, the value is 0 0 in px (**0px 0px**). 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. For the upper left corner, the value is 0% 0%. For the lower right corner, the value is **100% 100%**. If only one value is specified, the other one is **50%**.<br>Using both **\<percentage>** and **\<length>**.|
# badge
The **\<badge>** component is used to mark new events that require user attention in your application.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
This component supports only one child component.
## attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| placement | string | rightTop | No| Position of a number or dot badge. Available values are as follows:<br>**right**: on the right border of the component.<br>- **rightTop**: in the upper right corner of the component border.<br>- **left**: on the left border of the component.|
| count | number | 0 | No| Number of notifications displayed via the badge. The default value is **0**. If the number of notifications is greater than 0, the badge changes from a dot to the number. If this attribute is not set or the value is less than or equal to 0, the badge is a dot.<br>When the **count** value is greater than the **maxcount** value, *maxcount***+** is displayed. The largest integer value supported for **count** is **2147483647**.|
| visible | boolean | false | No| Whether to display the badge. The value **true** means that the badge shows up when a new notification is received. To use a number badge, set the **count** attribute.|
| maxcount | number | 99 | No| Maximum number of notifications. When the number of new notifications exceeds the value of this attribute, *maxcount***+** is displayed, for example, **99+**.<br>Note: The maximum integer value is 2147483647.|
| config | BadgeConfig | - | No| Configuration of the badge.|
| label | string | - | No| Text of the new notification displayed via the badge.<br>When this attribute is set, attributes **count** and **maxcount** do not take effect.|
### BadgeConfig
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| badgeColor | &lt;color&gt; | #fa2a2d | No| Background color of the badge.|
| textColor | &lt;color&gt; | #ffffff | No| Text color of the number badge.|
| textSize | &lt;length&gt; | 10px | No| Text size of the number badge.|
| badgeSize | &lt;length&gt; | 6px | No| Size of the dot badge.|
## Styles
The [universal styles](js-service-widget-common-styles.md) are supported.
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
```html
<!-- xxx.hml -->
<div class="container">
<badge class="badge" config="{{badgeconfig}}" visible="true" count="100" maxcount="99">
<text class="text1">example</text>
</badge>
<badge class="badge" visible="true" count="1">
<text class="text2">example</text>
</badge>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
width: 100%;
align-items: center;
}
.badge {
width: 80px;
height: 60px;
margin-top: 30px;
}
.text1 {
background-color: #f9a01e;
font-size: 19fp;
}
.text2 {
background-color: #46b1e3;
font-size: 19fp;
}
```
```json
{
"data":{
"badgeconfig":{
"badgeColor":"#0a59f7",
"textColor":"#ffffff",
"textSize":"9px",
"badgeSize": "14px"
}
}
}
```
![badgeSample](figures/badgeSample.png)
# div
The **\<div>** component is a basic container that is used as the root node of the page structure or is used to group the content.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Supported
## Attributes
The [universal attributes](js-service-widget-common-attributes.md) are supported.
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| flex-direction | string | row | No| Main axis direction of the flex container, which defines how items are placed in the container. Available values are as follows:<br>- **column**: Items are placed vertically from top to bottom.<br>- **row**: Items are placed horizontally from left to right.|
| flex-wrap | string | nowrap | No| Whether items in the flex container are displayed in a single line or multiple lines. The value cannot be dynamically updated. Available values are as follows:<br>- **nowrap**: Flex items are displayed in a single line.<br>- **wrap**: Flex items are displayed in multiple lines.|
| justify-content | string | flex-start | No| How items are aligned along the main axis of the flex container. Available values are as follows:<br>- **flex-start**: Items are packed toward the start edge of the container along the main axis.<br>- **flex-end**: Items are packed toward the end edge of the container along the main axis.<br>- **center**: Items are packed toward the center of the container along the main axis.<br>- **space-between**: Items are positioned with space between the rows.<br>- **space-around**: Items are positioned with space before, between, and after the rows.<br>- **space-evenly**<sup>5+</sup>: Items are distributed within the container along the main axis, with even space between each two.|
| align-items | string | stretch | No| How items are aligned along the cross axis in a flex container. Available values are as follows:<br>- **stretch**: Items are stretched to the same height or width as the container along the cross axis.<br>- **flex-start**: Items are packed toward the start edge of the cross axis.<br>- **flex-end**: Items are packed toward the end edge of the cross axis.<br>- **center**: Items are packed toward the center of the cross axis.|
| align-content | string | flex-start | No| Multi-row alignment mode when there is extra space in the cross axis. Available values are as follows:<br>- **flex-start**: All rows are packed toward the start edge of the cross axis. The start edge of the cross axis of the first row is aligned with the start edge of the cross axis of the container. All subsequent rows are aligned with the previous row.<br>- **flex-end**: All rows are packed toward the end edge of the cross axis. The end of the cross axis of the last row is aligned with the end of the cross axis of the container. All subsequent rows are aligned with the previous row.<br>- **center**: All rows are packed toward the center of the cross axis. Rows are close to each other and aligned with the center of the container. The spacing between the start edge of the container's cross axis and the first row is equal to the spacing between the end edge of the container's cross axis and the last row.<br>- **space-between**: All rows are evenly distributed in the container. The spacing between two adjacent rows is the same. The start and end edges of the container's cross axis are aligned with the edges of the first and last rows, respectively.<br>- **space-around**: All rows are evenly distributed in the container. The spacing between two adjacent rows is the same. The spacing between the start edge of the container's cross axis and the first row and that between the end edge and the last row are half of the spacing between two adjacent rows.|
| display | string | flex | No| Type of the view box of the item. The value cannot be dynamically updated. Available values are as follows:<br>- **flex**: flexible layout<br>- **none**: not rendered|
| grid-template-[columns\|rows] | string | 1 row, 1 column| No| Number of rows and columns in the current grid layout. If this attribute is not set, one row and one column are displayed by default. This attribute is valid only when **display** is set to **grid**.<br>Below are some example values of **grid-template-columns**:<br>- **50px 100px 60px**: There are three columns. The first column is 50 px, the second column is 100 px, and the third column is 60 px.<br>- **1fr 1fr 2fr**: There are three columns, and the width allowed by the parent component is divided into four equal shares. The first column occupies one share, the second column occupies one share, and the third column occupies two shares.<br>- **30% 20% 50%**: There are three columns. The first column occupies 30% of the total width allowed by the parent component, the second column occupies 20%, and the third column occupies 50%.<br>- **repeat (2,100px)**: There are two columns. The first column is 100 px, and the second column is 100 px.<br>- **repeat(auto-fill,100px)**<sup>5+</sup>: Each column is 100 px and repeats to fill the cross axis. The number of columns is calculated based on the column size and the cross axis size.<br>- **auto 1fr 1fr**: There are three columns. The first column is adaptive to the width required by its child components. The remaining space is divided into two equal shares, one share occupied by each of the rest two columns.|
| grid-[columns\|rows]-gap | &lt;length&gt; | 0 | No| Size of the gap between two consecutive rows or columns in a grid layout. You can also use **grid-gap** to set the same size of the gap between rows and columns. This attribute is valid only when **display** is set to **grid**.|
| grid-row-[start\|end] | number | - | No| Start and end row numbers of the current item in the grid layout. This attribute is valid only when the item's parent component is a **\<div>** container whose **display** style is set to **grid**.|
| grid-column-[start\|end] | number | - | No| Start and end column numbers of the current item in the grid layout. This attribute is valid only when the item's parent component is a **\<div>** container whose **display** style is set to **grid**.|
| grid-auto-flow | string | - | No| How grid items are laid out automatically. Available values are as follows:<br>- **row**: Elements are filled row by row. When there is no horizontal space in a row, a new row is added.<br>- **column**: Elements are filled column by column. When there is no vertical space in a column, a new column is added.|
| align-items | string | - | No| How items are aligned along the cross axis in a flex container. Available values are as follows:<br>- **stretch**: Items are stretched to the same height or width as the flex container along the cross axis.<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>- **baseline**: In a vertical layout, items are aligned to the start of the cross axis, which means that this value is equivalent of **flex-start**. In a horizontal layout, items are aligned with the text baseline if there is text involved, and aligned to the bottom otherwise.|
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
1. Flex style
```html
<!-- xxx.hml -->
<div class="container">
<div class="flex-box">
<div class="flex-item color-primary"></div>
<div class="flex-item color-warning"></div>
<div class="flex-item color-success"></div>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 454px;
height: 454px;
}
.flex-box {
justify-content: space-around;
align-items: center;
width: 400px;
height: 140px;
background-color: #ffffff;
}
.flex-item {
width: 120px;
height: 120px;
border-radius: 16px;
}
.color-primary {
background-color: #007dff;
}
.color-warning {
background-color: #ff7500;
}
.color-success {
background-color: #41ba41;
}
```
**2 x 4 widget**
![en-us_image_0000001231610863](figures/en-us_image_0000001231610863.png)
2. Flex wrap style
```html
<!-- xxx.hml -->
<div class="container">
<div class="flex-box">
<div class="flex-item color-primary"></div>
<div class="flex-item color-warning"></div>
<div class="flex-item color-success"></div>
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 454px;
height: 454px;
}
.flex-box {
justify-content: space-around;
align-items: center;
flex-wrap: wrap;
width: 300px;
height: 250px;
background-color: #ffffff;
}
.flex-item {
width: 120px;
height: 120px;
border-radius: 16px;
}
.color-primary {
background-color: #007dff;
}
.color-warning {
background-color: #ff7500;
}
.color-success {
background-color: #41ba41;
}
```
**4 x 4 widget**
![en-us_image_0000001186131150](figures/en-us_image_0000001186131150.png)
# list-item
**\<list-item>** is a child component of the **[\<list>](js-service-widget-container-list.md)** component and is used to display items in a list.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
> - You can customize the width of each **\<list-item>**. However, if you retain the default value **stretch** of **align-items** for the parent component **\<list>**, the width of **\<list-item>** is equal to that of **\<list>**. To make the customized **\<list-item>** width take effect, set **align-items** to other values rather than **stretch**.
>
> - When possible, do not develop the long press and drag gestures on the **\<list-item>** component.
## Child Components
Supported
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| type | string | default | No| Type of the list-item. A list can contain multiple list-item types. The same type of list items should have the same view layout after being rendered. When the type is fixed, replace the **if** attribute with the **show** attribute to ensure that the view layout remains unchanged.|
| section | string | - | No| String used to match this item. This attribute can be left empty. Type of the **Enter** key on the soft keyboard. The value cannot be dynamically updated. In a list item group, only the string set for the primary item is valid.|
| sticky | string | none | No| Whether the current item sticks in place at the top, and the effect when it disappears. This attribute supports vertical lists only and is invalid for items in a group.<br>- **none**: The current item does not stick at the top.<br>- **normal**: The current item sticks at the top and disappears with a sliding effect.<br>- **opacity**: The current item sticks at the top and disappears gradually. This option is only supported on wearables.|
| clickeffect | boolean | true | No| Whether an effect is displayed when the current item is clicked.<br>- **false**: No effect is displayed when the item is clicked.<br>- **true**: An effect is displayed when the item is clicked.|
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name| Type| Default Value| Mandatory| Description|
| -------- | -------- | -------- | -------- | -------- |
| column-span | &lt;number&gt; | 1 | No| Number of columns occupied by the current list-item in the list. By default, the list-item occupies one column. This attribute is valid only when the list contains multiple columns.|
| click-color | &lt;color&gt; | - | No| Backplane color of a list-item when touched.|
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
For details, see [Example of the \<list> component](js-service-widget-container-list.md#example).
# list
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.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
>
> Limit the number of items in a list to 30 to improve user experience.
## Child Components
Only the **[\<list-item>](js-service-widget-container-list-item.md)** child component is supported.
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| ------------- | -------------- | ------- | ---- | ---------------------------------------- |
| cachedcount | number | 0 | No | Minimum number of cached list items when a long list is loaded with delay. |
| 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 on display. |
| scrolleffect | string | spring | No | Scroll effect. Available values 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 you scroll to 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.|
| divider | boolean | false | No | Whether list items are separated by dividers.<br>For details, see **divider-color**, **divider-height**, **divider-length**, and **divider-origin** in [Styles](#styles).|
| 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.|
| initialindex | number | 0 | No | Item displayed at the start position of the viewport when the 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. |
| initialoffset | &lt;length&gt; | 0 | No | Start offset of the viewport when the list is loaded for the first time. The offset must not exceed the scrolling range of the list. If exceeded, the offset is truncated to the maximum value of the scrolling range. |
| selected | string | - | No | Selected item in the list. The value can be a **section** value of any list items. |
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| ---------------- | ---------------------------------------- | ----------- | ---- | ---------------------------------------- |
| divider-color | &lt;color&gt; | transparent | No | Item divider color. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-height | &lt;length&gt; | 1 | No | Item divider height. This style is valid only when the **divider** attribute of **\<list>** is set to **true**. |
| divider-length | &lt;length&gt; | 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 | &lt;length&gt; | 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 along the cross axis.<br>- **flex-start**: Items are packed toward the start edge of the cross axis.<br>- **flex-end**: Items are packed toward the end edge of the cross axis.<br>- **center**: Items are packed toward the center of the cross axis.<br>This style takes effect only on items of each column. Columns are evenly distributed.|
| item-extent | &lt;length&gt; \| &lt;percentage&gt; | - | 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 | &lt;color&gt; | grey | No | Color of the physical dynamic effect. This attribute is valid only when **scrolleffect** is set to **fade**. |
| scrollbar-color | &lt;color&gt; | - | No | Color of the scrollbar. |
| scrollbar-width | &lt;length&gt; | - | No | Width of the scrollbar. |
| scrollbar-offset | &lt;length&gt; | 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
The [universal events](js-service-widget-common-events.md) are supported.
## Example
```html
<!-- index.hml -->
<div class="container">
<list class="todo-wraper">
<list-item for="{{todolist}}" class="todo-item">
<text class="todo-title">{{$item.title}}</text>
<text class="todo-title">{{$item.date}}</text>
</list-item>
</list>
</div>
```
```json
{
"data": {
"todolist": [{
"title": "work",
"date": "2021-12-31 10:00:00"
}, {
"title": "watch movie",
"date": "2021-12-31 20:00:00"
}]
}
}
```
```css
/* index.css */
.container {
display: flex;
justify-content: center;
align-items: center;
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.todo-wraper {
width: 454px;
height: 300px;
}
.todo-item {
width: 454px;
height: 80px;
flex-direction: column;
}
.todo-title {
width: 454px;
height: 40px;
text-align: center;
}
```
**4 x 4 widget**
![en-us_image_0000001231370803](figures/en-us_image_0000001231370803.png)
# stack
The **\<stack>** component provides a stack container where child components are successively stacked and the latter one overwrites the previous one.
> **NOTE**
>
>The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Child Components
Supported
## Attributes
The [universal attributes](js-service-widget-common-attributes.md) are supported.
## Styles
The [universal styles](js-service-widget-common-styles.md) are supported.
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
```html
<!-- xxx.hml -->
<stack class="stack-parent">
<div class="back-child bd-radius"></div>
<div class="positioned-child bd-radius"></div>
<div class="front-child bd-radius"></div>
</stack>
```
```css
/* xxx.css */
.stack-parent {
width: 400px;
height: 400px;
margin: 50px;
background-color: #ffffff;
border-width: 1px;
border-style: solid;
}
.back-child {
width: 300px;
height: 300px;
background-color: #3f56ea;
}
.front-child {
width: 100px;
height: 100px;
background-color: #00bfc9;
}
.positioned-child {
width: 100px;
height: 100px;
left: 50px;
top: 50px;
background-color: #47cc47;
}
.bd-radius {
border-radius: 16px;
}
```
**4 x 4 widget**
![Stack](figures/stack.PNG)
# swiper
The **\<Swiper>** component provides a container that allows users to switch among child components using swipe gestures.
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
## Attributes
In addition to the [universal attributes](js-service-widget-common-attributes.md), the following attributes are supported.
| Name | Type | Default Value | Mandatory | Description |
| --------- | ------- | ----- | ---- | ---------------------------------------- |
| index | number | 0 | No | Index of the child component currently displayed in the container. |
| indicator | boolean | true | No | Whether to enable the indicator. The default value is **true**. |
| digital | 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**.|
| 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. |
## Styles
In addition to the [universal styles](js-service-widget-common-styles.md), the following styles are supported.
| Name | Type | Default Value | Mandatory | Description |
| ---------------------------------- | ---------------------------------------- | ---- | ---- | -------------------- |
| indicator-color | &lt;color&gt; | - | No | Fill color of the indicator. |
| indicator-selected-color | &lt;color&gt; | - | No | Color of the currently selected indicator. |
| indicator-size | &lt;length&gt; | 4px | No | Diameter of the indicator. |
| indicator-top\|left\|right\|bottom | &lt;length&gt; \| &lt;percentage&gt; | - | No | Relative position of the indicator in the swiper.|
## Events
The [universal events](js-service-widget-common-events.md) are supported.
## Example
```html
<!-- xxx.hml -->
<swiper class="container" index="{{index}}">
<div class="swiper-item primary-item">
<text>1</text>
</div>
<div class="swiper-item warning-item">
<text>2</text>
</div>
<div class="swiper-item success-item">
<text>3</text>
</div>
</swiper>
```
```css
/* xxx.css */
.container {
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.swiper-item {
width: 454px;
height: 454px;
justify-content: center;
align-items: center;
}
.primary-item {
background-color: #007dff;
}
.warning-item {
background-color: #ff7500;
}
.success-item {
background-color: #41ba41;
}
```
```json
{
"data": {
"index": 1
}
}
```
**4 x 4 widget**
![Swiper](figures/swiper.png)
# Custom Component Basic Usage
> **NOTE**
>
> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
Custom components are existing components encapsulated based on service requirements. A custom component can be invoked multiple times in a project to improve the code readability. You can introduce a custom component to the host page through **element** as shown in the following code snippet:
```html
<element name='comp' src='../../common/component/comp.hml'></element>
<div>
<comp prop1='xxxx' @child1="bindParentVmMethod"></comp>
</div>
```
- The **name** attribute indicates the custom component name (optional), which is case-insensitive and is in lowercase by default. The **src** attribute indicates the **.hml** file path (mandatory) of the custom component. If **name** is not set, the **.hml** file name is used as the component name by default.
- Event binding: Use **(on|\@)*child1*** in the custom component to bind a child component event. In the child component, use **{action:"*proxy*", method: "*eventName*"}** to trigger the bound event and pass the parameter value. In the parent component, call **bindParentVmMethod** and receive the parameter passed from the child component.
## Labels of Custom Component Configuration File
| Name| Type| Description|
| -------- | -------- | -------- |
| data | Object | Data model of the page. The name cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (**for**, **if**, **show**, and **tid**).|
| props | Array/Object | Used for communication between components. This attribute can be transferred to components via **<tag xxxx='value'>**. A **props** name must be in lowercase and cannot start with a dollar sign ($) or underscore (_). Do not use reserved words (**for**, **if**, **show**, and **tid**). Currently, **props** does not support functions.|
## Adding a Custom Event
Custom components support custom events, whose **action** is **proxy** and name is specified by **method**. A service widget page that uses a custom component can register an event callback corresponding to the custom event name. When the custom event in the custom component is triggered, the registered callback will be invoked.
> **NOTE**
>
> The event name cannot contain uppercase letters.
Example of a custom child component:
```html
<!-- comp.hml -->
<div class="container">
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```css
/* comp.css */
.container {
flex-direction:column;
background-color: green;
width: 100%;
height: 100%;
}
.row-3 {
width: 100%;
height: 50px;
background-color: orange;
font-size:15px;
}
```
```json
{
"data": {
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method":"event_1"
}
}
}
```
Example of a parent component:
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp @event_1="click"></comp>
<button value="parentClick" @click="buttonClick"></button>
</div>
```
```css
/* xxx.css */
.container {
background-color: red;
height: 500px;
width: 500px;
}
```
```json
{
"data": {
},
"actions": {
"click": {
"action": "message",
"params": {
"message": "click event"
}
},
"buttonClick": {
"action": "message",
"params": {
"message": "click event 2"
}
}
}
}
```
## props
You can use **props** to declare custom attributes of a custom component. The attributes can be used by a parent component to pass parameters to a child component.
### Default Value
You can set the default value for a child component attribute via **default**. The default value is used if the parent component does not have **default** set. In this case, the **props** attribute must be in object format instead of an array.
```html
<!-- comp.hml -->
<div class="container">
<div class="row-1">
<div class="box-1">
<text>xiaoziti</text>
</div>
<div class="box-2">
<text>{{text}}</text>
</div>
<div class="box-3">
<text>{{textdata[0]}}</text>
</div>
</div>
<div class="row-2" if="true">
<button value="{{progress}}"></button>
</div>
<div class="row-3" if="true">
<button onclick="buttonClicked" value="click"></button>
</div>
</div>
```
```json
{
"data": {
"progress": {
"default": "80"
}
},
"props": {
"textdata": {
"default": ["a","b"]
},
"progress": {
"default": 60
},
"text": {
"default": "ha"
}
},
"actions": {
"buttonClicked": {
"action": "proxy",
"method": "event_1"
}
}
}
```
Example of the parent component that references the **comp** child component:
```html
<!-- xxx.hml -->
<element name='comp' src='../../common/customComponent/customComponent.hml'></element>
<div class="container">
<comp progress="{{clicknow}}" textdata="{{texts}}" if="false" @event_1="click"></comp>
</div>
```
### Unidirectional Value Transfer
Data can be transferred only from the parent component to child components. You are not allowed to change the value passed to the child component. However, you can receive the value passed by **props** as a default value in **data**, and then change the **data** value.
For details, see [props](../arkui-js/js-components-custom-props.md).
# File Organization
## Directory Structure
Below is the typical directory structure (**entry/src/main/js/Widget**) of a JS service widget.
```
├─widget
│ ├─common
│ │ └─widget.png
│ ├─i18n
│ │ ├─en-US.json
│ │ └─zh-CN.json
│ └─pages
│ └─index
│ ├─index.css
│ ├─index.hml
│ └─index.json
```
Functions of the files are as follows:
- **.hml** files describe the widget template layout.
- **.css** files describe the page style.
- **.json** files define variables and action events used for a service widget.
Functions of the folders are as follows:
- The **pages** folder stores template pages.
- The **common** folder stores public resource files, such as images.
- The **i18n** folder stores resources in different languages, for example, UI strings and image paths.
## File Access Rules
Application resources can be accessed via an absolute or relative path. In this development framework, an absolute path starts with a slash (/), and a relative path starts with **./** or **../**. The rules are as follows:
- To reference a code file, use a relative path, for example, **../common/style.css**.
- To reference a resource file, use an absolute path, for example, **/common/test.png**.
- Store code files and resource files in the **common** directory and access them in the required fashion.
- In a **.css** file, use the **url()** function to create a URL, for example, **url(/common/test.png)**.
> **NOTE**
>
> When code file A needs to reference code file B:
>
> - If code files A and B are in the same directory, you can use either a relative or absolute path in code file B to reference resource files.
>
> - If code files A and B are in different directories, you must use an absolute path in code file B to reference resource files. The reason is that the directory of code file B changes during Webpack packaging.
>
> - When defining data in a **.json** file, use absolute paths for resource files.
## Configuration Files
If you are developing a widget in the FA model, configure the **config.json** file. For details, see [FA Widget Development](../../ability/fa-formability.md#configuring-the-widget-configuration-file).
If you are developing a widget in the stage model, configure **ExtensionAbility** under **extensionAbilities** in the **module.json5** file. For details, see [Stage Widget Development](../../ability/stage-formextension.md#configuring-the-widget-configuration-file).
# Multi-Language Capability
Applications designed based on the development framework apply to different countries and regions. With the multi-language capability, you do not need to develop application versions in different languages, and your users can switch between various locales. This also facilitates project maintenance.
You only need to perform operations in [Defining Resource Files](#defining-resource-files) and [Referencing Resources](#referencing-resources) to use the multi-language capability of this framework.
## Defining Resource Files
Resource files store application content in multiple languages. This framework uses JSON files to store resource definitions.
Place the resource file of each locale in the **i18n** directory described in [File Organization](js-service-widget-file.md). Resource files are named in *language-region***.json** format. For example, the resource file for English (United States) is named **en-US.json**. If there is no resource file of the locale that matches the system language, content in the **en-US.json** file will be used by default.
Different languages have different matching rules for singular and plural forms. In the resource file, **zero**, **one**, **two**, **few**, **many**, and **other** are used to define the string content in different singular and plural forms. For example, there is only the **other** scenario in Chinese since the language does not have singular and plural forms. **One** and **other** scenarios are applicable to English. All the preceding six scenarios are needed for Arabic.
The following example takes **en-US.json** and **ar-AE.json** as examples:
```json
{
"strings": {
"hello": "Hello world!",
"symbol": "@#$%^&*()_+-={}[]\\|:;\"'<>,./?",
"plurals": {
"one": "one person",
"other": "other people"
}
},
"files": {
"image": "image/en_picture.PNG"
}
}
```
```json
{
"strings": {
"plurals": {
"zero": "لا أحد",
"one": "وحده",
"two": "اثنان",
"few": "ستة اشخاص",
"many": "خمسون شخص",
"other": "مائة شخص"
}
}
}
```
## Referencing Resources
Multi-language syntax used on application development pages (including simple formatting and singular-plural formatting) can be used in **.hml** or **.js** files.
- Simple formatting
Use the **$t** function to reference to resources of different locales. The **$t** function is available for both **.hml** and **.js** files. The system displays content based on a resource file path specified via **$t** and the specified resource file whose locale matches the current system language.
**Table 1** Simple formatting
| Name | Type | Parameter | Mandatory | Description |
| ---- | -------- | -------- | ---- | -------------------------------------- |
| $t | Function | Described in **$t parameters**| Yes | Sets the parameters based on the system language, for example, **this.$t('strings.hello')**.|
**Table 2** $t parameters
| Name | Type | Mandatory | Description |
| ---- | ------ | ---- | ---- |
| path | string | Yes | Resource path.|
- Example code for simple formatting
```html
<!-- xxx.hml -->
<div>
<text>{{ $t('strings.hello') }}</text>
<image src="{{ $t('files.image') }}" class="image"></image>
</div>
```
- Singular-Plural Conversion
**Table 3** Singular-plural conversion
| Name | Type | Parameter | Mandatory | Description |
| ---- | -------- | --------- | ---- | ---------------------------------------- |
| $tc | Function | Described in **$tc parameters**| Yes | Converts between the singular and plural forms based on the system language, for example, **this.$tc('strings.plurals')**.<br>The resource content is distinguished by the following JSON keys: **zero**, **one**, **two**, **few**, **many**, and **other**.|
**Table 4** $tc parameters
| Parameter | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| path | string | Yes | Resource path. |
| count | number | Yes | Number|
- Example code for converting between the singular and plural forms
```html
<!--xxx.hml-->
<div>
<!-- When the value 0 is passed, "0 people" matches the Arabic string whose key is zero. -->
<text>{{ $tc('strings.plurals', 0) }}</text>
<!-- When the value 1 is passed, "1 person" matches the Arabic string whose key is one. -->
<text>{{ $tc('strings.plurals', 1) }}</text>
<!-- When the value 2 is passed, "2 people" matches the Arabic string whose key is two. -->
<text>{{ $tc('strings.plurals', 2) }}</text>
<!-- When the value 6 is passed, "6 people" matches the Arabic string whose key is few. -->
<text>{{ $tc('strings.plurals', 6) }}</text>
<!-- When the value 50 is passed, "50 people" matches the Arabic string whose key is many. -->
<text>{{ $tc('strings.plurals', 50) }}</text>
<!-- When the value 100 is passed, "100 people" matches the Arabic string whose key is other. -->
<text>{{ $tc('strings.plurals', 100) }}</text>
</div>
```
# CSS
Cascading Style Sheets (CSS) is a language used to describe the HML page structure. All HML components have default styles. You can customize styles for these components using CSS to design various pages.
## Size Unit
1. Logical px set by **\<length>**:
1. The default logical width of a service widget is 150 px. The page will be scaled to fit the actual width of the screen. For example, on a screen with the actual width of 300 physical px, 100 px is rendered on 200 physical px, with the size doubled from 150 px to 300 px.
2. If you set **autoDesignWidth** to **true**, the logical pixels are scaled based on the screen density. For example, if the screen density is 3x, 100 px will be rendered on 300 physical px. This approach is recommended when your application needs to adapt to multiple devices.
2. Percentage set by **\<percentage>**: The component size is represented by its percentage of the parent component size. For example, if the width **\<percentage>** of a component is set to **50%**, the width of the component is half of its parent component's width.
## Style Import
CSS files can be imported using the **\@import** statement. This facilitates module management and code reuse.
## Style Declaration
The **.css** file with the same name as the **.hml** file in each page directory describes the styles of components on the HML page, determining how the components will be displayed.
1. Internal style: The **style** and **class** attributes can be used to specify the component style. Example:
```html
<!-- index.hml -->
<div class="container">
<text style="color: red">Hello World</text>
</div>
```
```css
/* index.css */
.container {
justify-content: center;
}
```
2. External style files: You need to import the files. For example, create a **style.css** file in the **common** directory and import the file at the beginning of **index.css**.
```css
/* style.css */
.title {
font-size: 50px;
}
```
```css
/* index.css */
@import '../../common/style.css';
.container {
justify-content: center;
}
```
## Selectors
A CSS selector is used to select elements for which styles need to be added to. The following table lists the supported selectors.
| Selector| Example| Description|
| -------- | -------- | -------- |
| .class | .container | Selects all components whose **class** is **container**.|
| \#id | \#titleId | Selects all components whose **id** is **titleId**.|
Example:
```html
<!-- Pagelayoutexample.hml -->
<div id="containerId" class="container">
<text id="titleId" class="title">Title</text>
<div class="content">
<text id="contentId">Content</text>
</div>
</div>
```
```css
/* Pagestyleexample.css */
/* Set the style for the components whose class is title. */
.title {
font-size: 30px;
}
/* Set the style for the components whose id is contentId. */
#contentId {
font-size: 20px;
}
```
## Selector Specificity
The specificity rule of the selectors complies with the W3C rule, which is only available for inline styles, **id**, and **class**. (Inline styles are those declared in the **style** attribute.)
When multiple selectors point to the same element, their priorities are as follows (in descending order): inline style > **id** > **class**.
# HML
The OpenHarmony Markup Language (HML) is an HTML-like language that allows you to build pages based on components and events. HML pages provide advanced capabilities such as data binding, event binding, loop rendering, conditional rendering, and logic control.
## Page Structure
```html
<!-- xxx.hml -->
<div class="item-container">
<text class="item-title">Image Show</text>
<div class="item-content">
<image src="/common/xxx.png" class="image"></image>
</div>
</div>
```
## Data Binding
```html
<!-- xxx.hml -->
<div class="item-container">
<text>{{content}}</text> <!-- Display Hello World!-->
<text>{{key1}} {{key2}}</text> <!-- Display Hello World-->
<text>key1 {{key1}}</text> <!-- Display key1 Hello-->
<text>{{flag1 && flag2}}</text> <!-- Display false-->
<text>{{flag1 || flag2}}</text> <!-- Display true-->
<text>{{!flag1}}</text> <!-- Display false-->
</div>
```
Declare the variables used in the XML file for service widgets in the **data** field in the JSON file.
```json
{
"data": {
"content": "Hello World!",
"key1": "Hello",
"key2": "World",
"flag1": true,
"flag2": false
}
}
```
> **NOTE**
> - When using data binding, you can use the object operator or array operator on a key to access the bound data, for example, **{{key.value}}** and **{{key[0]}}**.
>
> - String concatenation, logical operations, and ternary expressions are supported.
> - String concatenation:
> - A variable can be followed by another variable, for example, **{{key1}}{{key2}}**.
> - A variable can also be followed by a constant, for example, **"my name is {{name}}, i am from {{city}}." "key1 {{key1}}"**.
> - Logical operations:
> - AND: {{flag1 && flag2}} (The AND operation can only be performed on two Boolean variables.)
> - OR: {{flag1 || flag2}} (The OR operation can only be performed on two Boolean variables.)
> - NOT: {{! flag1}} (The NOT operation can only be performed on a Boolean variable.)
> - Ternary expressions:
> - {{flag? key1: key2}} (**flag** is a Boolean variable. **key1** and **key2** can be variables or constants.)
> - Notes
> - The default value is **false** when a Boolean-specific operation is performed on a non-Boolean variable.
> - The preceding variable and operation parsing do not support nesting.
## Event Binding
Declare the events for service widgets in the **actions** field in the JSON file. Service widgets support the common click event only. The event must be declared explicitly. The event definition must contain the **action** field to describe the event type. Service widgets support redirection events (**router**) and message events (**message**). A redirection event is used for switching to the OpenHarmony application (the widget provider). A message event can transfer custom information to the service widget provider. Event parameters can be variables, which are defined using **{{}}**. If the **params** field is defined in the redirection event, you can pass **params** to the **onStart** method (as **intent**) of the started application to access the value.
- Redirection event properties
Define the **abilityName** and **params** fields to implement direct redirection to the target application.
| Selector | Example | Default Value | Description |
| ----------- | ------ | -------- | ---------------------------------------- |
| action | string | "router" | Event type.<br>- **"router"**: redirection event.<br>- **"message"**: message event.|
| abilityName | string | - | Name of the ability to redirect to. |
| params | Object | - | Additional parameter passed during the redirection. |
```json
{
"data": {
"mainAbility": "xxx.xxx.xxx"
},
"actions": {
"routerEvent": {
"action": "router",
"abilityName": "{{mainAbility}}",
"params":{}
}
}
}
```
You can also implement redirection to the target application using a **want**, which contains the **abilityName**, **bundleName**, and **parameters** fields.
| Selector | Type | Default Value | Description |
| ------ | ------ | -------- | ---------------------------------------- |
| action | string | "router" | Event type.<br>- **"router"**: redirection event.<br>- **"message"**: message event.|
| want | [Want](../apis/js-apis-application-Want.md) | - | Information about the target application. For details, see the **want** format. |
```json
{
"data": {
"mainAbility": "xxx.xxx.xxx"
},
"actions": {
"routerEventName1": {
"action": "router",
"want": {
"bundleName": "com.example.myapplication",
"abilityName": "com.example.entry.MainAbility"
}
},
"routerEventName2": {
"action": "router",
"want": {
"action": "xxx.intent.action.DIAL",
"uri": "tel:12345678"
}
}
}
}
```
In API version 8, the [featureAbility.getWant](../apis/js-apis-featureAbility.md) API in the **onCreate** method of the **app.js** or **app.ets** file must be called for the **want** parameter to receive related parameters.
- Message event properties
| Selector | Example | Default Value | Description |
| ------ | ------ | ------- | ------------ |
| action | string | message | Event type. |
| params | Object | - | Additional parameter passed during the redirection.|
```json
{
"actions": {
"activeEvent": {
"action": "message",
"params": {}
}
}
}
```
- The following example shows two styles for binding the redirection event and message event:
```html
<!-- xxx.hml -->
<div>
<!-- Regular format -->
<div onclick="activeEvent"></div>
<!-- Abbreviation -->
<div @click="activeEvent"></div>
</div>
```
## Loop Rendering
```html
<!-- xxx.hml -->
<div class="array-container">
<!-- div loop rendering -->
<!-- By default, $item indicates the element in the array, and $idx indicates the index of the element in the array. -->
<div for="{{array}}" tid="id">
<text>{{$item.name}}</text>
</div>
<!-- Define the name for an element variable. -->
<div for="{{value in array}}" tid="id">
<text>{{value.name}}</text>
</div>
<!-- Define an element variable and its index name. -->
<div for="{{(index, value) in array}}" tid="id">
<text>{{value.name}}</text>
</div>
</div>
```
```json
{
"data": {
"array": [
{"id": 1, "name": "jack", "age": 18},
{"id": 2, "name": "tony", "age": 18}
]
}
}
```
The **tid** attribute accelerates the **for** loop and improves the re-rendering efficiency when data in a loop changes. The **tid** attribute specifies the unique ID of each element in the array. If it is not specified, the index of each element in the array is used as the ID. For example, **tid="id"** indicates that the **id** attribute of each element is its unique ID. The **for** loop supports the following statements:
- for="array": **array** is an array object, whose element variable is **$item** by default.
- for="v in array": **v** is a custom element variable, whose index is **$idx** by default.
- for="(i, v) in array": **i** indicates the element index, and **v** indicates the element variable. All elements of the array object will be looped through.
> **NOTE**
> - Each element in the array must have the data attribute specified by **tid**. Otherwise, an exception may occur.
>
> - The attribute specified by **tid** in the array must be unique. Otherwise, performance loss occurs. In the above example, only **id** and **name** can be used as **tid** because they are unique fields.
>
> - The **tid** field does not support expressions.
>
> - Nested **for** loops are not supported.
>
> - When you use the **for** loop, ensure that the objects contained in the array are of the same type.
## Conditional Rendering
There are two ways to implement conditional rendering: **if-elif-else** or **show**.
The **if-elif-else** statements must be used in sibling nodes. Otherwise, the compilation fails. The following example uses both ways to implement conditional rendering:
```html
<!-- xxx.hml -->
<div>
<text if="{{show}}"> Hello-TV </text>
<text elif="{{display}}"> Hello-Wearable </text>
<text else> Hello-World </text>
</div>
```
```json
{
"data": {
"show": false,
"display": true
}
}
```
If **show** is **true**, the node is rendered properly; if it is **false**, the display style will be **none**.
```html
<!-- xxx.hml -->
<text show="{{visible}}"> Hello World </text>
```
```json
{
"data": {
"visible": false
}
}
```
## Logic Control Block
**\<block>** makes loop rendering and conditional rendering more flexible. A **\<block>** will not be compiled as a real component. The **\<block>** supports the **if** attribute only.
```html
<!-- xxx.hml -->
<div>
<block if="{{show}}">
<text>Hello</text>
<text>World</text>
</block>
</div>
```
```json
{
"data": {
"show": true
}
}
```
# Theme Configuration
To configure the theme for a service widget, use the attribute described below.
| Name | Description |
| ------------------ | ----------------------------- |
| app_background | Background color of the widget. |
To configure the theme, create the **resources** folder at the same level as **pages** in the **widget** folder and set the above attribute in the **widget/resources/styles/default.json** file. For example, to configure the default theme of a widget to light gray:
```json
{
"style": {
"app_background": "#dcdcdc"
}
}
```
# Version Compatibility Adaptation
As you incorporate new features into service widgets of your applications, take measures to avoid abnormal display of these features on earlier versions. You can specify the minimum SDK version in the service widget project so that service widgets incorporating new features will not be installed on incompatible systems. You can also follow the instructions in this section to implement forward compatibility during your service widget development.
Configure forward compatibility in the JSON configuration file. Specifically, set the **apiVersion** attribute, which is at the same level as the **data** and **actions** fields in the service widget configuration file. The content defined in **apiVersion** overwrites the original content in **data** based on the current version information.
Example:
Assume that the JS service widget framework supports WebP image sources since API version 9. Then you can implement forward compatibility as follows:
```html
<!-- xxx.hml -->
<div>
<image src="{{imageSrc}}" style="width: 100px;height: 100px;"></image>
</div>
```
JSON configuration file:
```json
{
"data": {
"imageSrc": "defaultSrc.png"
},
"apiVersion": {
"9": {
"imageSrc": "newSrc.webp"
}
}
}
```
The JS service widget development framework selects the most appropriate data based on the application configuration and the current API version.
If the API version is 8 or earlier, the value of **imageSrc** is **defaultSrc.png**.
If the API version is 9, the value of **imageSrc** is **newSrc.webp**.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册