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(value: { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string }) 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| value | { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string } | Yes| Parameters of the marquee.<br>**start**: whether to start scrolling.<br>**NOTE**<br>This parameter cannot be used to restart scrolling that has been completed.<br>- **step**: scrolling step. If the step is greater than the text width, the default value is taken.<br>Default value: **6**, in vp<br>- **loop**: 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>- **fromStart**: whether the text scrolls from the start.<br>Default value: **true**<br>- **src**: text to scroll.| 32 33## Attributes 34 35In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 36 37### fontColor 38 39fontColor(value: ResourceColor) 40 41Sets the font color. 42 43**Widget capability**: This API can be used in ArkTS widgets since API version 9. 44 45**Atomic service API**: This API can be used in atomic services since API version 11. 46 47**System capability**: SystemCapability.ArkUI.ArkUI.Full 48 49**Parameters** 50 51| Name| Type | Mandatory| Description | 52| ------ | ------------------------------------------ | ---- | ---------- | 53| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color.| 54 55### fontSize 56 57fontSize(value: Length) 58 59Sets the text size. 60 61**Widget capability**: This API can be used in ArkTS widgets since API version 9. 62 63**Atomic service API**: This API can be used in atomic services since API version 11. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67**Parameters** 68 69| Name| Type | Mandatory| Description | 70| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 71| 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.| 72 73### fontWeight 74 75fontWeight(value: number | FontWeight | string) 76 77Sets the font weight. If the value is too large, the text may be clipped depending on the font. 78 79**Widget capability**: This API can be used in ArkTS widgets since API version 9. 80 81**Atomic service API**: This API can be used in atomic services since API version 11. 82 83**System capability**: SystemCapability.ArkUI.ArkUI.Full 84 85**Parameters** 86 87| Name| Type | Mandatory| Description | 88| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 89| 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**| 90 91### fontFamily 92 93fontFamily(value: string | Resource) 94 95Sets the font family. 96 97**Widget capability**: This API can be used in ArkTS widgets since API version 9. 98 99**Atomic service API**: This API can be used in atomic services since API version 11. 100 101**System capability**: SystemCapability.ArkUI.ArkUI.Full 102 103**Parameters** 104 105| Name| Type | Mandatory| Description | 106| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 107| 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.| 108 109### allowScale 110 111allowScale(value: boolean) 112 113Sets whether to allow text to scale. 114 115**Widget capability**: This API can be used in ArkTS widgets since API version 9. 116 117**Atomic service API**: This API can be used in atomic services since API version 11. 118 119**System capability**: SystemCapability.ArkUI.ArkUI.Full 120 121**Parameters** 122 123| Name| Type | Mandatory| Description | 124| ------ | ------- | ---- | ------------------------------------ | 125| 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.| 126 127### marqueeUpdateStrategy<sup>12+</sup> 128 129marqueeUpdateStrategy(value: MarqueeUpdateStrategy) 130 131Sets 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.) 132 133**Atomic service API**: This API can be used in atomic services since API version 12. 134 135**System capability**: SystemCapability.ArkUI.ArkUI.Full 136 137**Parameters** 138 139| Name| Type | Mandatory| Description | 140| ------ | ------- | ---- | ------------------------------------ | 141| value |[MarqueeUpdateStrategy](ts-appendix-enums.md#marqueeupdatestrategy12) | Yes| Scrolling strategy of the marquee after its attributes are updated.<br>Default value: **MarqueeUpdateStrategy.DEFAULT**| 142 143## Events 144 145### onStart 146 147onStart(event: () => void) 148 149Called when the marquee text changes or starts scrolling. 150 151**Widget capability**: This API can be used in ArkTS widgets since API version 9. 152 153**Atomic service API**: This API can be used in atomic services since API version 11. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157### onBounce 158 159onBounce(event: () => void) 160 161Triggered when the marquee has reached the end. This event will be triggered for multiple times if the **loop** attribute is not set to **1**. 162 163**Widget capability**: This API can be used in ArkTS widgets since API version 9. 164 165**Atomic service API**: This API can be used in atomic services since API version 11. 166 167**System capability**: SystemCapability.ArkUI.ArkUI.Full 168 169### onFinish 170 171onFinish(event: () => void) 172 173Triggered when the marquee has finished the number of scrolling times set by the **loop** attribute. 174 175**Widget capability**: This API can be used in ArkTS widgets since API version 9. 176 177**Atomic service API**: This API can be used in atomic services since API version 11. 178 179**System capability**: SystemCapability.ArkUI.ArkUI.Full 180 181## Example 182 183This example demonstrates the dynamic updating of a marquee's content by setting properties such as **start**, **step**, **loop**, **fromStart**, **src**, and **marqueeUpdateStrategy**. 184 185```ts 186// xxx.ets 187@Entry 188@Component 189struct MarqueeExample { 190 @State start: boolean = false 191 @State src: string = '' 192 @State marqueeText: string = 'Running Marquee' 193 private fromStart: boolean = true 194 private step: number = 10 195 private loop: number = Number.POSITIVE_INFINITY 196 controller: TextClockController = new TextClockController() 197 convert2time(value: number): string{ 198 let date = new Date(Number(value+'000')); 199 let hours = date.getHours().toString().padStart(2, '0'); 200 let minutes = date.getMinutes().toString().padStart(2, '0'); 201 let seconds = date.getSeconds().toString().padStart(2, '0'); 202 return hours+ ":" + minutes + ":" + seconds; 203 } 204 205 build() { 206 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 207 Marquee({ 208 start: this.start, 209 step: this.step, 210 loop: this.loop, 211 fromStart: this.fromStart, 212 src: this.marqueeText + this.src 213 }) 214 .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION) 215 .width('300vp') 216 .height('80vp') 217 .fontColor('#FFFFFF') 218 .fontSize('48fp') 219 .fontWeight(700) 220 .backgroundColor('#182431') 221 .margin({ bottom: '40vp' }) 222 .onStart(() => { 223 console.info('Succeeded in completing the onStart callback of marquee animation') 224 }) 225 .onBounce(() => { 226 console.info('Succeeded in completing the onBounce callback of marquee animation') 227 }) 228 .onFinish(() => { 229 console.info('Succeeded in completing the onFinish callback of marquee animation') 230 }) 231 Button('Start') 232 .onClick(() => { 233 this.start = true 234 // Start the text clock. 235 this.controller.start() 236 }) 237 .width('120vp') 238 .height('40vp') 239 .fontSize('16fp') 240 .fontWeight(500) 241 .backgroundColor('#007DFF') 242 TextClock({ timeZoneOffset: -8, controller: this.controller }) 243 .format('hms') 244 .onDateChange((value: number) => { 245 this.src = this.convert2time(value); 246 }) 247 .margin('20vp') 248 .fontSize('30fp') 249 } 250 .width('100%') 251 .height('100%') 252 } 253} 254``` 255 256 257
