智慧屏和智能穿戴开发：容器组件marquee

HarmonyOS应用开发文档更新修改说明：marquee组件补充示例代码和示例效果图，方便开发者掌握该组件的使用方式。

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

支持设备

表1 组件的设备支持情况

智慧屏	智能穿戴
支持	支持

权限列表

无

子组件

不支持。

属性

名称	类型	默认值	必填	描述
scrollamount	number	6	否	跑马灯每次滚动时移动的最大长度。
loop	number	-1	否	跑马灯滚动的次数。如果未指定，则默认值为-1，当该值小于等于零时表示marquee将连续滚动。
direction	string	left	否	设置跑马灯的文字滚动方向，可选值为left和right。
id	string	-	否	组件的唯一标识。
style	string	-	否	组件的样式声明。
class	string	-	否	组件的样式类，用于引用样式表。
ref	string	-	否	用来指定指向子元素或子组件的引用信息，该引用将注册到父组件的$refs 属性对象上。
disabled	boolean	false	否	当前组件是否被禁用，在禁用场景下，组件将无法响应用户交互。
focusable	boolean	false	否	当前组件是否可以获取焦点。 当focusable设置为true时，组件可以响应焦点事件和按键事件。当组件额外设置了按键事件或者点击事件时，框架会设置该属性为true。
data	string	-	否	给当前组件设置data属性，进行相应的数据存储和读取。

事件

名称	参数	描述
bounce	-	当文本滚动到末尾时触发该事件。
finish	-	当完成滚动次数时触发该事件。需要在 loop 属性值大于 0 时触发。
start	-	当文本滚动开始时触发该事件。
touchstart	TouchEvent	手指刚触摸屏幕时触发该事件。
touchmove	TouchEvent	手指触摸屏幕后移动时触发该事件。
touchcancel	TouchEvent	手指触摸屏幕中动作被打断时触发该事件。
touchend	TouchEvent	手指触摸结束离开屏幕时触发该事件。
click	-	点击动作触发该事件。
longpress	-	长按动作触发该事件。
focus	-	获得焦点时触发该事件，span组件无法获取焦点。
blur	-	失去焦点时触发该事件，span组件无法失去焦点。
key	KeyEvent	智慧屏特有的按键事件，当用户操作遥控器按键时触发。 返回true表示页面自己处理按键事件。 返回false表示使用默认的按键事件逻辑。 不返回值作为false处理。

样式

名称	类型	默认值	必填	描述
color	<color>	智慧屏：#e5ffffff 智能穿戴：#ffffffff	否	设置跑马灯中文字的文本颜色。
font-size	<length>	37.5	否	设置跑马灯中文字的文本尺寸。
allow-scale	boolean	true	否	设置跑马灯中文字的文本尺寸是否跟随系统设置字体缩放尺寸进行放大缩小。 说明 如果在config描述文件中针对ability配置了fontSize的config-changes标签，则应用不会重启而直接生效。
font-weight	number | string	normal	否	设置跑马灯中文字的字体的粗细，见text组件font-weight的样式属性。
font-family	string	sans-serif	否	设置跑马灯中文字的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过自定义字体指定的字体，会被选中作为文本的字体。
width	<length> | <percentage>	-	否	设置组件自身的宽度。 缺省时使用元素自身内容需要的宽度。
height	<length> | <percentage>	-	否	设置组件自身的高度。 缺省时使用元素自身内容需要的高度。
padding	<length>	0	否	使用简写属性设置所有的内边距属性。 该属性可以有1到4个值： 指定一个值时，该值指定四个边的内边距。 指定两个值时，第一个值指定上下两边的内边距，第二个指定左右两边的内边距。 指定三个值时，第一个指定上边的内边距，第二个指定左右两边的内边距，第三个指定下边的内边距。 指定四个值时分别为上、右、下、左边的内边距（顺时针顺序）。
padding-[left|top|right|bottom]	<length>	0	否	设置左、上、右、下内边距属性。
padding-[start|end]	<length>	0	否	设置起始和末端内边距属性。
margin	<length>	0	否	使用简写属性设置所有的外边距属性，该属性可以有1到4个值。 只有一个值时，这个值会被指定给全部的四个边。 两个值时，第一个值被匹配给上和下，第二个值被匹配给左和右。 三个值时，第一个值被匹配给上, 第二个值被匹配给左和右，第三个值被匹配给下。 四个值时，会依次按上、右、下、左的顺序匹配 (即顺时针顺序)。
margin-[left|top|right|bottom]	<length>	0	否	设置左、上、右、下外边距属性。
margin-[start|end]	<length>	0	否	设置起始和末端外边距属性。
border	-	0	否	使用简写属性设置所有的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置时，各属性值为默认值。
border-style	string	solid	否	使用简写属性设置所有边框的样式，可选值为： dotted：显示为一系列圆点，圆点半径为border-width的一半。 dashed：显示为一系列短的方形虚线。 solid：显示为一条实线。
border-[left|top|right|bottom]-style	string	solid	否	分别设置左、上、右、下四个边框的样式，可选值为dotted、dashed、solid。
border-[left|top|right|bottom]	-	-	否	使用简写属性设置对应位置的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置的值为默认值。
border-width	<length>	0	否	使用简写属性设置元素的所有边框宽度，或者单独为各边边框设置宽度。
border-[left|top|right|bottom]-width	<length>	0	否	分别设置左、上、右、下四个边框的宽度。
border-color	<color>	black	否	使用简写属性设置元素的所有边框颜色，或者单独为各边边框设置颜色。
border-[left|top|right|bottom]-color	<color>	black	否	分别设置左、上、右、下四个边框的颜色。
border-radius	<length>	-	否	border-radius属性是设置元素的外边框圆角半径。设置border-radius时不能单独设置某一个方向的border-[left|top|right|bottom]-width，border-[left|top|right|bottom]-color ，border-[left|top|right|bottom]-style，如果要设置color、width和style，需要将四个方向一起设置（border-width、border-color、border-style）。
border-[top|bottom]-[left|right]-radius	<length>	-	否	分别设置左上，右上，右下和左下四个角的圆角半径。
background	<linear-gradient>	-	否	仅支持设置渐变样式，与background-color、background-image不兼容。
background-color	<color>	-	否	设置背景颜色。
background-image	string	-	否	设置背景图片。与background-color、background不兼容；支持网络图片资源和本地图片资源地址。
background-size	string <length> <length> <percentage> <percentage>	auto	否	设置背景图片的大小。 string可选值： contain：把图像扩展至最大尺寸，以使其高度和宽度完全适用内容区域。 cover：把背景图像扩展至足够大，以使背景图像完全覆盖背景区域；背景图像的某些部分也许无法显示在背景定位区域中。 auto：保持原图的比例不变。 length值参数方式： 设置背景图像的高度和宽度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为 "auto"。 百分比参数方式： 以父元素的百分比来设置背景图像的宽度和高度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为 "auto"。
background-repeat	string	repeat	否	针对重复背景图像样式进行设置，背景图像默认在水平和垂直方向上重复。 repeat：在水平轴和竖直轴上同时重复绘制图片。 repeat-x：只在水平轴上重复绘制图片。 repeat-y：只在竖直轴上重复绘制图片。 no-repeat：不会重复绘制图片。
background-position	string string <length> <length> <percentage> <percentage>	0px 0px	否	关键词方式：如果仅规定了一个关键词，那么第二个值为"center"。两个值分别定义水平方向位置和竖直方向位置。 left：水平方向上最左侧。 right：水平方向上最右侧。 top：竖直方向上最顶部。 bottom：竖直方向上最底部。 center：水平方向或竖直方向上中间位置。 length值参数方式：第一个值是水平位置，第二个值是垂直位置。 左上角是 0 0。单位是像素 (0px 0px) 。如果仅规定了一个值，另外一个值将是50%。 百分比参数方式：第一个值是水平位置，第二个值是垂直位置。左上角是 0% 0%。右下角是 100% 100%。如果仅规定了一个值，另外一个值为50%。 可以混合使用<percentage>和<length>
opacity	number	1	否	元素的透明度，取值范围为0到1，1表示为不透明，0表示为完全透明。
display	string	flex	否	确定一个元素所产生的框的类型，可选值为： flex：弹性布局。 none：不渲染此元素。
visibility	string	visible	否	是否显示元素所产生的框。不可见的框会占用布局（将'display'属性设置为'none'来完全去除框），可选值为： visible：元素正常显示。 hidden：隐藏元素，但是其他元素的布局不改变，相当于此元素变成透明。 说明 visibility和display样式都设置时，仅display生效
flex	number	-	否	规定当前组件如何适应父组件中的可用空间。它作为一个简写属性，用来设置组件的flex-grow。 说明 仅父容器为<div>、<list-item>、<tabs>时生效。
flex-grow	number	0	否	设置组件的拉伸样式，指定父组件容器主轴方向上剩余空间（容器本身大小减去所有flex子元素占用的大小）的分配权重。0为不伸展。 说明 仅父容器为<div>、<list-item>、<tabs>时生效。
flex-shrink	number	1	否	设置组件的收缩样式，元素仅在默认宽度之和大于容器的时候才会发生收缩，0为不收缩。 说明 仅父容器为<div>、<list-item>、<tabs>时生效。
flex-basis	<length>	-	否	设置组件在主轴方向上的初始大小。 说明 仅父容器为<div>、<list-item>、<tabs>时生效。
position	string	relative	否	设置元素的定位类型，不支持动态变更。 fixed：相对与整个界面进行定位。 absolute：相对于父元素进行定位。 relative：相对于其正常位置进行定位。 说明 absolute属性仅在父容器为<div>、<stack>时生效。
[left|top|right|bottom]	<length>	-	否	left|top|right|bottom需要配合position样式使用，来确定元素的偏移位置。 left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。 top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。 right属性规定元素的右边缘。该属性定义了定位元素右外边距边界与其包含块右边界之间的偏移。 bottom属性规定元素的底部边缘。该属性定义了一个定位元素的下外边距边界与其包含块下边界之间的偏移。

方法

名称	参数	描述
start	-	开始滚动。
stop	-	停止滚动。

示例

<!-- xxx.hml -->
<div class="container">
  <marquee id="customMarquee" class="customMarquee" scrollamount="{{scrollAmount}}" loop="{{loop}}"direction="{{marqueeDir}}" onbounce="onMarqueeBounce" onstart="onMarqueeStart" onfinish="onMarqueeFinish">{{marqueeCustomData}}</marquee>
  <div class="content">
    <button class="controlButton" onclick="onStartClick">Start</button>
    <button class="controlButton" onclick="onStopClick">Stop</button>
  </div>
</div>

/* xxx.css */
.container {
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: #ffffff;
}
.customMarquee {
  width: 100%;
  height: 80px;
  padding: 10px;
  margin: 20px;
  border: 4px solid #ff8888;
  border-radius: 20px;
  font-size: 40px;
  color: #ff8888;
  font-weight: bolder;
  font-family: serif;
  background-color: #ffdddd;
}
.content {
  flex-direction: row;
}
.controlButton {
  flex-grow: 1;
}

// xxx.js
export default {
  data: {
    scrollAmount: 30,
    loop: 3,
    marqueeDir: 'left',
    marqueeCustomData: 'Custom marquee',
  },
  onMarqueeBounce: function() {
    console.log("onMarqueeBounce");
  },
  onMarqueeStart: function() {
    console.log("onMarqueeStart");
  },
  onMarqueeFinish: function() {
    console.log("onMarqueeFinish");
  },
  onStartClick (evt) {
    this.$element('customMarquee').start();
  },
  onStopClick (evt) {
    this.$element('customMarquee').stop();
  }
}