JS 组件开发

组件

通用属性

常规属性

常规属性指的是组件普遍支持的用来设置组件基本标识和外观显示特征的属性。

表 1 常规属性说明

名称	类型	默认值	必填	说明
id	string	-	否	组件的唯一标识。
style	string	-	否	组件的样式声明。
class	string	-	否	组件的样式类，用于引用样式表。
ref	string	-	否	用来指定指向子元素的引用信息，该引用将注册到父组件的$refs属性对象上。

渲染属性

渲染属性指的是组件普遍支持的用来设置组件是否渲染的属性。

表 2 渲染属性说明

名称	类型	默认值	说明
for	Array	-	根据设置的数据列表，展开当前元素。
if	boolean	-	根据设置的boolean值，添加或移除当前元素。
show	boolean	-	根据设置的boolean值，显示或隐藏当前元素。

说明： 属性和样式不能混用，不能在属性字段中进行样式设置。

通用样式

组件普遍支持的可以在style或css中设置组件外观样式。

说明： 通用样式都不是必填项。

表 1 通用样式说明

名称	类型	默认值	说明
width	<length> \| <percentage>	-	设置组件自身的宽度。未设置时组件宽度默认为0。
height	<length> \| <percentage>	-	设置组件自身的高度。未设置时组件高度默认为0。
padding	<length>	0	使用简写属性设置所有的内边距属性，该属性可以有1到4个值：指定一个值时，该值指定四个边的内边距。指定两个值时，第一个值指定上下两边的内边距，第二个指定左右两边的内边距。指定三个值时，第一个指定上边的内边距，第二个指定左右两边的内边距，第三个指定下边的内边距。指定四个值时分别为上、右、下、左边的内边距（顺时针顺序）。
padding-[left\|top\|right\|bottom]	<length>	0	设置左、上、右、下内边距属性。
margin	<length> \| <percentage>	0	使用简写属性设置所有的外边距属性，该属性可以有1到4个值：只有一个值时，这个值会被指定给全部的四个边。两个值时，第一个值被匹配给上和下，第二个值被匹配给左和右。三个值时，第一个值被匹配给上，第二个值被匹配给左和右，第三个值被匹配给下。四个值时，会依次按上、右、下、左的顺序匹配（即顺时针顺序）。
margin-[left\|top\|right\|bottom]	<length> \| <percentage>	0	设置左、上、右、下外边距属性。
border-width	<length>	0	使用简写属性设置元素的所有边框宽度。
border-color	<color>	black	使用简写属性设置元素的所有边框颜色。
border-radius	<length>	-	border-radius属性是设置元素的外边框圆角半径。
background-color	<color>	-	设置背景颜色。
opacity⁵⁺	number	1	元素的透明度，取值范围为0到1。 0：完全透明。 1：不透明。
display	string	flex	确定一个元素所产生的框的类型，可选值为： flex：弹性布局。 none：不渲染此元素。
[left\|top]	<length> \| <percentage>	-	left\|top确定元素的偏移位置。 left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。 top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。

通用事件

事件说明

事件绑定在组件上，当组件达到事件触发条件时，会执行JS中对应的事件回调函数，实现页面UI视图和页面JS逻辑层的交互。
事件回调函数中通过参数可以携带额外的信息，如组件上的数据对象dataset，事件特有的回调参数。

相对于私有事件，大部分组件都可以绑定如表1所示事件。

表 1 通用事件说明

名称	参数	说明	是否支持冒泡
click	-	点击动作触发该事件。	是
longpress	-	长按动作触发该事件。	是
swipe	表2	组件上快速滑动后触发该事件。	是

说明： 除上述事件外，其他事件均为非冒泡事件，如“事件”，请参见各个组件。

表 2 SwipeEvent基础事件对象属性列表

属性

类型

说明

direction

string

滑动方向，可能值有：

left：向左滑动；
right：向右滑动；
up：向上滑动；
down：向下滑动。

动画样式

组件支持动态的旋转、平移、缩放效果，可在style或css中设置。

表 1 动画样式说明

名称	类型	默认值	说明
transform	string	-	请参见表2。
animation-name	string	-	指定@keyframes，请参见表3。
animation-delay	<time>	0	定义动画播放的延迟时间。支持的单位为[s(秒)\|ms(毫秒) ]，默认单位为ms，格式为：1000ms或1s。
animation-duration	<time>	0	定义一个动画周期。支持的单位为[s(秒)\|ms(毫秒) ]，默认单位为ms，格式为：1000ms或1s。注意：轻量级智能穿戴上，动画周期最大值为60s。 animation-duration样式必须设置，否则时长为0，则不会播放动画。
animation-iteration-count	number \| infinite	1	定义动画播放的次数，默认播放一次，可通过设置为infinite无限次播放。
animation-timing-function	string	linear	描述动画执行的速度曲线，用于使动画更为平滑。可选项有： linear：表示动画从头到尾的速度都是相同的。 ease-in：表示动画以低速开始，cubic-bezier(0.42, 0.0, 1.0, 1.0)。 ease-out：表示动画以低速结束，cubic-bezier(0.0, 0.0, 0.58, 1.0)。 ease-in-out：表示动画以低速开始和结束，cubic-bezier(0.42, 0.0, 0.58, 1.0)。
animation-fill-mode	string	none	指定动画开始和结束的状态： none：在动画执行之前和之后都不会应用任何样式到目标上。 forwards：在动画结束后，目标将保留动画结束时的状态（在最后一个关键帧中定义）。

表 2 transform操作说明

名称	类型	说明
translateX	<length>	X轴方向平移动画属性。
translateY	<length>	Y轴方向平移动画属性。
rotate	<deg> \| <rad>	旋转动画属性

说明： 轻量级智能穿戴仅支持原始大小的图片进行旋转。

表 3 @keyframes属性说明

名称	类型	默认值	说明
background-color	<color>	-	动画执行后应用到组件上的背景颜色。
width	<length>	-	动画执行后应用到组件上的宽度值。
height	<length>	-	动画执行后应用到组件上的高度值。
transform	string	-	定义应用在组件上的变换类型，见表1。

对于不支持起始值或终止值缺省的情况，可以通过from和to显示指定起始和结束。示例：

<!-- xxx.hml -->
<div class="container">
  <div class="rect">
  </div>
</div>

/* xxx.css */
.container {
    width: 100%;
    height: 100%;
    display: flex;
    justify-content: center;
    align-items: center;
}
.rect{
    width: 200px;
    height: 200px;
    background-color: #f76160;
    animation-name: Go;
    animation-iteration-count: infinite;
    animation-duration: 3s;
}
@keyframes Go
{
    from {
        background-color: #f76160;
    }
    to {
        background-color: #09ba07;
    }
}

说明： @keyframes的from/to不支持动态绑定。

图 1 动画样式-示例说明

动画样式-示例说明

容器组件

div

基础容器，用作页面结构的根节点或将内容进行分组。

子组件

支持。

属性

支持“通用属性”中所述属性。

样式

除支持“通用样式”中所述样式外，还支持如表1所示样式。

表 1 div组件样式说明

名称	类型	默认值	必填	说明
flex-direction	string	row	否	flex容器主轴方向。可选项有： column：垂直方向从上到下。 row：水平方向从左到右。
flex-wrap	string	nowrap	否	flex容器是单行还是多行显示，该值暂不支持动态修改。可选项有： nowrap：不换行，单行显示。 wrap：换行，多行显示。
justify-content	string	flex-start	否	flex容器当前行的主轴对齐格式。可选项有： flex-start：项目位于容器的开头。 flex-end：项目位于容器的结尾。 center：项目位于容器的中心。 space-between：项目位于各行之间留有空白的容器内。 space-around：项目位于各行之前、之间、之后都留有空白的容器内。
align-items	string	stretch⁵⁺ flex-start^1-4 5+：支持SDK版本大于5。 1-4：支持SDK版本在1-4。	否	flex容器当前行的交叉轴对齐格式，可选值为： stretch：弹性元素在交叉轴方向被拉伸到与容器相同的高度或宽度。 flex-start：元素向交叉轴起点对齐。 flex-end：元素向交叉轴终点对齐。 center：元素在交叉轴居中。
display	string	flex	否	确定该元素视图框的类型，该值暂不支持动态修改。可选值为： flex：弹性布局。 none：不渲染此元素。

事件

支持“通用事件”中所述事件。

示例

Flex样式：

<!-- 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>
/* 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;
 }

图 1 div组件-Flex样式示例结果

div组件-Flex样式示例结果

Flex Wrap样式

 <!-- 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>
/* 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;
 }

图 2 div组件-Flex Wrap样式示例结果

div组件-Flex-Wrap样式示例结果

list

列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。

子组件

仅支持<list-item>子组件。

属性

支持“通用属性”中所述属性。

样式

除支持“通用样式”中所述样式外，还支持如表1所示样式。

表 1 list组件样式说明

名称

类型

默认值

必填

说明

flex-direction

string

column

否

设置flex容器主轴的方向，指定flex项如何放置在flex容器中，可选值为：

column：主轴为纵向。
row：主轴为横向。

其他组件默认值为row，在list组件中默认值为column。轻量级智能穿戴不支持动态修改。

事件

除支持“通用事件”中所述事件外，还支持如表2所示事件。

表 2 list组件事件说明

名称	参数	说明
scrollend	-	列表滑动已经结束。
scrollbar	bool	是否展示list进度条，false为不显示，true为显示；组件scrollbar属性默认为false。

方法

表 3 list组件方法说明

名称	参数	说明
scrollTo	{ index: number(指定位置) }	list滑动到指定index的item位置。
scrollToEnd	无	list滑动到底部。
long-text	bool	使能长文本模式。
value	string	设置文本内容，打开长文本模式后才能使用。建议控制在5000字以内。

示例

<!-- index.hml -->
<div class="container">
  <list class="todo-wrapper">
    <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>

// index.js
export default {
    data: {
        todolist: [{
            title: '刷题',
            date: '2021-12-31 10:00:00',
        }, {
            title: '看电影',
            date: '2021-12-31 20:00:00',
        }],
    },
}

/* index.css */
.container {
    display: flex;
    justify-content: center;
    align-items: center;
    left: 0px;
    top: 0px;
    width: 454px;
    height: 454px;
}
.todo-wrapper {
    width: 454px;
    height: 300px;
}
.todo-item {
    width: 454px;
    height: 80px;
    flex-direction: column;
}
.todo-title {
    width: 454px;
    height: 40px;
    text-align: center;
}

图 1 list组件-示例结果

list组件-示例结果

list-item

list-item是<list>的子组件，用来展示列表具体item。

子组件

支持。

属性

支持“通用属性”中所述属性。

样式

支持“通用样式”中所述样式。

当使用text子组件时，样式如果只设置width，不设置height，会触发自适应高度模式，lite-item自动配置组件height。

事件

支持“通用事件”中所述事件。

示例

请参见“示例”中示例内容。

stack

堆叠容器，子组件按照顺序依次入栈，后一个子组件覆盖前一个子组件。

子组件

支持。

属性

支持“通用属性”中所述属性。

样式

支持“通用样式”中所述样式。

事件

支持“通用事件”中所述事件。

示例

<!-- 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>

/* 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;
}

图 1 stack组件-示例结果

stack组件-示例结果

swiper

滑动容器，提供切换子组件显示的能力。

子组件

支持除<list>之外的子组件。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 swiper组件属性说明

名称	类型	默认值	必填	说明
index	number	0	否	当前在容器中显示的子组件的索引值。如果需要在js page切换时指定index，请在onShow()方法中更新index值。
loop	boolean	true	否	是否开启循环滑动。不支持动态修改。注意：loop参数生效需要满足以下两个条件：除第一个子组件之外，剩余子组件的总长度大于等于swiper的长度。除最后一个子组件之外，剩余子组件的总长度大于等于swiper的长度。
duration	number	-	否	子组件切换的动画时长。
vertical	boolean	false	否	是否为纵向滑动，纵向滑动时采用纵向的指示器。不支持动态修改。

样式

支持“通用样式”中所述样式。

事件

表 2 swiper组件事件说明

名称	参数	说明
change	{ index: currentIndex }	当前显示的组件索引变化时触发该事件。

示例

<!-- 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>

/* 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;
}

/* xxx.js */
export default {
    data: {
        index: 1
    }
}

图 1 swiper组件-示例结果

swiper组件-示例结果

基础组件

chart

图表组件，用于呈现线形图、柱状图界面。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 chart组件属性说明

名称

类型

默认值

必填

说明

type

string

line

否

设置图表类型（不支持动态修改），可选项有：

bar：柱状图。
line：线形图。

options

表2

-

是

图表参数设置，柱状图和线形图必须设置参数设置。可以设置x轴、y轴的最小值、最大值、刻度数、是否显示，线条宽度、是否平滑等。（不支持动态修改）

datasets

Array<表3>

-

是

数据集合，柱状图和线形图必须设置数据集合。可以设置多条数据集及其背景色。

表 2 ChartOptions

名称

类型

默认值

必填

说明

xAxis

表4

-

是

x轴参数设置。可以设置x轴最小值、最大值、刻度数以及是否显示。

yAxis

表4

-

是

y轴参数设置。可以设置y轴最小值、最大值、刻度数以及是否显示。

series

表5

-

否

数据序列参数设置。

设置线的样式，如线宽、是否平滑。
设置线最前端位置白点的样式和大小。

表 3 ChartDataset

名称	类型	默认值	必填	说明
backgroundColor(deprecated)	<color>	#ff6384	否	设置线或柱的颜色（不推荐使用）。
strokeColor	<color>	#ff6384	否	线条颜色。注意：仅线形图支持。
fillColor	<color>	#ff6384	否	填充颜色。线形图表示填充的渐变颜色。
data	Array<number>	-	是	设置绘制线或柱中的点集。
gradient	boolean	false	否	设置是否显示填充渐变颜色。注意：仅线形图支持。

表 4 ChartAxis

名称	类型	默认值	必填	说明
min	number	0	否	轴的最小值。注意：仅线形图支持负数。
max	number	100	否	轴的最大值。注意：仅线形图支持负数。
axisTick	number	10	否	轴显示的刻度数量。注意：仅支持1～20，且具体显示的效果与如下计算值有关（图的宽度所占的像素/（max-min））。因轻量级智能穿戴为整型运行，在除不尽的情况下会有误差产生，具体的表现形式是x轴末尾可能会空出一段。在柱状图中，每组数据显示的柱子数量与刻度数量一致，且柱子显示在刻度处。
display	boolean	false	否	是否显示轴。
color	<color>	#c0c0c0	否	轴颜色。

表 5 ChartSeries

名称	类型	默认值	必填	说明
lineStyle	表6	-	否	线样式设置，如线宽、是否平滑。
headPoint	表7	-	否	线最前端位置白点的样式和大小。
topPoint	表7	-	否	最高点的样式和大小。
bottomPoint	表7	-	否	最低点的样式和大小。
loop	表8	-	否	设置屏幕显示满时，是否需要重头开始绘制。

表 6 ChartLineStyle

名称	类型	默认值	必填	说明
width	<length>	1px	否	线宽设置。
smooth	boolean	false	否	是否平滑。

表 7 PointStyle

名称	类型	默认值	必填	说明
shape	string	circle	否	高亮点的形状。可选值为： circle：圆形。
size	<length>	5px	否	高亮点的大小。
strokeWidth	<length>	1px	否	边框宽度
strokeColor	<color>	#ff0000	否	边框颜色。
fillColor	<color>	#ff0000	否	填充颜色。
display	boolean	true	否	是否高亮显示。

表 8 ChartLoop

名称

类型

默认值

必填

说明

margin

1

否

擦除点的个数（最新绘制的点与最老的点之间的横向距离）。

注意：轻量设备margin和topPoint/bottomPoint/headPoint同时使用时，有概率出现point正好位于擦除区域的情况，导致point不可见，因此不建议同时使用。

样式

支持“通用样式”中所述样式。

事件

支持“通用事件”中所述事件。

方法

表 9 chart组件方法说明

方法

参数

说明

append

{

serial: number, // 设置要更新的线形图数据下标

data: Array<number>, // 设置新增的数据

}

往已有的数据序列中动态添加数据，根据serial指定目标序列。serial为datasets数组的下标，从0开始。

注意：不会更新datasets[index].data。仅线形图支持，按横坐标加1递增（与xAxis min/max设置相关）。

示例

线形图

 <!-- 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>
/* 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;
 }
// 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,
                }
            }
        },
    },
    addData() {
        this.$refs.linechart.append({
            serial: 0,
            data: [Math.floor(Math.random() * 400) + 400]
        })
    }
}

图 1 chart组件-线形图示例结果

chart组件-线形图示例结果

柱状图

 <!-- xxx.hml -->
 <div class="container">
   <chart class="chart" type="bar" id="bar-chart" options="{{barOps}}" datasets="{{barData}}"></chart>
 </div>
/* xxx.css */
 .container {
     flex-direction: column;
     justify-content: center;
     align-items: center;
     width: 454px;
     height: 454px;
     background-color: white;
 }
 .chart {
     width: 300px;
     height: 300px;
 }
// 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,
            },
        },
    }
}

图 2 chart组件-柱状图示例结果

chart组件-柱状图示例结果

image

图片组件，用来渲染展示图片。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 image组件属性说明

名称	类型	默认值	必填	说明
src	string	-	否	图片的路径，支持的图片格式包括png、jpg。

说明： 轻量级智能穿戴上，单个应用所有的图片资源总大小不得超过8M。

样式

支持“通用样式”中所述样式。

事件

支持“通用事件”中所述事件。

image-animator

图片帧动画播放器。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 image-animator组件属性说明

名称	类型	默认值	必填	说明
images	Array<ImageFrame>	-	是	设置图片帧信息集合。每一帧的帧信息包含图片路径、图片大小和图片位置信息。目前支持以下图片格式：png、jpg。ImageFrame的详细说明请见表2。注意：使用时需要使用数据绑定的方式，如images = {{images}}，js中声明相应变量：images: [{src: "/common/heart-rate01.png"}, {src: "/common/heart-rate02.png"}]。
iteration	number \| string	infinite	否	设置帧动画播放次数。number表示固定次数，infinite枚举表示无限次数播放。
reverse	boolean	false	否	设置播放顺序。 false：从第1张图片播放到最后1张图片。 true：从最后1张图片播放到第1张图片。
fixedsize	boolean	true	否	设置图片大小是否固定为组件大小。 true：图片大小与组件大小一致，此时设置图片的width 、height 、top 和left属性是无效的。 false：每一张图片的 width 、height 、top和left属性都要单独设置。
duration	string	-	是	设置单次播放时长。单位支持[s(秒)\|ms(毫秒)]，默认单位为ms。 duration为0时，不播放图片。值改变只会在下一次循环开始时生效。
fillmode⁵⁺	string	forwards	否	指定帧动画执行结束后的状态。可选项有： none：恢复初始状态。 forwards：保持帧动画结束时的状态（在最后一个关键帧中定义）。

表 2 ImageFrame说明

名称	类型	默认值	必填	说明
src	<uri>	-	是	图片路径。
width	<length>	0	否	图片宽度。
height	<length>	0	否	图片高度。
top	<length>	0	否	图片相对于组件左上角的纵向坐标。
left	<length>	0	否	图片相对于组件左上角的横向坐标。

样式

支持“通用样式”中所述样式。

事件

除支持“通用事件”中所述事件外，还支持如表3所示事件。

表 3 image-animator组件事件说明

名称	参数	说明
stop	-	帧动画结束时触发。

方法

表 4 image-animator组件方法说明

名称	参数	说明
start	-	开始播放图片帧动画。再次调用，重新从第1帧开始播放。
pause	-	暂停播放图片帧动画。
stop	-	停止播放图片帧动画。
resume	-	继续播放图片帧。
getState	-	获取播放状态。可能值有： playing：播放中。 paused：已暂停。 stopped：已停止。

示例

<!-- 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>

/* 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;
}

//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();
    },
};

图 1 image-animator组件-示例结果

image-animator组件-示例结果

input

交互式组件，包括单选框、多选框、按钮。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 input组件属性说明

名称	类型	默认值	必填	说明
type	string	button	否	input组件类型，可选值为button、checkbox、radio，均不支持动态修改。可选值定义如下： button：定义可点击的按钮。 checkbox：定义多选框。 radio：定义单选按钮，允许在多个拥有相同name值的选项中选中其中一个。
checked	boolean	false	否	当前组件是否选中，仅type为checkbox和radio生效。
name	string	-	否	input组件的名称。
value	string	-	否	input组件的value值，当类型为radio时必填且相同name值的选项该值唯一。

样式

除支持“通用样式”中所述样式外，还支持如表2所示样式。

表 2 input组件样式说明

名称	类型	默认值	必填	说明
color	<color>	#ffffff	否	单行输入框或者按钮的文本颜色。
font-size	<length>	30px	否	单行输入框或者按钮的文本尺寸。

事件

除支持“通用事件”中所述事件外，还支持如下事件：

当input类型为checkbox、radio时，支持如下事件：

表 3 input组件事件说明

名称

参数

说明

change

{ checked:true | false }

checkbox多选框或radio单选框的checked状态发生变化时触发该事件。

marquee

跑马灯组件，用于展示一段单行滚动的文字。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 marquee组件属性说明

名称	类型	默认值	必填	说明
scrollamount	number	6	否	跑马灯每次滚动时移动的最大长度。

样式

除支持“通用样式”中所述样式外，还支持如表2所示样式。

表 2 marquee组件样式说明

名称	类型	默认值	必填	说明
color	<color>	#ffffff	否	设置跑马灯中文字的文本颜色。
font-size	<length>	30	否	设置跑马灯中文字的文本尺寸。
font-family	string	HYQiHei-65S	否	字体。目前仅支持HYQiHei-65S字体。

事件

支持“通用事件”中所述事件。

picker-view

嵌入页面的滑动选择器。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 picker-view组件属性说明

名称

类型

默认值

必填

说明

type

string

text

否

设置滑动选择器的类型，该属性不支持动态修改，可选项有：

text：文本选择器。
time：时间选择器。

loop

boolean

true

否

是否开启循环滑动。不支持动态修改。

不同的滑动选择器的类型还支持不同的属性。

类型为文本选择器时，type=text，支持如表2所示属性。

表 2 文本选择器属性说明

名称

类型

默认值

必填

说明

range

Array

-

否

设置文本选择器的取值范围。

注意：使用时需要使用数据绑定的方式，如range = {{data}}，js中声明相应变量：data：["15", "20", "25"]。

selected

string

0

否

设置文本选择器的默认选择值，该值需要为range的索引。

类型为时间选择器时，type=time，支持如表3所示属性。

表 3 时间选择器属性说明

名称

类型

默认值

必填

说明

selected

string

00:00

否

设置时间选择器的默认取值，格式为HH:mm。

样式

除支持“通用样式”中所述样式外，还支持如表4所示样式。

表 4 picker-view组件样式说明

名称	类型	默认值	必填	说明
color	<color>	#808080	否	候选项字体颜色。
font-size	<length>	30px	否	候选项字体尺寸，类型length，单位：px。
selected-color	<color>	#ffffff	否	选中项字体颜色。
selected-font-size	<length>	38px	否	选中项字体尺寸，类型length，单位：px。
font-family	string	HYQiHei-65S	否	选项字体类型。字体。目前仅支持HYQiHei-65S字体。

事件

仅支持如下事件：

类型为文本选择器时，type=text，支持如表5所示事件。

表 5 文本选择器事件说明

名称

参数

说明

change

{ newValue: newValue, newSelected: newSelected }

文本选择器选定值后触发该事件。
类型为时间选择器时，type=time，支持如表6所示事件。

表 6 时间选择器事件说明

名称

参数

说明

change

{ hour: hour, minute: minute}

时间选择器选定值后触发该事件。

方法

不支持。

示例

<!-- 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>

/* 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;
}

/* 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)}`;
    },
}

图 1 picker-view组件-示例结果

picker-view组件-示例结果

progress

进度条，用于显示内容加载或操作处理进度。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 progress组件属性说明

名称

类型

默认值

必填

说明

type

string

horizontal

否

设置进度条的类型，该属性不支持动态修改，可选值为：

horizontal：线性进度条。
arc：弧形进度条。

不同类型的进度条还支持不同的属性。

类型为horizontal时，type=horizontal，支持如表2所示属性。

表 2 线性进度条属性说明

名称

类型

默认值

必填

说明

percent

number

0

否

当前进度。取值范围为0～100。
类型为arc时，type=arc，支持如表3所示属性。

表 3 弧形进度条属性说明

名称

类型

默认值

必填

说明

percent

number

0

否

当前进度。取值范围为0～100。

样式

除支持“通用样式”中所述样式外，还支持如下样式。

类型为horizontal时，type=horizontal，支持如表4所示样式。

表 4 线性进度条样式说明

名称

类型

默认值

必填

说明

color

<color>

#6b9ac7

否

设置进度条的颜色。

stroke-width

<length>

32px

否

设置进度条的宽度。

类型为arc时，type=arc，支持如表5所示样式。

表 5 弧形进度条样式说明

名称	类型	默认值	必填	说明
color	<color>	#5ea1ff	否	弧形进度条的颜色。
background-color	<color>	rgba(255, 255, 255, 0.15)	否	弧形进度条的背景色。
stroke-width	<length>	32px	否	弧形进度条的宽度。注意：进度条宽度越大，进度条越靠近圆心，进度条始终在半径区域内。
start-angle	<deg>	240	否	弧形进度条起始角度，以时钟0点为基线，取值范围为0到360（顺时针）。
total-angle	<deg>	240	否	弧形进度条总长度，范围为-360～+360，负数标识起点到终点为逆时针。
center-x	<length>	弧形进度条宽度的一半	否	弧形进度条中心位置（坐标原点为组件左上角顶点）。该样式需要和center-y和radius一起使用。
center-y	<length>	弧形进度条高度的一半	否	弧形进度条中心位置（坐标原点为组件左上角顶点）。该样式需要和center-x和radius一起使用。
radius	<length>	弧形进度条宽高最小值的一半	否	弧形进度条半径，该样式需要和center-x和center-y一起使用。

事件

支持“通用事件”中所述事件。

qrcode

生成并显示二维码。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 qrcode组件属性说明

名称

类型

默认值

必填

说明

value

string

-

是

用来生成二维码的内容。

最大长度为256。

type

string

rect

否

二维码类型。

rect：矩形二维码。

样式

除支持“通用样式”中所述样式外，还支持如表2所示样式。

表 2 qrcode组件样式说明

名称	类型	默认值	必填	说明
color	<color>	#000000	否	二维码颜色。
background-color	<color>	#ffffff	否	二维码背景颜色。

说明：

width和height不一致时，取二者较小值作为二维码的边长。且最终生成的二维码居中显示。

width和height的最小值与value长度成正比，请参见表3。

表 3 二维码最小尺寸与value长度关系

value长度	≤17	≤32	≤53	≤78	≤106	≤134	≤154	≤192	≤230
二维码最小尺寸	21×21	25×25	29×29	33×33	37×37	41×41	45×45	49×49	53×53

事件

支持“通用事件”中所述事件。

示例

/* xxx.css */
.qrcode_class{
    width: 53px;
    height: 53px;
}
.container{
    width: 100%;
    height: 100%;
    justify-content: center;
    align-items: center;
}
<!-- xxx.hml -->
<div class="container">
<qrcode class="qrcode_class" value="https://example.com"/>
</div>

slider

滑动条组件，用来快速调节设置值，如音量、亮度等。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 slider组件属性说明

名称	类型	默认值	必填	说明
min	number	0	否	滑动选择器的最小值。
max	number	100	否	滑动选择器的最大值。
value	number	0	否	滑动选择器的初始值。

样式

除支持“通用样式”中所述样式外，还支持如表2所示样式。

表 2 slider组件样式说明

名称

类型

默认值

必填

说明

color

<color>

#000000

否

滑动条的背景颜色。

selected-color

<color>

#ffffff

否

滑动条的已选择颜色。

direction

column | row

row

否

滑动条方向，可选项有：

column：垂直方向。

row：水平方向。

事件

除支持“通用事件”中所述事件外，还支持如表3所示事件。

表 3 slider组件事件说明

名称	参数	说明
change	表4	选择值发生变化时触发该事件。

表 4 ChangeEvent

属性	类型	说明
progress(deprecated)	string	当前slider的进度值。
value	number	当前slider的值。

switch

开关选择器，通过开关开启或关闭某个功能。

子组件

不支持。

属性

除支持“通用属性”中所述属性外，还支持如表1所示属性。

表 1 switch组件属性说明

名称	类型	默认值	必填	说明
checked	boolean	false	否	是否选中。

样式

支持“通用样式”中所述样式。

事件

除支持“通用事件”中所述事件外，还支持如表2所示事件。

表 2 switch组件事件说明

名称	参数	说明
change	{ checked: checkedValue }	选中状态改变时触发该事件。

示例

<!-- xxx.hml -->
<div class="container">
  <switch  checked="true" @change="switchChange">
  </switch>
</div>

/* xxx.css */
.container {
    width: 100%;
    height: 100%;
    display: flex;
    justify-content: center;
    align-items: center;
}
switch{
    width: 100px;
    height: 100px;
}

// xxx.js

export default {
    switchChange(e){
        console.log(e.checked);
    }
}

图 1 switch组件-示例说明

switch组件-示例说明

text

文本，用于呈现一段信息。

子组件

不支持。

属性

支持“通用属性”中所述属性。

样式

除支持“通用样式”中所述样式外，还支持如表1所示样式。

表 1 text组件样式说明

名称	类型	默认值	必填	说明
color	<color>	#ffffff	否	设置文本的颜色。
font-size	<length>	30px	否	设置文本的尺寸。目前仅支持30px和38px两个字体大小。
letter-spacing	<length>	2px	否	设置文本的字符间距。
text-alignright	string	left	否	设置文本的文本对齐方式，可选值为： left：文本水平方向左对齐。 center：文本水平方向居中对齐。 right：文本水平方向右对齐。
text-align-vertical	string	top	否	设置文本的文本对齐方式，可选值为： top：文本垂直方向顶部对齐。 center：文本垂直方向居中对齐。 bottom：文本垂直方向底部对齐。
text-overflow	string	clip	否	可选值为： clip：将文本根据父容器大小进行裁剪显示。 ellipsis：根据父容器大小显示，显示不下的文本用省略号代替。
font-family	string	HYQiHei-65S	否	字体。默认支持HYQiHei-65S字体用于调试。

自定义字体：商用产品增加自定义字体库详见《UIKit开发指南》。JSApp自定义字体需在DevEco Studio配置文件“sdk\default\openharmony\js\build-tools\ace-loader\lib\styler\lib\validator.js”中添加字体名称，才能通过JS编译检查。示例如下：["HYQiHei-65S","HarmonyOS_Sans_SC_Bold"]

text配置

事件

支持“通用事件”中所述事件。

示例

text组件示例：

<!-- xxx.hml -->
<div class="container">

    <text class="title">
      Hello {{ title }}
    </text>
</div>

/* xxx.css */
.container {
    width: 100%;
    height: 100%;
    display: flex;
    justify-content: center;
    align-items: center;
}
.title {
    font-size: 30px;
    text-align: center;
    width: 100px;

}

// xxx.js
export default {
    data: {
        title: 'World'
    }
}

图 1 text组件-示例结果1

text组件-示例结果1

text组件截断属性示例：

<!-- xxx.hml -->
<div class="container">
  <text class="text1">
    This is a passage
  </text>
  <text class="text2">
    This is a passage
  </text>
</div>

/* xxx.css */
.container {
    width: 100%;
    height: 100%;
    flex-direction: column;
    align-items: center;
    background-color: #F1F3F5;
    justify-content: center;
}
.text1{
    color: black;
}
.text2{
    width: 200px;
    height: 46px;
    color: black;
    max-lines: 1;
    text-overflow: ellipsis;
    text-valign: middle;
    line-height: 40px;
}

图 2 text组件-示例结果2

text组件-示例结果2

扩展组件

禁止修改公版已交付组件，会导致稳定性下降并破坏应用兼容性。

ACE上扩展组件。

在components路径下添加自定义组件的具体实现，自定义组件继承自“component.h”。

components
```
class CanvasComponent final : public Component {
    ...
};
```

在“keys.h”中添加组件的key值及名称。

keys.h

enum {
    ...
    KEYWORD(CANVAS, canvas) // canvas component
}

在 component_factory.h 中增加新增组件对应的构造函数。

static Component* CreateComponent(...)
    {
        ...
        switch (componentNameId) {
            ...
            case K_QRCODE:
                component = new CanvasComponent(options, children, styleManager);
                break;
        }
    }

将ACE扩展组件添加到Deveco Studio检查项。

Deveco Studio SDK目录：点击“File”→ “Settings”进入“HarmonyOS SDK”。

修改SDK目录下检查配置

IDE2.1（已日落）：js\2.1.1.21\build-tools\ace-loader\lib\templater\lite-validator.js

IDE5.0：js\build-tools\ace-loader\lib\templater\lite_component_map.js

在Deveco Studio中使用：

<!-- index.hml -->
<div class="full">
    <canvas class="canvas" ref="home"></canvas>
</div>

名称	类型	默认值	必填	说明
color	<color>	#6b9ac7	否	设置进度条的颜色。
stroke-width	<length>	32px	否	设置进度条的宽度。