1# Marquee 2 3The **Marquee** component is used to display a scrolling piece of text. The text is scrolled only when its width exceeds the width of the **Marquee** component. 4 5 6> **NOTE** 7> 8> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 9> 10> To ensure that scrolling frame rates are not affected, it is recommended that the number of **Marquee** components in a scroll container does not exceed four, or alternatively, use the [Text](ts-basic-components-text.md) component's [TextOverflow.MARQUEE](ts-appendix-enums.md#textoverflow) as a substitute. 11 12## Child Components 13 14Not supported 15 16 17## APIs 18 19Marquee(options: MarqueeOptions) 20 21**Widget capability**: This API can be used in ArkTS widgets since API version 9. 22 23**Atomic service API**: This API can be used in atomic services since API version 11. 24 25**System capability**: SystemCapability.ArkUI.ArkUI.Full 26 27**Parameters** 28 29| Name| Type| Mandatory| Description| 30| -------- | -------- | -------- | -------- | 31| options | [MarqueeOptions](#marqueeoptions18) | Yes| Parameters of the marquee.| 32 33## MarqueeOptions<sup>18+</sup> 34 35Describes the initialization options of the **Marquee** component. 36 37**Widget capability**: This API can be used in ArkTS widgets since API version 18. 38 39**Atomic service API**: This API can be used in atomic services since API version 18. 40 41**System capability**: SystemCapability.ArkUI.ArkUI.Full 42 43**Parameters** 44 45| Name| Type| Mandatory| Description| 46| -------- | -------- | -------- | -------- | 47| start<sup>8+</sup> | boolean | Yes| Whether to start scrolling.<br>**true**: Start scrolling.<br>**false**: Do not start scrolling.<br>**NOTE**<br>This parameter cannot be used to restart scrolling that has been completed.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 48| step<sup>8+</sup> | number | No| Step length of the scrolling animation text. If the value is greater than the text width of the marquee, the default value is used.<br>Default value: **6**<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 49| loop<sup>8+</sup> | number | No| Number of times the marquee will scroll. If the value is less than or equal to **0**, the marquee will scroll continuously.<br>Default value: **-1**<br>**NOTE**<br>Regardless of the value, the marquee scrolls only once on an ArkTS widget.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 50| fromStart<sup>8+</sup> | boolean | No| Whether the text scrolls from the start.<br>Default value: **true**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 51| src<sup>8+</sup> | string | Yes| Text to scroll.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 52 53## Attributes 54 55In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 56 57### fontColor 58 59fontColor(value: ResourceColor) 60 61Sets the font color. 62 63**Widget capability**: This API can be used in ArkTS widgets since API version 9. 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69**Parameters** 70 71| Name| Type | Mandatory| Description | 72| ------ | ------------------------------------------ | ---- | ---------- | 73| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color.| 74 75### fontSize 76 77fontSize(value: Length) 78 79Sets the text size. 80 81**Widget capability**: This API can be used in ArkTS widgets since API version 9. 82 83**Atomic service API**: This API can be used in atomic services since API version 11. 84 85**System capability**: SystemCapability.ArkUI.ArkUI.Full 86 87**Parameters** 88 89| Name| Type | Mandatory| Description | 90| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 91| value | [Length](ts-types.md#length) | Yes | Font size. If **fontSize** is of the number type, the unit fp is used. The default font size is 16 fp. This parameter cannot be set in percentage.| 92 93### fontWeight 94 95fontWeight(value: number | FontWeight | string) 96 97Sets the font weight. If the value is too large, the text may be clipped depending on the font. 98 99**Widget capability**: This API can be used in ArkTS widgets since API version 9. 100 101**Atomic service API**: This API can be used in atomic services since API version 11. 102 103**System capability**: SystemCapability.ArkUI.ArkUI.Full 104 105**Parameters** 106 107| Name| Type | Mandatory| Description | 108| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 109| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | Yes | Font weight. For the number type, the value range is [100, 900], at an interval of 100. The default value is **400**. A larger value indicates a heavier font weight. For the string type, only strings that represent a number, for example, **"400"**, and the following enumerated values of **FontWeight** are supported: **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**.<br>Default value: **FontWeight.Normal**| 110 111### fontFamily 112 113fontFamily(value: string | Resource) 114 115Sets the font family. 116 117**Widget capability**: This API can be used in ArkTS widgets since API version 9. 118 119**Atomic service API**: This API can be used in atomic services since API version 11. 120 121**System capability**: SystemCapability.ArkUI.ArkUI.Full 122 123**Parameters** 124 125| Name| Type | Mandatory| Description | 126| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 127| value | string \| [Resource](ts-types.md#resource) | Yes | Font family. Default font: **'HarmonyOS Sans'**<br>The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported for applications.<br>Only the 'HarmonyOS Sans' font is supported for widgets.| 128 129### allowScale 130 131allowScale(value: boolean) 132 133Sets whether to allow text to scale. 134 135**Widget capability**: This API can be used in ArkTS widgets since API version 9. 136 137**Atomic service API**: This API can be used in atomic services since API version 11. 138 139**System capability**: SystemCapability.ArkUI.ArkUI.Full 140 141**Parameters** 142 143| Name| Type | Mandatory| Description | 144| ------ | ------- | ---- | ------------------------------------ | 145| value | boolean | Yes | Whether to allow text to scale.<br>Default value: **false**<br>**NOTE**<br>This parameter is effective only when **fontSize** is in fp units.| 146 147### marqueeUpdateStrategy<sup>12+</sup> 148 149marqueeUpdateStrategy(value: MarqueeUpdateStrategy) 150 151Sets the scrolling strategy for the marquee after its attributes are updated. (This attribute takes effect when the marquee is in the playing state and the text content width exceeds the width of the marquee component.) 152 153**Atomic service API**: This API can be used in atomic services since API version 12. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ------- | ---- | ------------------------------------ | 161| value |[MarqueeUpdateStrategy](ts-appendix-enums.md#marqueeupdatestrategy12) | Yes| Scrolling strategy of the marquee after its attributes are updated.<br>Default value: **MarqueeUpdateStrategy.DEFAULT**| 162 163## Events 164 165### onStart 166 167onStart(event: () => void) 168 169Called when the marquee text changes or starts scrolling. 170 171**Widget capability**: This API can be used in ArkTS widgets since API version 9. 172 173**Atomic service API**: This API can be used in atomic services since API version 11. 174 175**System capability**: SystemCapability.ArkUI.ArkUI.Full 176 177### onBounce 178 179onBounce(event: () => void) 180 181Triggered when the marquee has reached the end. This event will be triggered for multiple times if the **loop** attribute is not set to **1**. 182 183**Widget capability**: This API can be used in ArkTS widgets since API version 9. 184 185**Atomic service API**: This API can be used in atomic services since API version 11. 186 187**System capability**: SystemCapability.ArkUI.ArkUI.Full 188 189### onFinish 190 191onFinish(event: () => void) 192 193Triggered when the marquee has finished the number of scrolling times set by the **loop** attribute. 194 195**Widget capability**: This API can be used in ArkTS widgets since API version 9. 196 197**Atomic service API**: This API can be used in atomic services since API version 11. 198 199**System capability**: SystemCapability.ArkUI.ArkUI.Full 200 201## Example 202 203This example demonstrates the dynamic updating of a marquee's content by setting properties such as **start**, **step**, **loop**, **fromStart**, **src**, and **marqueeUpdateStrategy**. 204 205```ts 206// xxx.ets 207@Entry 208@Component 209struct MarqueeExample { 210 @State start: boolean = false; 211 @State src: string = ''; 212 @State marqueeText: string = 'Running Marquee'; 213 private fromStart: boolean = true; 214 private step: number = 10; 215 private loop: number = Number.POSITIVE_INFINITY; 216 controller: TextClockController = new TextClockController(); 217 218 convert2time(value: number): string { 219 let date = new Date(Number(value + '000')); 220 let hours = date.getHours().toString().padStart(2, '0'); 221 let minutes = date.getMinutes().toString().padStart(2, '0'); 222 let seconds = date.getSeconds().toString().padStart(2, '0'); 223 return hours + ":" + minutes + ":" + seconds; 224 } 225 226 build() { 227 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 228 Marquee({ 229 start: this.start, 230 step: this.step, 231 loop: this.loop, 232 fromStart: this.fromStart, 233 src: this.marqueeText + this.src 234 }) 235 .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION) 236 .width('300vp') 237 .height('80vp') 238 .fontColor('#FFFFFF') 239 .fontSize('48fp') 240 .allowScale(true) // Set this to true if you want the marquee text to scale with the system font size when using the fp unit for fontSize. 241 .fontWeight(700) 242 .fontFamily('HarmonyOS Sans') // Use 'HarmonyOS Sans' to avoid following the theme font. 243 .backgroundColor('#182431') 244 .margin({ bottom: '40vp' }) 245 .onStart(() => { 246 console.info('Succeeded in completing the onStart callback of marquee animation'); 247 }) 248 .onBounce(() => { 249 console.info('Succeeded in completing the onBounce callback of marquee animation'); 250 }) 251 .onFinish(() => { 252 console.info('Succeeded in completing the onFinish callback of marquee animation'); 253 }) 254 Button('Start') 255 .onClick(() => { 256 this.start = true 257 // Start the text clock. 258 this.controller.start(); 259 }) 260 .width('120vp') 261 .height('40vp') 262 .fontSize('16fp') 263 .fontWeight(500) 264 .backgroundColor('#007DFF') 265 TextClock({ timeZoneOffset: -8, controller: this.controller }) 266 .format('hms') 267 .onDateChange((value: number) => { 268 this.src = this.convert2time(value); 269 }) 270 .margin('20vp') 271 .fontSize('30fp') 272 } 273 .width('100%') 274 .height('100%') 275 } 276} 277``` 278 279 280
