提交 104c2e0c 编写于 作者: H HelloCrease

update docs

Signed-off-by: NHelloCrease <lian15@huawei.com>
上级 be463e33
......@@ -64,7 +64,8 @@ API参考提供了OpenHarmony全量组件和接口的参考文档,可以帮助
内容包括:
- [组件参考(基于TS扩展的声明式开发范式)](reference/arkui-ts/ts-components-summary.md)
- [组件参考(兼容JS的类Web开发范式)](reference/arkui-js/js-components-common-attributes.md)
- [组件参考(兼容JS的类Web开发范式-ArkUI.Full)](arkui-js/Readme-CN.md)
- [组件参考(兼容JS的类Web开发范式-ArkUI.Lite)](arkui-js-lite/Readme-CN.md)
- [JS服务卡片UI组件参考](reference/js-service-widget-ui/js-service-widget-file.md)
- [接口参考(ArkTS及JS API)](reference/apis/development-intro.md)
- 接口参考(Native API)
......
......@@ -3,7 +3,8 @@
- [系统能力SystemCapability使用指南](syscap.md)
- [系统能力SystemCapability列表](syscap-list.md)
- [组件参考(基于ArkTS的声明式开发范式)](arkui-ts/Readme-CN.md)
- [组件参考(兼容JS的类Web开发范式)](arkui-js/Readme-CN.md)
- [组件参考(兼容JS的类Web开发范式-ArkUI.Full)](arkui-js/Readme-CN.md)
- [组件参考(兼容JS的类Web开发范式-ArkUI.Lite)](arkui-js-lite/Readme-CN.md)
- [JS服务卡片UI组件参考](js-service-widget-ui/Readme-CN.md)
- [接口参考(ArkTS及JS API)](apis/Readme-CN.md)
- [错误码参考](errorcodes/Readme-CN.md)
......
# 兼容JS的类Web开发范式(ArkUI.Lite)
- 框架说明
- [文件组织](js-framework-file.md)
- [js标签配置](js-framework-js-tag.md)
- [app.js](js-framework-js-file.md)
- 语法
- [HML语法参考](js-framework-syntax-hml.md)
- [CSS语法参考](js-framework-syntax-css.md)
- [JS语法参考](js-framework-syntax-js.md)
- 组件通用信息
- [通用事件](js-common-events.md)
- [通用属性](js-common-attributes.md)
- [通用样式](js-common-styles.md)
- [动画样式](js-components-common-animation.md)
- [媒体查询](js-components-common-mediaquery.md)
- 容器组件
- [div](js-components-container-div.md)
- [list](js-components-container-list.md)
- [list-item](js-components-container-list-item.md)
- [stack](js-components-container-stack.md)
- [swiper](js-components-container-swiper.md)
- 基础组件
- [chart](js-components-basic-chart.md)
- [image](js-components-basic-image.md)
- [image-animator](js-components-basic-image-animator.md)
- [input](js-components-basic-input.md)
- [marquee](js-components-basic-marquee.md)
- [picker-view](js-components-basic-picker-view.md)
- [progress](js-components-basic-progress.md)
- [qrcode](js-components-basic-qrcode.md)
- [slider](js-components-basic-slider.md)
- [switch](js-components-basic-switch.md)
- [text](js-components-basic-text.md)
- 画布组件
- [canvas组件](js-components-canvas-canvas.md)
- [CanvasRenderingContext2D对象](js-components-canvas-canvasrenderingcontext2d.md)
# 通用属性
## 常规属性
常规属性指的是组件普遍支持的用来设置组件基本标识和外观显示特征的属性。
| 名称 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| id | string | 否 | 组件的唯一标识。 |
| style | string | 否 | 组件的样式声明。 |
| class | string | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 渲染属性
组件普遍支持的用来设置组件是否渲染的属性。
| 名称 | 类型 | 描述 |
| -------- | -------- | -------- |
| for | Array | 根据设置的数据列表,展开当前元素。 |
| if | boolean | 根据设置的boolean值,添加或移除当前元素。 |
| show | boolean | 根据设置的boolean值,显示或隐藏当前元素。 |
> **说明:**
>
> 属性和样式不能混用,不能在属性字段中进行样式设置。
# 通用事件
相对于私有事件,大部分组件都可以绑定如下事件。
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | SwipeEvent | 组件上快速滑动后触发。 |
**表6** SwipeEvent 基础事件对象属性列表(继承BaseEvent)
| 属性 | 类型 | 说明 |
| -------- | -------- | -------- |
| direction | string | 滑动方向,可能值有:<br/>1.&nbsp;left:向左滑动;<br/>2.&nbsp;right:向右滑动;<br/>3.&nbsp;up:向上滑动;<br/>4.&nbsp;down:向下滑动。 |
# 通用样式
组件普遍支持的可以在style或css中设置组件外观样式。
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ---------------------------------- | ---------------------------------------- | ----- | ---- | ---------------------------------------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
> **说明:**
>
> 通用样式都不是必填项。
>
> 目前,样式支持的颜色格式如下:
> - rgb(255, 255, 255)
>
> - rgba(255, 255, 255, 1.0)
>
> - HEX格式:\#rrggbb,\#aarrggbb
>
> - 枚举格式:black,white等,详见 **表1** 当前支持的颜色枚举。Script脚本中不支持枚举格式。
**表1** 当前支持的颜色枚举
| 枚举名称 | 对应颜色 | 颜色 |
| -------------------- | -------- | ---------------------------------------- |
| 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) |
# chart
图表组件,用于呈现线形图、柱状图界面。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 必填 | 描述 |
| -------- | ------------------------- | ---- | ---------------------------------------- |
| type | string | 否 | 设置图表类型(不支持动态修改),可选项有:<br/>-&nbsp;bar:柱状图。<br/>-&nbsp;line:线形图。<br>默认值:line |
| options | ChartOptions | 是 | 图表参数设置,柱状图和线形图必须设置参数设置。可以设置x轴、y轴的最小值、最大值、刻度数、是否显示,线条宽度、是否平滑等。(不支持动态修改) |
| datasets | Array&lt;ChartDataset&gt; | 是 | 数据集合,柱状图和线形图必须设置数据集合。可以设置多条数据集及其背景色。 |
| id | string | 否 | 组件的唯一标识。 |
| style | string | 否 | 组件的样式声明。 |
| class | string | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
**表1** ChartOptions
| 名称 | 类型 | 必填 | 描述 |
| ------ | ----------- | ---- | ---------------------------------------- |
| xAxis | ChartAxis | 是 | x轴参数设置。可以设置x轴最小值、最大值、刻度数以及是否显示。 |
| yAxis | ChartAxis | 是 | y轴参数设置。可以设置y轴最小值、最大值、刻度数以及是否显示。 |
| series | ChartSeries | 否 | 数据序列参数设置。可以设置:<br>1. 线的样式,如线宽、是否平滑;<br>2. 设置线最前端位置白点的样式和大小。<br/>**说明:**<br>仅线形图支持。 |
**表2** ChartDataset
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| --------------------------- | ------------------- | -------- | ---- | -------------------- |
| backgroundColor(deprecated) | &lt;color&gt; | \#ff6384 | 否 | 设置线或柱的颜色(不推荐使用)。 |
| strokeColor | &lt;color&gt; | \#ff6384 | 否 | 线条颜色。仅线形图支持。 |
| fillColor | &lt;color&gt; | \#ff6384 | 否 | 填充颜色。线形图表示填充的渐变颜色。 |
| data | Array&lt;number&gt; | - | 是 | 设置绘制线或柱中的点集。 |
| gradient | boolean | false | 否 | 设置是否显示填充渐变颜色。仅线形图支持。 |
**表3** ChartAxis
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | ------------- | -------- | ---- | ---------------------------------------- |
| min | number | 0 | 否 | 轴的最小值。<br/>不支持负数。仅线形图支持。 |
| max | number | 100 | 否 | 轴的最大值。<br/>不支持负数。仅线形图支持。 |
| axisTick | number | 10 | 否 | 轴显示的刻度数量。<br/>**说明:**<br/>仅支持1~20,且具体显示的效果与如下计算值有关(图的宽度所占的像素/(max-min))。<br/>因轻量级智能穿戴为整型运行,在除不尽的情况下会有误差产生,具体的表现形式是x轴末尾可能会空出一段。<br/>在柱状图中,每组数据显示的柱子数量与刻度数量一致,且柱子显示在刻度处。 |
| display | boolean | false | 否 | 是否显示轴。 |
| color | &lt;color&gt; | \#c0c0c0 | 否 | 轴颜色。 |
**表4** ChartSeries
| 名称 | 类型 | 必填 | 描述 |
| ----------- | -------------- | ---- | -------------------- |
| lineStyle | ChartLineStyle | 否 | 线样式设置,如线宽、是否平滑。 |
| headPoint | PointStyle | 否 | 线最前端位置白点的样式和大小。 |
| topPoint | PointStyle | 否 | 最高点的样式和大小。 |
| bottomPoint | PointStyle | 否 | 最低点的样式和大小。 |
| loop | ChartLoop | 否 | 设置屏幕显示满时,是否需要重头开始绘制。 |
**表5** ChartLineStyle
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ------ | -------------- | ----- | ---- | ----- |
| width | &lt;length&gt; | 1px | 否 | 线宽设置。 |
| smooth | boolean | false | 否 | 是否平滑。 |
**表6** PointStyle
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ----------- | -------------- | -------- | ---- | ---------------------------------- |
| shape | string | circle | 否 | 高亮点的形状。可选值为:<br/>-&nbsp;circle:圆形。 |
| size | &lt;length&gt; | 5px | 否 | 高亮点的大小。 |
| strokeWidth | &lt;length&gt; | 1px | 否 | 边框宽度 |
| strokeColor | &lt;color&gt; | \#ff0000 | 否 | 边框颜色。 |
| fillColor | &lt;color&gt; | \#ff0000 | 否 | 填充颜色。 |
| display | boolean | true | 否 | 是否高亮显示。 |
**表7** ChartLoop
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ------ | -------------- | ---- | ---- | ---------------------------------------- |
| margin | &lt;length&gt; | 1 | 否 | 擦除点的个数(最新绘制的点与最老的点之间的横向距离)。注意:轻量设备margin和topPoint/bottomPoint/headPoint同时使用时,有概率出现point正好位于擦除区域的情况,导致point不可见,因此不建议同时使用。 |
## 方法
| 方法 | 参数 | 描述 |
| ------ | ---------------------------------------- | ---------------------------------------- |
| append | {<br/>serial:&nbsp;number,&nbsp;//&nbsp;设置要更新的线形图数据下标<br/>data:&nbsp;Array&lt;number&gt;,&nbsp;//&nbsp;设置新增的数据<br/>} | 往已有的数据序列中动态添加数据,根据serial指定目标序列,serial为datasets数组的下标,从0开始。注意:不会更新datasets[index].data。仅线形图支持,按横坐标加1递增(与xAxis&nbsp;min/max设置相关)。 |
## 事件
| 名称 | 参数 | 描述 |
| ------------------ | --------------------------------- | ----------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ---------------------------------- | ---------------------------------------- | ----- | ---- | ---------------------------------------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
1. 线形图
```html
<!-- xxx.hml -->
<div class="container">
<chart class="chart" type="line" ref="linechart" options="{{lineOps}}" datasets="{{lineData}}"></chart>
<input class="button" type="button" value="Add data" onclick="addData"/>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 454px;
height: 454px;
background-color: white;
}
.chart {
width: 300px;
height: 300px;
}
.button {
width: 280px;
border-radius: 0px;
}
```
```js
// xxx.js
export default {
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: 10,
strokeWidth: 5,
fillColor: '#ffffff',
strokeColor: '#007aff',
display: true,
},
loop: {
margin: 2,
gradient: true,
}
}
},
},
addData() {
this.$refs.linechart.append({
serial: 0,
data: [Math.floor(Math.random() * 400) + 400]
})
}
}
```
![lite_line](figures/lite_line.PNG)
2. 柱状图
```html
<!-- xxx.hml -->
<div class="container">
<chart class="chart" type="bar" id="bar-chart" options="{{barOps}}" datasets="{{barData}}"></chart>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 454px;
height: 454px;
background-color: white;
}
.chart {
width: 300px;
height: 300px;
}
```
```js
// xxx.js
export default {
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,
},
},
}
}
```
![lite_bar](figures/lite_bar.PNG)
# image-animator
图片帧动画播放器。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| --------------------- | -------------------------- | -------- | ---- | ---------------------------------------- |
| images | Array&lt;ImageFrame&gt; | - | 是 | 设置图片帧信息集合。每一帧的帧信息包含图片路径、图片大小和图片位置信息。目前支持以下图片格式:png、jpg和bmp。ImageFrame的详细说明请见表1。<br/>**说明:**<br/>使用时需要使用数据绑定的方式,如images&nbsp;=&nbsp;{{images}},js中声明相应变量:images:&nbsp;[{src:&nbsp;"/common/heart-rate01.png"},&nbsp;{src:&nbsp;"/common/heart-rate02.png"}]。 |
| iteration | number&nbsp;\|&nbsp;string | infinite | 否 | 设置帧动画播放次数。number表示固定次数,infinite枚举表示无限次数播放。 |
| reverse | boolean | false | 否 | 设置播放顺序。false表示从第1张图片播放到最后1张图片;&nbsp;true表示从最后1张图片播放到第1张图片。 |
| fixedsize | boolean | true | 否 | 设置图片大小是否固定为组件大小。&nbsp;true表示图片大小与组件大小一致,此时设置图片的width&nbsp;、height&nbsp;、top&nbsp;和left属性是无效的。false表示每一张图片的&nbsp;width&nbsp;、height&nbsp;、top和left属性都要单独设置。 |
| duration | string | - | 是 | 设置单次播放时长。单位支持[s(秒)\|ms(毫秒)],默认单位为ms。&nbsp;duration为0时,不播放图片。&nbsp;值改变只会在下一次循环开始时生效。 |
| fillmode<sup>5+</sup> | string | forwards | 否 | 指定帧动画执行结束后的状态。可选项有:<br/>-&nbsp;none:恢复初始状态。<br/>-&nbsp;forwards:保持帧动画结束时的状态(在最后一个关键帧中定义)。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
**表1** ImageFrame说明
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ------ | -------------- | ---- | ---- | ---------------- |
| src | &lt;uri&gt; | - | 是 | 图片路径。 |
| width | &lt;length&gt; | 0 | 否 | 图片宽度。 |
| height | &lt;length&gt; | 0 | 否 | 图片高度。 |
| top | &lt;length&gt; | 0 | 否 | 图片相对于组件左上角的纵向坐标。 |
| left | &lt;length&gt; | 0 | 否 | 图片相对于组件左上角的横向坐标。 |
## 事件
| 名称 | 参数 | 描述 |
| ------------------ | --------------------------------- | ----------- |
| stop | - | 帧动画结束时触发。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ---------------------------------- | ---------------------------------------- | ----- | ---- | ---------------------------------------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 方法
| 名称 | 参数 | 描述 |
| -------- | ---- | ---------------------------------------- |
| start | - | 开始播放图片帧动画。再次调用,重新从第1帧开始播放。 |
| pause | - | 暂停播放图片帧动画。 |
| stop | - | 停止播放图片帧动画。 |
| resume | - | 继续播放图片帧。 |
| getState | - | 获取播放状态。可能值有:<br/>-&nbsp;playing:播放中<br/>-&nbsp;paused:已暂停<br/>-&nbsp;stopped:已停止。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<image-animator class="animator" ref="animator" images="{{frames}}" duration="1s" />
<div class="btn-box">
<input class="btn" type="button" value="start" @click="handleStart" />
<input class="btn" type="button" value="stop" @click="handleStop" />
<input class="btn" type="button" value="pause" @click="handlePause" />
<input class="btn" type="button" value="resume" @click="handleResume" />
</div>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.animator {
width: 70px;
height: 70px;
}
.btn-box {
width: 264px;
height: 120px;
flex-wrap: wrap;
justify-content: space-around;
align-items: center;
}
.btn {
border-radius: 8px;
width: 120px;
margin-top: 8px;
}
```
```js
//xxx.js
export default {
data: {
frames: [
{
src: "/common/asserts/heart78.png",
},
{
src: "/common/asserts/heart79.png",
},
{
src: "/common/asserts/heart80.png",
},
{
src: "/common/asserts/heart81.png",
},
{
src: "/common/asserts/heart82.png",
},
{
src: "/common/asserts/heart83.png",
},
{
src: "/common/asserts/heart84.png",
},
{
src: "/common/asserts/heart85.png",
},
{
src: "/common/asserts/heart86.png",
},
{
src: "/common/asserts/heart87.png",
},
{
src: "/common/asserts/heart88.png",
},
{
src: "/common/asserts/heart89.png",
},
{
src: "/common/asserts/heart90.png",
},
{
src: "/common/asserts/heart91.png",
},
{
src: "/common/asserts/heart92.png",
},
{
src: "/common/asserts/heart93.png",
},
{
src: "/common/asserts/heart94.png",
},
{
src: "/common/asserts/heart95.png",
},
{
src: "/common/asserts/heart96.png",
},
],
},
handleStart() {
this.$refs.animator.start();
},
handlePause() {
this.$refs.animator.pause();
},
handleResume() {
this.$refs.animator.resume();
},
handleStop() {
this.$refs.animator.stop();
},
};
```
![image-animator](figures/image-animator.gif)
# image
图片组件,用来渲染展示图片。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- |
| src | string | 否 | <br/>图片的路径,支持的图片格式包括png、jpg。 |
| id | string | 否 | 组件的唯一标识。 |
| style | string | 否 | 组件的样式声明。 |
| class | string | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<image src="common/images/hw_right.png" style="width: 300px; height: 300px; border-color: red; border-width: 2px;">
</image>
</div>
```
```css
/* xxx.css */
.container {
justify-content: center;
align-items: center;
flex-direction: column;
width: 100%;
height: 100%;
}
```
![image](figures/image.png)
\ No newline at end of file
# input
交互式组件,包括单选框,多选框,按钮。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | <br/>button | 否 | input组件类型,可选值为button,checkbox,radio。<br/><br/>button,checkbox,radio不支持动态修改。可选值定义如下:<br/>-&nbsp;button:定义可点击的按钮;<br/>-&nbsp;checkbox:定义多选框;<br/>-&nbsp;radio:定义单选按钮,允许在多个拥有相同name值的选项中选中其中一个; |
| checked | boolean | false | 否 | 当前组件是否选中,仅type为checkbox和radio生效。 |
| name | string | - | 否 | input组件的名称。 |
| value | string | - | 否 | input组件的value值,当类型为radio时必填且相同name值的选项该值唯一。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
- 当input类型为checkbox、radio时,支持如下事件:
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| change | {&nbsp;checked:true&nbsp;\|&nbsp;false&nbsp;} | checkbox多选框或radio单选框的checked状态发生变化时触发该事件。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
- 当input类型为button时,支持如下事件:
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#ffffff | 否 | 按钮的文本颜色。 |
| font-size | &lt;length&gt; | 30px | 否 | 按钮的文本尺寸。 |
| width | &lt;length&gt; | - | 否 | type为button时,默认值为100px。 |
| height | &lt;length&gt; | - | 否 | type为button时,默认值为50px。 |
| font-family | string | SourceHanSansSC-Regular | 否 | 字体。目前仅支持SourceHanSansSC-Regular&nbsp;字体。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
1. type为button
```html
<!-- xxx.hml -->
<div class="div-button">
<input class="button" type="button" value="Input-Button"></input>
</div>
```
```css
/* xxx.css */
.div-button {
flex-direction: column;
align-items: center;
width: 100%;
height: 100%;
}
.button {
margin-top: 30px;
width: 280px;
}
```
![input-type-button](figures/input-type-button.png)
2. type为checkbox
```html
<!-- xxx.hml -->
<div class="content">
<input onchange="checkboxOnChange" checked="true" type="checkbox"></input>
<text class="text">{{text}}</text>
</div>
```
```css
/* xxx.css */
.content{
width: 100%;
height: 100%;
flex-direction: column;
align-items: center;
justify-content: center;
}
.text{
font-size: 30px;
text-align: center;
width: 200px;
margin-top: 20px;
height: 100px;
}
```
```javascript
// xxx.js
export default {
data: {
text: "text"
},
checkboxOnChange(e) {
this.text = e.checked;
}
}
```
![input-type-checkbox](figures/input-type-checkbox.gif)
3. type为radio
```html
<!-- xxx.hml -->
<div class="container">
<div class="item">
<input type="radio" checked="true" name="radioSample" value="radio1" onchange="onRadioChange"></input>
<text class="text">radio1</text>
</div>
<div class="item">
<input type="radio" checked="false" name="radioSample" value="radio2" onchange="onRadioChange"></input>
<text class="text">radio2</text>
</div>
<div class="item">
<input type="radio" checked="false" name="radioSample" value="radio3" onchange="onRadioChange"></input>
<text class="text">radio3</text>
</div>
</div>
```
```css
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
flex-direction: column;
}
.item {
width: 50%;
height: 30%;
justify-content: center;
}
.text {
margin-top: 25%;
font-size: 30px;
text-align: center;
width: 200px;
height: 100px;
}
```
![input-type-radio](figures/input-type-radio.gif)
\ No newline at end of file
# marquee
跑马灯组件,用于展示一段单行滚动的文字。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| scrollamount | number | 6 | 否 | 跑马灯每次滚动时移动的最大长度。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#ffffff<br/><br/><br/> | 否 | 设置跑马灯中文字的文本颜色。 |
| font-size | &lt;length&gt; | <br/>30 | 否 | 设置跑马灯中文字的文本尺寸。 |
| font-family | string | <br/><br/>SourceHanSansSC-Regular | 否 | <br/><br/>字体。目前仅支持SourceHanSansSC-Regular&nbsp;字体。 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<marquee class="customMarquee" scrollamount="{{scrollAmount}}">{{marqueeCustomData}}</marquee>
<text class="text" onclick="addSpeed">speed+</text>
<text class="text" onclick="downSpeed">speed-</text>
<text class="text" onclick="changeData">changeData</text>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
width: 100%;
height: 100%;
flex-direction: column;
align-items: center;
}
.customMarquee {
width: 50%;
height: 80px;
padding: 10px;
margin: 20px;
border-width: 4px;
border-color: #ffffff;
border-radius: 20px;
font-size: 38px;
}
.text {
font-size: 30px;
text-align: center;
width: 30%;
height: 10%;
margin-top: 5%;
background-color: #f2f2f2;
border-radius: 40px;
color: #0d81f2;
}
```
```javascript
// xxx.js
export default {
data: {
scrollAmount: 30,
marqueeCustomData: 'Custom marquee Custom marquee Custom marquee'
},
addSpeed() {
this.scrollAmount++;
},
downSpeed() {
this.scrollAmount--;
},
changeData() {
this.marqueeCustomData = 'Change Data Change Data Change Data';
}
}
```
![marquee](figures/marquee.gif)
\ No newline at end of file
# picker-view
嵌入页面的滑动选择器。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | text | 否 | 设置滑动选择器的类型,该属性不支持动态修改,可选项有:<br/>-&nbsp;text:文本选择器。<br/>-&nbsp;time:时间选择器。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
文本选择器:type=text
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| range | Array | - | 否 | 设置文本选择器的取值范围。<br/>使用时需要使用数据绑定的方式,如range&nbsp;=&nbsp;{{data}},js中声明相应变量:data:["15",&nbsp;"20",&nbsp;"25"]。 |
| selected | string | 0 | 否 | 设置文本选择器的默认选择值,该值需要为range的索引。 |
时间选择器:type=time
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| selected | string | 00:00 | 否 | 设置时间选择器的默认取值,格式为&nbsp;HH:mm;<br/> |
## 事件
type=text:
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| change | {&nbsp;newValue:&nbsp;newValue,&nbsp;newSelected:&nbsp;newSelected&nbsp;} | 文本选择器选定值后触发该事件。 |
type=time:
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| change | {&nbsp;hour:&nbsp;hour,&nbsp;minute:&nbsp;minute} | 时间选择器选定值后触发该事件。<br/> |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#808080<br/> | 否 | 候选项字体颜色。 |
| font-size | &lt;length&gt; | 30px<br/> | 否 | 候选项字体尺寸,类型length,单位px。 |
| selected-color | &lt;color&gt; | \#ffffff<br/> | 否 | 选中项字体颜色。 |
| selected-font-size | &lt;length&gt; | 38px<br/> | 否 | 选中项字体尺寸,类型length,单位px。 |
| selected-font-family | string | HYQiHei-65S | 否 | 选中项字体类型。 |
| font-family | string | <br/>HYQiHei-65S | 否 | 选项字体类型。 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container" @swipe="handleSwipe">
<text class="title">
Selected:{{time}}
</text>
<picker-view class="time-picker" type="time" selected="{{defaultTime}}" @change="handleChange"></picker-view>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.title {
font-size: 30px;
text-align: center;
}
.time-picker {
width: 500px;
height: 400px;
margin-top: 20px;
}
```
```js
/* xxx.js */
export default {
data: {
defaultTime: "",
time: "",
},
onInit() {
this.defaultTime = this.now();
},
handleChange(data) {
this.time = this.concat(data.hour, data.minute);
},
now() {
const date = new Date();
const hours = date.getHours();
const minutes = date.getMinutes();
return this.concat(hours, minutes);
},
fill(value) {
return (value > 9 ? "" : "0") + value;
},
concat(hours, minutes) {
return `${this.fill(hours)}:${this.fill(minutes)}`;
},
}
```
![picker-view](figures/picker-view.png)
\ No newline at end of file
# progress
进度条,用于显示内容加载或操作处理进度。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| type | string | horizontal | 否 | 设置进度条的类型,该属性不支持动态修改,可选值为:<br/>-&nbsp;horizontal:线性进度条;<br/>-&nbsp;arc:弧形进度条。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
不同类型的进度条还支持不同的属性:
- 类型为horizontal时,支持如下属性:
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | 否 | 当前进度。取值范围为0-100。 |
- 类型为arc时,支持如下属性:
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| percent | number | 0 | 否 | 当前进度。取值范围为0-100。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
- type为horizontal,支持如下样式:
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ------------ | -------------- | ---------------------------------------------- | ---- | ------------------ |
| color | &lt;color&gt; | \#6b9ac7 | 否 | 设置进度条的颜色。 |
| stroke-width | &lt;length&gt; | 32<sup>1-4&nbsp;</sup>\|&nbsp;4<sup>5+</sup>px | 否 | 设置进度条的宽度。 |
- type为arc,支持如下样式:
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ---------------- | -------------- | ------ | ---- | ------------------------------------------------------------ |
| color | &lt;color&gt; | - | 否 | 弧形进度条的颜色。 |
| background-color | &lt;color&gt; | - | 否 | 弧形进度条的背景色。 |
| stroke-width | &lt;length&gt; | - | 否 | 弧形进度条的宽度。<br/>进度条宽度越大,进度条越靠近圆心。即进度条始终在半径区域内。 |
| start-angle | &lt;deg&gt; | 240 | 否 | 弧形进度条起始角度,以时钟0点为基线。范围为0到360(顺时针)。 |
| total-angle | &lt;deg&gt; | 240 | 否 | 弧形进度条总长度,范围为-360到360,负数标识起点到终点为逆时针。 |
| center-x | &lt;length&gt; | - | 否 | 弧形进度条中心位置,(坐标原点为组件左上角顶点)。该样式需要和center-y和radius一起。 |
| center-y | &lt;length&gt; | - | 否 | 弧形进度条中心位置,(坐标原点为组件左上角顶点)。该样式需要和center-x和radius一起。 |
| radius | &lt;length&gt; | - | 否 | 弧形进度条半径,该样式需要和center-x和center-y一起。 |
除上述样式之外,还支持如下样式:
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<progress type="horizontal" percent="{{horizontalVal}}" style="height: 10%;width: 40%;" onclick = "changeHorizontal"></progress>
<progress type="arc" class="min-progress" percent="{{arcVal}}" on:click="changeArc"></progress>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
height: 100%;
width: 100%;
align-items: center;
}
.min-progress {
width: 300px;
height: 300px;
}
```
```javascript
// xxx.js
export default {
data: {
arcVal: 0,
horizontalVal: 0
},
changeArc() {
this.arcVal+= 10;
},
changeHorizontal() {
this.horizontalVal+= 10;
}
}
```
![progress](figures/progress.png)
\ No newline at end of file
# qrcode
生成并显示二维码。
> **说明:**
>
> 该组件从从API version 5 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| value | string | - | 是 | 用来生成二维码的内容。最大长度为256。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#000000 | 否 | 二维码颜色 |
| background-color | &lt;color&gt; | \#ffffff | 否 | 二维码背景颜色 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
> **说明:**
> - width和height不一致时,以二者最小值作为二维码的边长。且最终生成的二维码居中显示;
>
>- width和height的最小值为200px。
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<qrcode value="{{qr_value}}" class="qrCode" style="color: {{qr_color}};background-color: {{qr_bcol}};"></qrcode>
<input type="button" onclick="changeColor" class="button">Color</input>
<input type="button" onclick="changeBackgroundColor" class="button">BackgroundColor</input>
<input type="button" onclick="changeColor" class="button">Value</input>
</div>
```
```css
/* xxx.css */
.container {
width: 100%;
height: 100%;
flex-direction: column;
justify-content: center;
align-items: center;
}
.qrCode {
width: 200px;
height: 200px;
}
.button {
width: 30%;
height: 10%;
margin-top: 5%;
}
```
```javascript
// xxx.js
export default {
data: {
qr_col: '#87ceeb',
qr_bcol: '#f0ffff',
qr_value: 'value'
},
changeColor() {
if (this.qr_col == '#87ceeb') {
this.qr_col = '#fa8072';
} else {
this.qr_col = '#87ceeb';
}
},
changeBackgroundColor() {
if (this.qr_bcol == '#f0ffff') {
this.qr_bcol = '#ffffe0';
} else {
this.qr_bcol = '#f0ffff';
}
},
changeValue() {
if (this.qr_value == 'value') {
this.qr_value = 'change';
} else {
this.qr_value = 'value';
}
}
}
```
![qrcode](figures/qrcode.gif)
\ No newline at end of file
# slider
滑动条组件,用来快速调节设置值,如音量、亮度等。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ----- | ------ | ---- | ---- | ---------------------------------------- |
| min | number | 0 | 否 | 滑动选择器的最小值。 |
| max | number | 100 | 否 | 滑动选择器的最大值。 |
| value | number | 0 | 否 | 滑动选择器的初始值。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| ------------------ | --------------------------------- | -------------- |
| change | ChangeEvent | 选择值发生变化时触发该事件。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
**表1** ChangeEvent
| 属性 | 类型 | 说明 |
| ---------------------------------------- | ------ | ------------- |
| progress<sup>(deprecated<sup>5+</sup>)</sup> | string | 当前slider的进度值。 |
| value<sup>5+</sup> | number | 当前slider的进度值。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ---------------------------------- | ---------------------------------------- | -------- | ---- | ---------------------------------------- |
| color | &lt;color&gt; | \#000000 | 否 | 滑动条的背景颜色。 |
| selected-color | &lt;color&gt; | \#ffffff | 否 | 滑动条的已选择颜色。 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<text>slider start value is {{startValue}}</text>
<text>slider current value is {{currentValue}}</text>
<text>slider end value is {{endValue}}</text>
<slider min="0" max="100" value="{{value}}" onchange="setvalue" style="width: 20%;height: 10%"></slider>
</div>
```
```css
/* xxx.css */
.container {
flex-direction: column;
justify-content: center;
align-items: center;
width: 100%;
height: 100%;
}
```
```javascript
// xxx.js
export default {
data: {
value: 0,
startValue: 0,
currentValue: 0,
endValue: 100,
},
setvalue(e) {
this.currentValue = e.value;
}
}
```
![slider](figures/slider.png)
\ No newline at end of file
# switch
开关选择器,通过开关,开启或关闭某个功能。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| checked | boolean | false | 否 | 是否选中。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| change | {&nbsp;checked:&nbsp;checkedValue&nbsp;} | 选中状态改变时触发该事件。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<div class="box">
<switch checked="true" @change="switchChange"></switch>
<text>{{title}}</text>
</div>
</div>
```
```css
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
}
.box{
width: 18%;
height: 25%;
flex-direction:column;
justify-content: center;
align-items: center;
}
```
```javascript
// xxx.js
export default {
data: {
title: 'on'
},
switchChange(e){
console.log(e.checked);
if(e.checked){
this.title="on"
}else{
this.title="off"
}
}
}
```
![switch](figures/switch.gif)
\ No newline at end of file
# text
文本,用于呈现一段信息。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| color | &lt;color&gt; | \#ffffff | 否 | 设置文本的颜色。 |
| font-size | &lt;length&gt; | 30px | 否 | 设置文本的尺寸。<br/> |
| letter-spacing | &lt;length&gt; | 2px | 否 | 设置文本的字符间距。 |
| text-align | string | left | 否 | 设置文本的文本对齐方式,可选值为:<br/>-&nbsp;left:文本左对齐;<br/>-&nbsp;center:文本居中对齐;<br/>-&nbsp;right:文本右对齐; |
| text-overflow | string | clip | 否 | 可选值为:<br/>-&nbsp;clip:将文本根据父容器大小进行裁剪显示;<br/>-&nbsp;ellipsis:根据父容器大小显示,显示不下的文本用省略号代替。 |
| font-family | string | SourceHanSansSC-Regular | 否 | 字体。目前仅支持SourceHanSansSC-Regular&nbsp;字体。 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0px | 否 | 设置组件自身的宽度。<br/>单位:px<br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0px | 否 | 设置组件自身的高度。<br/>单位:px<br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
| line-height<sup>10+</sup> | number | 0px | 否 | 设置文本的行高。<br/>单位:px<br/>未设置时文本行高默认为适应性行高。 |
## 示例
```html
<!-- xxx.hml -->
<div class="container">
<text class="title">
Hello {{ title }}
</text>
</div>
```
```CSS
/* xxx.css */
.container {
width: 100%;
height: 100%;
justify-content: center;
align-items: center;
}
.title {
width: 100px;
font-size: 30px;
text-align: center;
color: red;
}
```
```javascript
// xxx.js
export default {
data: {
title: ""
},
onInit() {
this.title = "World";
}
}
```
![text](figures/text.png)
\ No newline at end of file
# canvas组件
提供画布组件。用于自定义绘制图形。
> **说明:**
>
> 该组件从从API version 5 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
不支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 方法
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| getContext | string&nbsp; | 获取canvas绘图上下文,参数仅支持“2d”,返回值为2D绘制对象,该对象提供具体的2D绘制操作。详见[CanvasRenderingContext2D对象](js-components-canvas-canvasrenderingcontext2d.md)章节。 |
# CanvasRenderingContext2D对象
使用CanvasRenderingContext2D在canvas画布组件上进行绘制,绘制对象可以是矩形、文本。
**示例:**
```html
<!-- xxx.hml -->
<canvas ref="canvas1" style="width: 200px; height: 150px; background-color: #ffff00;"></canvas>
<input type="button" style="width: 180px; height: 60px;" value="fillStyle" onclick="handleClick" />
```
```javascript
// xxx.js
export default {
handleClick() {
const el = this.$refs.canvas1;
const ctx = el.getContext('2d');
ctx.beginPath();
ctx.arc(100, 75, 50, 0, 6.28);
ctx.stroke();
},
}
```
![zh-cn_image_0000001431548113](figures/zh-cn_image_0000001431548113.png)
## fillRect()
填充一个矩形。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| x | number | 指定矩形左上角点的x坐标。 |
| y | number | 指定矩形左上角点的y坐标。 |
| width | number | 指定矩形的宽度。 |
| height | number | 指定矩形的高度。 |
**示例:**
![zh-cn_image_0000001431388525](figures/zh-cn_image_0000001431388525.png)
```javascript
ctx.fillRect(20, 20, 200, 150);
```
## fillStyle
指定绘制的填充色。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| color | &lt;color&gt; | 设置填充区域的颜色。 |
**示例:**
![zh-cn_image_0000001431388505](figures/zh-cn_image_0000001431388505.png)
```javascript
ctx.fillStyle = '#0000ff';
ctx.fillRect(20, 20, 150, 100);
```
## strokeRect()
绘制具有边框的矩形,矩形内部不填充。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| x | number | 指定矩形的左上角x坐标。 |
| y | number | 指定矩形的左上角y坐标。 |
| width | number | 指定矩形的宽度。 |
| height | number | 指定矩形的高度。 |
**示例:**
![zh-cn_image_0000001381268264](figures/zh-cn_image_0000001381268264.png)
```javascript
ctx.strokeRect(30, 30, 200, 150);
```
## fillText()
绘制填充类文本。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| text | string | 需要绘制的文本内容。 |
| x | number | 需要绘制的文本的左下角x坐标。 |
| y | number | 需要绘制的文本的左下角y坐标。 |
**示例:**
![zh-cn_image_0000001431548109](figures/zh-cn_image_0000001431548109.png)
```javascript
ctx.font = '35px sans-serif';
ctx.fillText("Hello World!", 20, 60);
```
## lineWidth
指定绘制线条的宽度值。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| lineWidth | number | 设置绘制线条的宽度。 |
**示例:**
![zh-cn_image_0000001431548121](figures/zh-cn_image_0000001431548121.png)
```javascript
ctx.lineWidth = 5;
ctx.strokeRect(25, 25, 85, 105);
```
## strokeStyle
设置描边的颜色。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| color | &lt;color&gt; | 指定描边使用的颜色 |
**示例:**
![zh-cn_image_0000001380789172](figures/zh-cn_image_0000001380789172.png)
```javascript
ctx.lineWidth = 10;
ctx.strokeStyle = '#0000ff';
ctx.strokeRect(25, 25, 155, 105);
```
### stroke()<sup>5+</sup>
进行边框绘制操作。
**示例:**
![zh-cn_image_0000001431388513](figures/zh-cn_image_0000001431388513.png)
```javascript
ctx.moveTo(25, 25);
ctx.lineTo(25, 105);
ctx.strokeStyle = 'rgb(0,0,255)';
ctx.stroke();
```
### beginPath()<sup>5+</sup>
创建一个新的绘制路径。
**示例:**
![zh-cn_image_0000001431548125](figures/zh-cn_image_0000001431548125.png)
```javascript
ctx.beginPath();
ctx.lineWidth = '6';
ctx.strokeStyle = '#0000ff';
ctx.moveTo(15, 80);
ctx.lineTo(280, 160);
ctx.stroke();
```
### moveTo()<sup>5+</sup>
路径从当前点移动到指定点。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| x | number | 指定位置的x坐标。 |
| y | number | 指定位置的y坐标。 |
**示例:**
![zh-cn_image_0000001431388529](figures/zh-cn_image_0000001431388529.png)
```javascript
ctx.beginPath();
ctx.moveTo(10, 10);
ctx.lineTo(280, 160);
ctx.stroke();
```
### lineTo()<sup>5+</sup>
从当前点到指定点进行路径连接。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| x | number | 指定位置的x坐标。 |
| y | number | 指定位置的y坐标。 |
**示例:**
![zh-cn_image_0000001431148365](figures/zh-cn_image_0000001431148365.png)
```javascript
ctx.beginPath();
ctx.moveTo(10, 10);
ctx.lineTo(280, 160);
ctx.stroke();
```
### closePath()<sup>5+</sup>
结束当前路径形成一个封闭路径。
**示例:**
![zh-cn_image_0000001381268284](figures/zh-cn_image_0000001381268284.png)
```javascript
ctx.beginPath();
ctx.moveTo(30, 30);
ctx.lineTo(110, 30);
ctx.lineTo(70, 90);
ctx.closePath();
ctx.stroke();
```
## font
设置文本绘制中的字体样式。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| value | string | 字体样式支持:sans-serif,&nbsp;serif,&nbsp;monospace,该属性默认值为30px&nbsp;HYQiHei-65S。 |
**示例:**
![zh-cn_image_0000001381108328](figures/zh-cn_image_0000001381108328.png)
```javascript
ctx.font = '30px sans-serif';
ctx.fillText("Hello World", 20, 60);
```
## textAlign
设置文本绘制中的文本对齐方式。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| align | string | 可选值为:<br/>-&nbsp;left(默认):文本左对齐;<br/>-&nbsp;right:文本右对齐;<br/>-&nbsp;center:文本居中对齐; |
**示例:**
![zh-cn_image_0000001431388517](figures/zh-cn_image_0000001431388517.png)
```javascript
ctx.strokeStyle = '#0000ff';
ctx.moveTo(140, 10);
ctx.lineTo(140, 160);
ctx.stroke();
ctx.font = '18px sans-serif';
// Show the different textAlign values
ctx.textAlign = 'left';
ctx.fillText('textAlign=left', 140, 100);
ctx.textAlign = 'center';
ctx.fillText('textAlign=center',140, 120);
ctx.textAlign = 'right';
ctx.fillText('textAlign=right',140, 140);
```
## arc()<sup>5+</sup>
绘制弧线路径。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| x | number | 弧线圆心的x坐标值。 |
| y | number | 弧线圆心的y坐标值。 |
| radius | number | 弧线的圆半径。 |
| startAngle | number | 弧线的起始弧度。 |
| endAngle | number | 弧线的终止弧度。 |
| anticlockwise | boolean | 是否逆时针绘制圆弧。 |
**示例:**
![zh-cn_image_0000001381108320](figures/zh-cn_image_0000001381108320.png)
```javascript
ctx.beginPath();
ctx.arc(100, 75, 50, 0, 6.28);
ctx.stroke();
```
### rect()<sup>5+</sup>
创建矩形路径。
**参数:**
| 参数 | 类型 | 描述 |
| -------- | -------- | -------- |
| x | number | 指定矩形的左上角x坐标值。 |
| y | number | 指定矩形的左上角y坐标值。 |
| width | number | 指定矩形的宽度。 |
| height | number | 指定矩形的高度。 |
**示例:**
![zh-cn_image_0000001381108312](figures/zh-cn_image_0000001381108312.png)
```javascript
ctx.rect(20, 20, 100, 100); // Create a 100*100 rectangle at (20, 20)
ctx.stroke(); // Draw it
```
# 动画样式
组件普遍支持的可以在style或css中设置的动态的旋转、平移、缩放效果。
| 名称 | 类型 | 默认值 | 描述 |
| ------------------------- | ---------------------------------- | ----------- | ---------------------------------------- |
| transform | string | - | 详见表1。 |
| animation-name | string | - | 指定\@keyframes,详见表2。 |
| animation-delay | &lt;time&gt; | 0 | 定义动画播放的延迟时间。支持的单位为[s(秒)\|ms(毫秒)&nbsp;],默认单位为ms,格式为:1000ms或1s。 |
| animation-duration | &lt;time&gt; | 0 | 定义一个动画周期。支持的单位为[s(秒)\|ms(毫秒)&nbsp;],默认单位为ms,格式为:1000ms或1s。<br/>**说明:**<br/>animation-duration&nbsp;样式必须设置,否则时长为&nbsp;0,则不会播放动画。 |
| animation-iteration-count | number&nbsp;&nbsp;\|&nbsp;infinite | 1 | 定义动画播放的次数,默认播放一次,可通过设置为infinite无限次播放。 |
| animation-timing-function | string | <br/>linear | 描述动画执行的速度曲线,用于使动画更为平滑。<br/>可选项有:<br/>-&nbsp;linear:表示动画从头到尾的速度都是相同的。<br/>-&nbsp;ease-in:表示动画以低速开始,cubic-bezier(0.42,&nbsp;0.0,&nbsp;1.0,&nbsp;1.0)。<br/>-&nbsp;ease-out:表示动画以低速结束,cubic-bezier(0.0,&nbsp;0.0,&nbsp;0.58,&nbsp;1.0)。<br/>-&nbsp;ease-in-out:表示动画以低速开始和结束,cubic-bezier(0.42,&nbsp;0.0,&nbsp;0.58,&nbsp;1.0)。 |
| animation-fill-mode | string | none | 指定动画开始和结束的状态:<br/>-&nbsp;none:在动画执行之前和之后都不会应用任何样式到目标上。<br/>-&nbsp;forwards:在动画结束后,目标将保留动画结束时的状态(在最后一个关键帧中定义)。 |
**表1** transform操作说明
| 名称 | 类型 | 描述 |
| ---------- | ------------------------------------ | ---------- |
| translateX | &lt;length&gt; | X轴方向平移动画属性 |
| translateY | &lt;length&gt; | Y轴方向平移动画属性 |
| rotate | &lt;deg&gt;&nbsp;\|&nbsp;&lt;rad&gt; | 旋转动画属性 |
> **说明:**
>
> 轻量级智能穿戴仅支持原始大小的图片进行旋转。
**表2** \@keyframes属性说明
| 名称 | 类型 | 默认值 | 描述 |
| ---------------- | -------------- | ---- | ------------------ |
| background-color | &lt;color&gt; | - | 动画执行后应用到组件上的背景颜色。 |
| width | &lt;length&gt; | - | 动画执行后应用到组件上的宽度值。 |
| height | &lt;length&gt; | - | 动画执行后应用到组件上的高度值。 |
| transform | string | - | 定义应用在组件上的变换类型,见表1。 |
对于不支持起始值或终止值缺省的情况,可以通过from和to显示指定起始和结束。示例:
```css
@keyframes Go
{
from {
background-color: #f76160;
}
to {
background-color: #09ba07;
}
}
```
![动画样式demo1](figures/动画样式demo1.gif)
> **说明:**
>
> \@keyframes的from/to不支持动态绑定。
# 媒体查询
> **说明:**
>
> - 从API version 8 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
>
> - media属性值默认为设备的真实尺寸大小、物理像素和真实的屏幕分辨率。
媒体查询(Media Query)应用十分广泛,开发者经常需要根据设备的大致类型或者特定的特征和设备参数(例如屏幕分辨率)来修改应用的样式。使用媒体查询针对设备和应用的属性信息,可以设计出相匹配的布局样式。
## CSS语法规则
使用@media来引入查询语句,具体规则如下:
```
@media [media-type] [and|or] [(media-feature)] {
CSS-Code;
}
```
@media screen and (round-screen: true) { … } : 当设备屏幕是圆形时条件成立
@media (max-height: 454) { … } :范围查询,CSS level 3 写法
> **说明:**
>
> - 不支持&lt;=,&gt;=,&lt;,&gt;操作符;
> - api 9开始才支持多重 () 嵌套使用;
> - media语句整体长度不能超过 512 个字符;
> - 单个media条件长度不能超过32个字符;
## 媒体类型
| 类型 | 说明 |
| ------ | -------------- |
| screen | 按屏幕相关参数进行媒体查询。 |
## 媒体逻辑操作
媒体逻辑操作符:and、or<sup>9+</sup>用于构成媒体查询语句,详细解释说明如下表。
**表1** 媒体逻辑操作符
| 类型 | 说明 |
| --------------- | ---------------------------------------- |
| and | 将多个媒体特征(Media&nbsp;Feature)以“与”的方式连接成一个媒体查询,只有当所有媒体特征都为true,查询条件成立。另外,它还可以将媒体类型和媒体功能结合起来。<br/>例如:screen&nbsp;and&nbsp;(device-type:&nbsp;liteWearable)&nbsp;and&nbsp;(max-height:&nbsp;454)&nbsp;表示当设备类型是智能穿戴同时应用的最大高度小于等于454个像素单位时成立。 |
| or<sup>9+</sup> | 将多个媒体特征以“或”的方式连接成一个媒体查询,如果存在结果为true的媒体特征,则查询条件成立。<br/>例如:screen&nbsp;and&nbsp;(max-height:&nbsp;454) &nbsp;or&nbsp;&nbsp;(round-screen:true)表示当应用高度小于等于454个像素单位或者设备屏幕是圆形时,条件成立。 |
## 媒体特征
| 类型 | 说明 |
| ---------------- | ---------------------------------------- |
| height | 应用页面显示区域的高度。 |
| min-height | 应用页面显示区域的最小高度。 |
| max-height | 应用页面显示区域的最大高度。 |
| width | 应用页面显示区域的宽度。 |
| min-width | 应用页面显示区域的最小宽度。 |
| max-width | 应用页面显示区域的最大宽度。 |
| aspect-ratio | 应用页面显示区域的宽度与高度的比值。<br/>例如:aspect-ratio: 1/2 |
| min-aspect-ratio | 应用页面显示区域的宽度与高度的最小比值。 |
| max-aspect-ratio | 应用页面显示区域的宽度与高度的最大比值。 |
| round-screen | 屏幕类型,圆形屏幕为 true,&nbsp;非圆形屏幕为&nbsp;false。 |
## 通用媒体特征示例代码
多个.container中的所写的属性个数以及类型需要相同,若不相同会导致显示异常。
```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;
}
.title {
font-size: 30px;
text-align: center;
}
@media (device-type: samrtVision) {
.container {
width: 500px;
height: 500px;
background-color: #fa8072;
}
}
@media (device-type: liteWearable) {
.container {
width: 300px;
height: 300px;
background-color: #008b8b;
}
}
```
# div
基础容器,用作页面结构的根节点或将内容进行分组。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| flex-direction | string | row | 否 | flex容器主轴方向。可选项有:<br/>-&nbsp;column:垂直方向从上到下<br/>-&nbsp;row:水平方向从左到右 |
| flex-wrap | string | nowrap | 否 | flex容器是单行还是多行显示,该值暂不支持动态修改。可选项有:<br/>-&nbsp;nowrap:不换行,单行显示。<br/>-&nbsp;wrap:换行,多行显示。 |
| justify-content | string | flex-start | 否 | flex容器当前行的主轴对齐格式。可选项有:<br/>-&nbsp;flex-start:项目位于容器的开头。<br/>-&nbsp;flex-end:项目位于容器的结尾。<br/>-&nbsp;center:项目位于容器的中心。<br/>-&nbsp;space-between:项目位于各行之间留有空白的容器内。<br/>-&nbsp;space-around:项目位于各行之前、之间、之后都留有空白的容器内。 |
| align-items | string | stretch<sup>5+</sup><br/>flex-start<sup>1-4</sup> | 否 | flex容器当前行的交叉轴对齐格式,可选值为:<br/>-&nbsp;stretch:弹性元素被在交叉轴方向被拉伸到与容器相同的高度或宽度。<sup>5+</sup><br/>-&nbsp;flex-start:元素向交叉轴起点对齐。<br/>-&nbsp;flex-end:元素向交叉轴终点对齐。<br/>-&nbsp;center:元素在交叉轴居中。 |
| display | string | flex | 否 | 确定该元素视图框的类型,该值暂不支持动态修改。可选值为:<br/>-&nbsp;flex:弹性布局<br/>-&nbsp;none:不渲染此元素 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
1. Flex样式
```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;
}
```
![zh-cn_image_0000001381108420](figures/zh-cn_image_0000001381108420.png)
2. Flex Wrap样式
```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;
}
```
![zh-cn_image_0000001431148457](figures/zh-cn_image_0000001431148457.png)
# list-item
&lt;[list](js-components-container-list.md)&gt;的子组件,用来展示列表具体item。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
## 示例
参考 [list示例](js-components-container-list.md)
\ No newline at end of file
# list
列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据,例如图片和文本。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
仅支持&lt;[list-item](js-components-container-list-item.md)&gt;
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| scrollend | - | 列表滑动已经结束。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
| scrolltop<sup>8+</sup> | - | 当前列表已滑动到顶部位置。 |
| scrollbottom<sup>8+</sup> | - | 当前列表已滑动到底部位置。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| flex-direction | string | column | 否 | 设置flex容器主轴的方向,指定flex项如何放置在flex容器中,可选值为:<br/>-&nbsp;column:主轴为纵向。<br/>-&nbsp;row:主轴为横向。<br/>其他组件默认值为row,在list组件中默认值为column。轻量级智能穿戴不支持动态修改。 |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 方法
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| scrollTo | {&nbsp;index:&nbsp;number(指定位置)&nbsp;} | list滑动到指定index的item位置。 |
## 示例
```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>
```
```js
// index.js
export default {
data: {
todolist: [{
title: '刷题',
date: '2021-12-31 10:00:00',
}, {
title: '看电影',
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;
}
```
![list](figures/list.png)
# stack
堆叠容器,子组件按照顺序依次入栈,后一个子组件覆盖前一个子组件。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
支持。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ----- | ------ | ---- | ---- | ---------------------------------------- |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| ------------------ | --------------------------------- | ----------- |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| ---------------------------------- | ---------------------------------------- | ----- | ---- | ---------------------------------------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
> **说明:**
>
> 由于绝对定位不支持设置百分比,所以也不支持stack组件的子组件上设置margin。
## 示例
```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;
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;
}
```
![zh-cn_image_0000001380789188](figures/zh-cn_image_0000001380789188.png)
# swiper
滑动容器,提供切换子组件显示的能力。
> **说明:**
>
> 该组件从从API version 4 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
## 子组件
支持除&lt;list&gt;之外的子组件。
## 属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| index | number | 0 | 否 | 当前在容器中显示的子组件的索引值。 |
| loop | boolean | true | 否 | 是否开启循环轮播。<br/> |
| duration | number | - | 否 | 子组件切换的动画时长。 |
| vertical | boolean | false | 否 | 是否为纵向滑动,纵向滑动时采用纵向的指示器。<br/>不支持动态修改。 |
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类,用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素的引用信息,该引用将注册到父组件的$refs&nbsp;属性对象上。 |
## 事件
| 名称 | 参数 | 描述 |
| -------- | -------- | -------- |
| change | {&nbsp;index:&nbsp;currentIndex&nbsp;} | 当前显示的组件索引变化时触发该事件。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| swipe<sup>5+</sup> | [SwipeEvent](js-common-events.md) | 组件上快速滑动后触发。 |
## 样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| width | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的宽度。<br/><br/>未设置时组件宽度默认为0。 |
| height | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | - | 否 | 设置组件自身的高度。<br/><br/>未设置时组件高度默认为0。 |
| padding | &lt;length&gt; | 0 | 否 | 使用简写属性设置所有的内边距属性。<br/>&nbsp;&nbsp;该属性可以有1到4个值:<br/>-&nbsp;指定一个值时,该值指定四个边的内边距。<br/>-&nbsp;指定两个值时,第一个值指定上下两边的内边距,第二个指定左右两边的内边距。<br/>-&nbsp;指定三个值时,第一个指定上边的内边距,第二个指定左右两边的内边距,第三个指定下边的内边距。<br/>-&nbsp;指定四个值时分别为上、右、下、左边的内边距(顺时针顺序)。 |
| padding-[left\|top\|right\|bottom] | &lt;length&gt; | 0 | 否 | 设置左、上、右、下内边距属性。 |
| margin | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 使用简写属性设置所有的外边距属性,该属性可以有1到4个值。<br/>-&nbsp;只有一个值时,这个值会被指定给全部的四个边。<br/>-&nbsp;两个值时,第一个值被匹配给上和下,第二个值被匹配给左和右。<br/>-&nbsp;三个值时,第一个值被匹配给上,&nbsp;第二个值被匹配给左和右,第三个值被匹配给下。<br/>-&nbsp;四个值时,会依次按上、右、下、左的顺序匹配&nbsp;(即顺时针顺序)。 |
| margin-[left\|top\|right\|bottom] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>5+</sup> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| border-width | &lt;length&gt; | 0 | 否 | 使用简写属性设置元素的所有边框宽度。 |
| border-color | &lt;color&gt; | black | 否 | 使用简写属性设置元素的所有边框颜色。 |
| border-radius | &lt;length&gt; | - | 否 | border-radius属性是设置元素的外边框圆角半径。 |
| background-color | &lt;color&gt; | - | 否 | 设置背景颜色。 |
| opacity<sup>5+</sup> | number | 1 | 否 | 元素的透明度,取值范围为0到1,1表示为不透明,0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型,可选值为:<br/>-&nbsp;flex:弹性布局。<br/>-&nbsp;none:不渲染此元素。 |
| [left\|top] | &lt;length&gt;&nbsp;\|&nbsp;&lt;percentage&gt;<sup>6+</sup> | - | 否 | left\|top确定元素的偏移位置。<br/>-&nbsp;left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。<br/>-&nbsp;top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 |
## 示例
```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;
}
```
```js
/* xxx.js */
export default {
data: {
index: 1
}
}
```
![swiper](figures/swiper.gif)
# 文件组织
## 目录结构
JS FA应用的JS模块(entry/src/main/js/module)的典型开发目录结构如下:
**图1** 目录结构  
![zh-cn_image_0000001431388581](figures/zh-cn_image_0000001431388581.png)
目录结构中文件分类如下:
- .hml结尾的HML模板文件,这个文件用来描述当前页面的文件布局结构。
- .css结尾的CSS样式文件,这个文件用于描述页面样式。
- .js结尾的JS文件,这个文件用于处理页面和用户的交互。
各个文件夹的作用:
- app.js文件用于全局JavaScript逻辑和应用生命周期管理。
- pages目录用于存放所有组件页面。
- common目录用于存放公共资源文件,比如:媒体资源和JS文件。
- i18n目录用于配置不同语言场景资源内容,比如应用文本词条,图片路径等资源。
> **说明:**
>
> - i18n是开发保留文件夹,不可重命名。
>
>
> - 在使用DevEco Studio进行应用开发时,目录结构中的可选文件夹需要开发者根据实际情况自行创建。
## 文件访问规则
应用资源可通过绝对路径或相对路径的方式进行访问,本开发框架中绝对路径以"/"开头,相对路径以"./"或"../"。具体访问规则如下:
- 引用代码文件,需使用相对路径,比如:../common/utils.js。
- 引用资源文件,推荐使用绝对路径。比如:/common/xxx.png。
- 公共代码文件和资源文件推荐放在common下,通过以上两条规则进行访问。
- CSS样式文件中通过url()函数创建&lt;url&gt;数据类型,如:url(/common/xxx.png)。
> **说明:**
>
> 当代码文件A需要引用代码文件B时:
>
> - 如果代码文件A和文件B位于同一目录,则代码文件B引用资源文件时可使用相对路径,也可使用绝对路径。
>
> - 如果代码文件A和文件B位于不同目录,则代码文件B引用资源文件时必须使用绝对路径。因为Webpack打包时,代码文件B的目录会发生变化。
>
>
## 媒体文件格式
**表1** 支持的图片格式
| 格式 | 支持版本 | 支持的文件类型 |
| ---- | ------------------------ | ------- |
| BMP | API&nbsp;Version&nbsp;4+ | .bmp |
| JPEG | API&nbsp;Version&nbsp;4+ | .jpg |
| PNG | API&nbsp;Version&nbsp;4+ | .png |
## 存储目录定义
从API Version 5开始,[image](js-components-basic-image.md)组件支持应用私有目录内的图片资源访问。
| 目录类型 | 路径前缀 | 访问可见性 | 说明 |
| ------ | --------------- | ------ | --------------------------- |
| 应用私有目录 | internal://app/ | 仅本应用可见 | 目录随应用卸载删除,路径禁止使用../等方式访问父目录 |
\ No newline at end of file
# app.js
## 应用生命周期<sup>4+</sup>
每个应用可以在app.js自定义应用级生命周期的实现逻辑,包括:
- onCreate:在应用生成时被调用的生命周期函数。
- onDestory:在应用销毁时被调用的生命周期函数。
以下示例仅在生命周期函数中打印对应日志:
```js
// app.js
export default {
onCreate() {
console.info('Application onCreate');
},
onDestroy() {
console.info('Application onDestroy');
},
}
```
## 应用对象<sup>10+</sup>
| 属性 | 类型 | 描述 |
| ------ | -------- | ---------------------------------------- |
| getApp | Function | 提供getApp()全局方法,可以在页面js文件中获取app.js中暴露的数据对象。 |
> **说明**:
>
> 应用对象是全局数据,其在整个应用消亡之前都会一直占用JS内存。尽管应用对象可为不同页面共享数据提供便利,但因为小型设备本身内存比较小,也应谨慎使用。如果过度使用,则容易造成应用在进入复杂page页面时,内存不够而出现异常。
示例如下:
在 app.js 中声明应用对象:
```javascript
// app.js
export default {
data: {
test: "by getAPP"
},
onCreate() {
console.info('Application onCreate');
},
onDestroy() {
console.info('Application onDestroy');
},
};
```
在具体的页面中访问应用对象:
```javascript
// index.js
export default {
data: {
title: ""
},
onInit() {
if (typeof getApp !== 'undefined') {
var appData = getApp().data;
if (typeof appData !== 'undefined') {
this.title = appData.name; // read from app data
}
}
},
clickHandler() {
if (typeof getApp !== 'undefined') {
var appData = getApp().data;
if (typeof appData !== 'undefined') {
appData.name = this.title; // write to app data
}
}
}
}
```
> **说明**:
>
> 为了应用可在不支持getApp的低版本上正常运行,代码中应进行兼容性处理,即在使用getApp前先判断其是否可用。
\ No newline at end of file
# js标签配置
js标签中包含了实例名称、页面路由信息。
| 标签 | 类型 | 默认值 | 必填 | 描述 |
| ----- | ------ | ------- | ---- | ----------------------------- |
| name | string | default | 是 | 标识JS实例的名字。 |
| pages | Array | - | 是 | 路由信息,详见“**[pages](#pages)**”。 |
> **说明:**
>
> name、pages标签配置需在配置文件中的“js”标签中完成设置。
## pages
定义每个页面的路由信息,每个页面由页面路径和页面名组成,页面的文件名就是页面名。比如:
```
{
...
"pages": [
"pages/index/index",
"pages/detail/detail"
]
...
}
```
> **说明:**
>
>
> - 应用首页固定为"pages/index/index"。
>
> - 页面文件名不能使用组件名称,比如:text.hml、button.hml等。
## 示例
```
{
"app": {
"bundleName": "com.huawei.player",
"version": {
"code": 1,
"name": "1.0"
},
"vendor": "example"
}
"module": {
...
"js": [
{
"name": "default",
"pages": [
"pages/index/index",
"pages/detail/detail"
]
}
],
"abilities": [
{
...
}
]
}
}
```
# CSS语法参考
CSS是描述HML页面结构的样式语言。所有组件均存在系统默认样式,也可在页面CSS样式文件中对组件、页面自定义不同的样式。
## 样式导入
为了模块化管理和代码复用,CSS样式文件支持 \@import 语句,导入 CSS 文件。
## 声明样式
每个页面目录下存在一个与布局hml文件同名的css文件,用来描述该hml页面中组件的样式,决定组件应该如何显示。
1. 内部样式,支持使用style、class属性来控制组件的样式。例如:
```html
<!-- index.hml -->
<div class="container">
<text style="color: red">Hello World</text>
</div>
```
```css
/* index.css */
.container {
justify-content: center;
}
```
2. 文件导入,合并外部样式文件。例如,在common目录中定义样式文件style.css,并在index.css文件首行中进行导入:
```css
/* style.css */
.title {
font-size: 50px;
}
```
```css
/* index.css */
@import '../../common/style.css';
.container {
justify-content: center;
}
```
## 选择器
css选择器用于选择需要添加样式的元素,支持的选择器如下表所示:
| 选择器 | 样例 | 样例描述 |
| ------ | --------------------- | ------------------------------------- |
| .class | .container | 用于选择class="container"的组件。 |
| \#id | \#titleId | 用于选择id="titleId"的组件。 |
| , | .title,&nbsp;.content | 用于选择class="title"和class="content"的组件。 |
示例:
```html
<!-- 页面布局xxx.hml -->
<div id="containerId" class="container">
<text id="titleId" class="title">标题</text>
<div class="content">
<text id="contentId">内容</text>
</div>
</div>
```
```css
/* 页面样式xxx.css */
/* 对class="title"的组件设置样式 */
.title {
font-size: 30px;
}
/* 对id="contentId"的组件设置样式 */
#contentId {
font-size: 20px;
}
/* 对所有class="title"以及class="content"的组件都设置padding为5px */
.title, .content {
padding: 5px;
}
```
## 伪类
css伪类是选择器中的关键字,用于指定要选择元素的特殊状态。
| 名称 | 支持组件 | 描述 |
| -------- | ----------------------------------- | ---------------------------------------- |
| :active | <br/>input[type="button"] | 表示被用户激活的元素,如:被用户按下的按钮。轻量级智能穿戴上伪类选择器上仅支持background-color&nbsp;和background-image&nbsp;的样式设置。 |
| :checked | input[type="checkbox"、type="radio"] | 表示checked属性为true的元素。轻量级智能穿戴上伪类选择器上仅支持background-color&nbsp;和background-image&nbsp;的样式设置。 |
伪类示例如下,设置按钮的:active伪类可以控制被用户按下时的样式:
```html
<!-- index.hml -->
<div class="container">
<input type="button" class="button" value="Button"></input>
</div>
```
```css
/* index.css */
.button:active {
background-color: #888888;/*按钮被激活时,背景颜色变为#888888 */
}
```
## 样式预编译
预编译提供了利用特有语法生成css的程序,可以提供变量、运算等功能,令开发者更便捷地定义组件样式,目前支持less、sass和scss的预编译。使用样式预编译时,需要将原css文件后缀改为less、sass或scss,如index.css改为index.less、index.sass或index.scss。
- 当前文件使用样式预编译,例如将原index.css改为index.less:
```css
/* index.less */
/* 定义变量 */
@colorBackground: #000000;
.container {
background-color: @colorBackground; /* 使用当前less文件中定义的变量 */
}
```
- 引用预编译文件,例如common中存在style.scss文件,将原index.css改为index.scss,并引入style.scss:
```css
/* style.scss */
/* 定义变量 */
$colorBackground: #000000;
```
在index.scss中引用:
```css
/* index.scss */
/* 引入外部scss文件 */
@import '../../common/style.scss';
.container {
background-color: $colorBackground; /* 使用style.scss中定义的变量 */
}
```
> **说明:**
>
> 引用的预编译文件建议放在common目录进行管理。
# HML语法参考
HML(OpenHarmony Markup Language)是一套类HTML的标记语言,通过组件,事件构建出页面的内容。页面具备数据绑定、事件绑定、列表渲染、条件渲染等高级能力。
## 页面结构
```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>
```
## 数据绑定
```html
<!-- xxx.hml -->
<div onclick="changeText">
<text> {{content[1]}} </text>
</div>
```
```js
// xxx.js
export default {
data: {
content: ['Hello World!', 'Welcome to my world!']
},
changeText: function() {
this.content.splice(1, 1, this.content[0]);
}
}
```
> **说明:**
> - 针对数组内的数据修改,请使用splice方法生效数据绑定变更。
>
> - hml中的js表达式不支持ES6语法。
## 事件绑定
事件绑定的回调函数接收一个事件对象参数,可以通过访问该事件对象获取事件信息。
```html
<!-- xxx.hml -->
<div>
<!-- 通过'@'绑定事件 -->
<div @click="clickfunc"></div>
<!-- 通过'on'绑定事件 -->
<div onclick="clickfunc"></div>
<!-- 通过'on'绑定事件,不推荐使用5+ -->
<div onclick="clickfunc"></div>
<!-- 使用事件冒泡模式绑定事件回调函数。5+ -->
<div on:click.bubble="clickfunc"></div>
<!-- on:{event}等价于on:{event}.bubble。5+ -->
<div on:click="clickfunc"></div>
<!-- 绑定事件回调函数,但阻止事件向上传递。5+ -->
<div grab:click.bubble="clickfunc"></div>
<!-- grab:{event}等价于grab:{event}.bubble。5+ -->
<div grab:click="clickfunc"></div>
</div>
```
```js
// xxx.js
export default {
data: {
obj: '',
},
clickfunc: function(e) {
this.obj = 'Hello World';
console.log(e);
},
}
```
> **说明:**
>
> 事件冒泡机制从API Version 5开始支持。升级SDK后,运行存量JS应用,采用旧写法(onclick)的事件绑定还是按事件不冒泡进行处理。但如果使用新版本SDK重新打包JS应用,将旧写法按事件冒泡进行处理。为了避免业务逻辑错误,建议将旧写法(如onclick)改成新写法(grab:click)。
**示例:**
```html
<!-- xxx.hml -->
<div class="container">
<text class="title">{{count}}</text>
<div class="box">
<input type="button" class="btn" value="increase" onclick="increase" />
<input type="button" class="btn" value="decrease" @click="decrease" />
<!-- 传递额外参数 -->
<input type="button" class="btn" value="double" @click="multiply(2)" />
<input type="button" class="btn" value="decuple" @click="multiply(10)" />
<input type="button" class="btn" value="square" @click="multiply(count)" />
</div>
</div>
```
```js
// xxx.js
export default {
data: {
count: 0
},
increase() {
this.count++;
},
decrease() {
this.count--;
},
multiply(multiplier) {
this.count = multiplier * this.count;
}
};
```
```css
/* xxx.css */
.container {
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
left: 0px;
top: 0px;
width: 454px;
height: 454px;
}
.title {
font-size: 30px;
text-align: center;
width: 200px;
height: 100px;
}
.box {
width: 454px;
height: 200px;
justify-content: center;
align-items: center;
flex-wrap: wrap;
}
.btn {
width: 200px;
border-radius: 0;
margin-top: 10px;
margin-left: 10px;
}
```
## 列表渲染
```html
<!-- xxx.hml -->
<div class="array-container">
<!-- div列表渲染 -->
<!-- 默认$item代表数组中的元素, $idx代表数组中的元素索引 -->
<div for="{{array}}" tid="id" onclick="changeText">
<text>{{$idx}}.{{$item.name}}</text>
</div>
<!-- 自定义元素变量名称 -->
<div for="{{value in array}}" tid="id" onclick="changeText">
<text>{{$idx}}.{{value.name}}</text>
</div>
<!-- 自定义元素变量、索引名称 -->
<div for="{{(index, value) in array}}" tid="id" onclick="changeText">
<text>{{index}}.{{value.name}}</text>
</div>
</div>
```
```js
// xxx.js
export default {
data: {
array: [
{id: 1, name: 'jack', age: 18},
{id: 2, name: 'tony', age: 18},
],
},
changeText: function() {
if (this.array[1].name === "tony"){
this.array.splice(1, 1, {id:2, name: 'Isabella', age: 18});
} else {
this.array.splice(2, 1, {id:3, name: 'Bary', age: 18});
}
},
}
```
tid属性主要用来加速for循环的重渲染,旨在列表中的数据有变更时,提高重新渲染的效率。tid属性是用来指定数组中每个元素的唯一标识,如果未指定,数组中每个元素的索引为该元素的唯一id。例如上述tid="id"表示数组中的每个元素的id属性为该元素的唯一标识。for循环支持的写法如下:
- for="array":其中array为数组对象,array的元素变量默认为$item。
- for="v in array":其中v为自定义的元素变量,元素索引默认为$idx。
- for="(i, v) in array":其中元素索引为i,元素变量为v,遍历数组对象array。
> **说明:**
>
> - 数组中的每个元素必须存在tid指定的数据属性,否则运行时可能会导致异常。
>
> - 数组中被tid指定的属性要保证唯一性,如果不是则会造成性能损耗。比如,示例中只有id和name可以作为tid字段,因为它们属于唯一字段。
>
> - tid不支持表达式。
## 条件渲染
条件渲染分为2种:if/elif/else和show。两种写法的区别在于:第一种写法里if为false时,组件不会在vdom中构建,也不会渲染,而第二种写法里show为false时虽然也不渲染,但会在vdom中构建;另外,当使用if/elif/else写法时,节点必须是兄弟节点,否则编译无法通过。实例如下:
```html
<!-- xxx.hml -->
<div class="container">
<button class="btn" type="capsule" value="toggleShow" onclick="toggleShow"></button>
<button class="btn" type="capsule" value="toggleDisplay" onclick="toggleDisplay"></button>
<text if="{{show}}"> Hello-One </text>
<text elif="{{display}}"> Hello-Two </text>
<text else> Hello-World </text>
</div>
```
```css
/* xxx.css */
.container{
flex-direction: column;
align-items: center;
}
.btn{
width: 280px;
font-size: 26px;
margin: 10px 0;
}
```
```js
// xxx.js
export default {
data: {
show: false,
display: true,
},
toggleShow: function() {
this.show = !this.show;
},
toggleDisplay: function() {
this.display = !this.display;
}
}
```
优化渲染优化:show方法。当show为真时,节点正常渲染;当为假时,仅仅设置display样式为none。
```html
<!-- xxx.hml -->
<div class="container">
<button class="btn" type="capsule" value="toggle" onclick="toggle"></button>
<text show="{{visible}}" > Hello World </text>
</div>
```
```css
/* xxx.css */
.container{
flex-direction: column;
align-items: center;
}
.btn{
width: 280px;
font-size: 26px;
margin: 10px 0;
}
```
```js
// xxx.js
export default {
data: {
visible: false,
},
toggle: function() {
this.visible = !this.visible;
},
}
```
> **说明:**
>
> 禁止在同一个元素上同时设置for和if属性。
# JS语法参考
JS文件用来定义HML页面的业务逻辑,支持ECMA规范的JavaScript语言。基于JavaScript语言的动态化能力,可以使应用更加富有表现力,具备更加灵活的设计。下面讲述JS文件的编译和运行的支持情况。
## 语法
支持ES6语法。轻量级智能穿戴支持的ES6语法有限,仅支持以下ES6 语法:
1. let/const
2. arrow functions
3. class
4. default value
5. destructuring assignment
6. destructuring binding pattern
7. enhanced object initializer
8. for-of
9. rest parameter
10. template strings
- 模块声明
使用import方法引入功能模块:
```
import router from '@system.router';
```
- 代码引用
使用import方法导入js代码:
```
import utils from '../../common/utils.js';
```
## 对象
- 页面对象
| 属性 | 类型 | 描述 |
| ----- | --------------- | ---------------------------------------- |
| data | Object/Function | 页面的数据模型,类型是对象或者函数,如果类型是函数,返回值必须是对象。属性名不能以$或_开头,不要使用保留字for,&nbsp;if,&nbsp;show,&nbsp;tid。<br/> |
| $refs | Object | 持有注册过ref&nbsp;属性的DOM元素或子组件实例的对象。示例见[获取DOM元素](#获取dom元素)。 |
## 获取DOM元素
1. 通过$refs获取DOM元素
```html
<!-- index.hml -->
<div class="container">
<image-animator class="image-player" ref="animator" images="{{images}}" duration="1s" onclick="handleClick"></image-animator>
</div>
```
```js
// index.js
export default {
data: {
images: [
{ src: '/common/frame1.png' },
{ src: '/common/frame2.png' },
{ src: '/common/frame3.png' },
],
},
handleClick() {
const animator = this.$refs.animator; // 获取ref属性为animator的DOM元素
const state = animator.getState();
if (state === 'paused') {
animator.resume();
} else if (state === 'stopped') {
animator.start();
} else {
animator.pause();
}
},
};
```
## 生命周期接口
- 页面生命周期
| 属性 | 类型 | 参数 | 返回值 | 描述 | 触发时机 |
| --------- | -------- | ---- | ---- | ------ | ------------------- |
| onInit | Function | 无 | 无 | 页面初始化 | 页面数据初始化完成时触发,只触发一次。 |
| onReady | Function | 无 | 无 | 页面创建完成 | 页面创建完成时触发,只触发一次。 |
| onShow | Function | 无 | 无 | 页面显示 | 页面显示时触发。 |
| onHide | Function | 无 | 无 | 页面消失 | 页面消失时触发。 |
| onDestroy | Function | 无 | 无 | 页面销毁 | 页面销毁时触发。 |
页面A的生命周期接口的调用顺序:
- 打开页面A:onInit() -&gt; onReady() -&gt; onShow()
- 在页面A打开页面B:onHide() -&gt; onDestroy()
- 从页面B返回页面A:onInit() -&gt; onReady() -&gt; onShow()
- 退出页面A:onHide() -&gt; onDestroy()
- 页面隐藏到后台运行:onHide()
- 页面从后台运行恢复到前台:onShow()
- 应用生命周期
| 属性 | 类型 | 参数 | 返回值 | 描述 | 触发时机 |
| --------- | -------- | ---- | ---- | ---- | --------- |
| onCreate | Function | 无 | 无 | 应用创建 | 当应用创建时调用。 |
| onDestroy | Function | 无 | 无 | 应用退出 | 当应用退出时触发。 |
......@@ -833,7 +833,42 @@
- [类型说明](reference/arkui-ts/ts-types.md)
- 已停止维护的组件
- [GridContainer](reference/arkui-ts/ts-container-gridcontainer.md)
- 组件参考(兼容JS的类Web开发范式)
- 组件参考(兼容JS的类Web开发范式-ArkUI.Full)
- 组件参考(兼容JS的类Web开发范式-ArkUI.Lite)
- 框架说明
- [文件组织](reference/arkui-js-lite/js-framework-file.md)
- [js标签配置](reference/arkui-js-lite/js-framework-js-tag.md)
- [app.js](reference/arkui-js-lite/js-framework-js-file.md)
- 语法
- [HML语法参考](reference/arkui-js-lite/js-framework-syntax-hml.md)
- [CSS语法参考](reference/arkui-js-lite/js-framework-syntax-css.md)
- [JS语法参考](reference/arkui-js-lite/js-framework-syntax-js.md)
- 组件通用信息
- [通用事件](reference/arkui-js-lite/js-common-events.md)
- [通用属性](reference/arkui-js-lite/js-common-attributes.md)
- [通用样式](reference/arkui-js-lite/js-common-styles.md)
- [动画样式](reference/arkui-js-lite/js-components-common-animation.md)
- 容器组件
- [div](reference/arkui-js-lite/js-components-container-div.md)
- [list](reference/arkui-js-lite/js-components-container-list.md)
- [list-item](reference/arkui-js-lite/js-components-container-list-item.md)
- [stack](reference/arkui-js-lite/js-components-container-stack.md)
- [swiper](reference/arkui-js-lite/js-components-container-swiper.md)
- 基础组件
- [chart](reference/arkui-js-lite/js-components-basic-chart.md)
- [image](reference/arkui-js-lite/js-components-basic-image.md)
- [image-animator](reference/arkui-js-lite/js-components-basic-image-animator.md)
- [input](reference/arkui-js-lite/js-components-basic-input.md)
- [marquee](reference/arkui-js-lite/js-components-basic-marquee.md)
- [picker-view](reference/arkui-js-lite/js-components-basic-picker-view.md)
- [progress](reference/arkui-js-lite/js-components-basic-progress.md)
- [qrcode](reference/arkui-js-lite/js-components-basic-qrcode.md)
- [slider](reference/arkui-js-lite/js-components-basic-slider.md)
- [switch](reference/arkui-js-lite/js-components-basic-switch.md)
- [text](reference/arkui-js-lite/js-components-basic-text.md)
- 画布组件
- [canvas组件](reference/arkui-js-lite/js-components-canvas-canvas.md)
- [CanvasRenderingContext2D对象](reference/arkui-js-lite/js-components-canvas-canvasrenderingcontext2d.md)
- 组件通用信息
- [通用属性](reference/arkui-js/js-components-common-attributes.md)
- [通用样式](reference/arkui-js/js-components-common-styles.md)
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册