1# Marquee 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @hddgzw--> 5<!--Designer: @pssea--> 6<!--Tester: @jiaoaozihao--> 7<!--Adviser: @HelloCrease--> 8 9跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度大于等于跑马灯组件宽度时滚动，当文本内容宽度小于跑马灯组件宽度时不滚动。 10 11 12> **说明：** 13> 14> 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15> 16> 为了不影响滚动帧率，建议在滚动类组件中Marquee的个数不超过4个，或者使用[Text](ts-basic-components-text.md)组件的[TextOverflow.MARQUEE](ts-appendix-enums.md#textoverflow)替代。 17> 18> 对于Marquee组件动态帧率的场景，可以使用[MarqueeDynamicSyncScene](../arkts-apis-uicontext-marqueedynamicsyncscene.md)接口实现。 19> 20> 在文本宽度小于跑马灯组件宽度时，使用[属性动画](ts-animatorproperty.md)实现滚动。 21 22## 子组件 23 24无 25 26 27## 接口 28 29Marquee(options: MarqueeOptions) 30 31**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 32 33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| -------- | -------- | -------- | -------- | 41| options | [MarqueeOptions](#marqueeoptions18对象说明)<sup>18+</sup> | 是 | 配置跑马灯组件的参数。| 42 43## MarqueeOptions<sup>18+</sup>对象说明 44 45Marquee初始化参数。 46 47> **说明：** 48> 49> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 50 51**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 52 53**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 54 55**系统能力：** SystemCapability.ArkUI.ArkUI.Full 56 57**参数：** 58 59| 名称 | 类型 | 只读 | 可选 | 说明 | 60| -------- | -------- | -------- | -------- | -------- | 61| start<sup>8+</sup> | boolean | 否 | 否 | 控制跑马灯是否进入播放状态。<br/>true表示播放，false表示不播放。<br/>**说明：**<br/>有限的滚动次数播放完毕后，不可以通过改变start重置滚动次数重新开始播放。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 62| step<sup>8+</sup> | number | 否 | 是 | 滚动动画文本滚动步长。当step大于Marquee的文本宽度时，取默认值。<br/>默认值：6 <br/>单位：[vp](ts-pixel-units.md) <br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 63| loop<sup>8+</sup> | number | 否 | 是 | 设置重复滚动的次数，小于等于零时无限循环。<br/>默认值：-1<br/>**说明：**<br/>ArkTS卡片上该参数设置任意值都仅在可见时滚动一次。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 64| fromStart<sup>8+</sup> | boolean | 否 | 是 | 设置文本从头开始滚动或反向滚动。<br/>true表示从头开始滚动，false表示反向滚动。<br/>默认值：true<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 65| src<sup>8+</sup> | string | 否 | 否 | 需要滚动的文本。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 66 67## 属性 68 69除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 70 71### fontColor 72 73fontColor(value: ResourceColor) 74 75设置字体颜色。 76 77**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 78 79**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83**参数：** 84 85| 参数名 | 类型 | 必填 | 说明 | 86| ------ | ------------------------------------------ | ---- | ---------- | 87| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 字体颜色。 | 88 89### fontSize 90 91fontSize(value: Length) 92 93设置字体大小。 94 95**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 96 97**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 98 99**系统能力：** SystemCapability.ArkUI.ArkUI.Full 100 101**参数：** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 105| value | [Length](ts-types.md#length) | 是 | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。 | 106 107### fontWeight 108 109fontWeight(value: number | FontWeight | string) 110 111设置文本的字体粗细，设置过大可能会在不同字体下有截断。 112 113**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 114 115**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 116 117**系统能力：** SystemCapability.ArkUI.ArkUI.Full 118 119**参数：** 120 121| 参数名 | 类型 | 必填 | 说明 | 122| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 123| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | 是 | 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal | 124 125### fontFamily 126 127fontFamily(value: string | Resource) 128 129设置字体列表。 130 131**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 132 133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 141| value | string \| [Resource](ts-types.md#resource) | 是 | 字体列表。默认字体'HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和注册自定义字体[loadFontSync](../../apis-arkgraphics2d/js-apis-graphics-text.md#loadfontsync)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 | 142 143### allowScale 144 145allowScale(value: boolean) 146 147设置是否允许文本缩放。 148 149**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 150 151**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 152 153**系统能力：** SystemCapability.ArkUI.ArkUI.Full 154 155**参数：** 156 157| 参数名 | 类型 | 必填 | 说明 | 158| ------ | ------- | ---- | ------------------------------------ | 159| value | boolean | 是 | 是否允许文本缩放。<br/>true表示允许文本缩放，false表示不允许文本缩放。<br/>默认值：false<br/>**说明：**<br/>仅当fontSize为fp单位时生效。 | 160 161### marqueeUpdateStrategy<sup>12+</sup> 162 163marqueeUpdateStrategy(value: MarqueeUpdateStrategy) 164 165跑马灯组件属性更新后，跑马灯的滚动策略。(当跑马灯为播放状态，且文本内容宽度超过跑马灯组件宽度时，该属性生效。) 166 167**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 168 169**系统能力：** SystemCapability.ArkUI.ArkUI.Full 170 171**参数：** 172 173| 参数名 | 类型 | 必填 | 说明 | 174| ------ | ------- | ---- | ------------------------------------ | 175| value |[MarqueeUpdateStrategy](ts-appendix-enums.md#marqueeupdatestrategy12) | 是 | 跑马灯组件属性更新后，跑马灯的滚动策略。<br/>默认值: MarqueeUpdateStrategy.DEFAULT | 176 177## 事件 178 179### onStart 180 181onStart(event: () => void) 182 183当滚动的文本内容变化或者开始滚动时触发回调。 184 185**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 186 187**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 188 189**系统能力：** SystemCapability.ArkUI.ArkUI.Full 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| ------ | ------------------------------------- | ---- | -------------- | 195| event | () => void | 是 | 当滚动的文本内容变化或者开始滚动时的回调。 | 196 197### onBounce 198 199onBounce(event: () => void) 200 201完成一次滚动时触发，若循环次数不为1，则该事件会多次触发。 202 203**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 204 205**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 206 207**系统能力：** SystemCapability.ArkUI.ArkUI.Full 208 209**参数：** 210 211| 参数名 | 类型 | 必填 | 说明 | 212| ------ | ------------------------------------- | ---- | -------------- | 213| event | () => void | 是 | 完成一次滚动时触发的回调。 | 214 215### onFinish 216 217onFinish(event: () => void) 218 219滚动全部循环次数完成时触发回调。 220 221**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 222 223**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 224 225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| ------ | ------------------------------------- | ---- | -------------- | 231| event | () => void | 是 | 滚动全部循环次数完成时的回调。 | 232 233## 示例 234 235该示例通过设置start、step、loop、fromStart、src、[marqueeUpdateStrategy](#marqueeupdatestrategy12)（从API version 12开始）展示了跑马灯内容动态更新时运行的效果。 236 237```ts 238// xxx.ets 239@Entry 240@Component 241struct MarqueeExample { 242 @State start: boolean = false; 243 @State src: string = ''; 244 @State marqueeText: string = 'Running Marquee'; 245 private fromStart: boolean = true; 246 private step: number = 10; 247 private loop: number = Number.POSITIVE_INFINITY; 248 controller: TextClockController = new TextClockController(); 249 250 convert2time(value: number): string { 251 let date = new Date(Number(value + '000')); 252 let hours = date.getHours().toString().padStart(2, '0'); 253 let minutes = date.getMinutes().toString().padStart(2, '0'); 254 let seconds = date.getSeconds().toString().padStart(2, '0'); 255 return hours + ":" + minutes + ":" + seconds; 256 } 257 258 build() { 259 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 260 Marquee({ 261 start: this.start, 262 step: this.step, 263 loop: this.loop, 264 fromStart: this.fromStart, 265 src: this.marqueeText + this.src 266 }) 267 .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION) 268 .width('300vp') 269 .height('80vp') 270 .fontColor('#FFFFFF') 271 .fontSize('48fp') 272 .allowScale(true) // 当fontSize为‘fp’单位且想要Marquee组件文本跟随系统字体大小缩放，可以设置该属性为true 273 .fontWeight(700) 274 .fontFamily('HarmonyOS Sans') // 不想跟随主题字体可设置该属性为默认字体'HarmonyOS Sans' 275 .backgroundColor('#182431') 276 .margin({ bottom: '40vp' }) 277 .onStart(() => { 278 console.info('Succeeded in completing the onStart callback of marquee animation'); 279 }) 280 .onBounce(() => { 281 console.info('Succeeded in completing the onBounce callback of marquee animation'); 282 }) 283 .onFinish(() => { 284 console.info('Succeeded in completing the onFinish callback of marquee animation'); 285 }) 286 Button('Start') 287 .onClick(() => { 288 this.start = true 289 // 启动文本时钟 290 this.controller.start(); 291 }) 292 .width('120vp') 293 .height('40vp') 294 .fontSize('16fp') 295 .fontWeight(500) 296 .backgroundColor('#007DFF') 297 TextClock({ timeZoneOffset: -8, controller: this.controller }) 298 .format('hms') 299 .onDateChange((value: number) => { 300 this.src = this.convert2time(value); 301 }) 302 .margin('20vp') 303 .fontSize('30fp') 304 } 305 .width('100%') 306 .height('100%') 307 } 308} 309``` 310 311
