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