1# Color Gradient 2 3Create a more gorgeous look for a component by applying a color gradient effect to it. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> Color gradients are considered part of the component's content and are drawn above the background. 10> 11> Color gradients do not support explicit width and height animations. When the width or height of a component is animated with a color gradient, the gradient will jump straight to the final size. 12 13## linearGradient 14 15linearGradient(value: {angle?: number | string; direction?: GradientDirection; colors: Array\<[ResourceColor, number]>; repeating?: boolean;}) 16 17Creates a linear gradient. 18 19**Widget capability**: This API can be used in ArkTS widgets since API version 9. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name| Type | Mandatory| Description | 28| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 29| value | {<br>angle?: number \| string,<br>direction?: [GradientDirection](ts-appendix-enums.md#gradientdirection),<br>colors: Array<[[ResourceColor](ts-types.md#resourcecolor), number]>,<br>repeating?: boolean<br>} | Yes | Linear gradient.<br> Value range: (-∞, +∞)<br>- **angle**: start angle of the linear gradient. A positive value indicates a clockwise rotation from the origin, (0, 0).<br> Default value: **180**<br>If the angle is specified with a string, only the deg, grad, rad, and turn types are supported.<br>- **direction**: direction of the linear gradient. It does not take effect when **angle** is set.<br> Default value: **GradientDirection.Bottom**<br>- [colors](#radialgradientoptions18): array of color stops, each of which consists of a color and its stop position. Invalid colors are automatically skipped.<br>- **repeating**: whether the colors are repeated.<br> Default value: **false**| 30 31## linearGradient<sup>18+</sup> 32 33linearGradient(options: Optional\<LinearGradientOptions>) 34 35Creates a linear gradient. Compared to [linearGradient](#lineargradient), this API supports the **undefined** type for the **options** parameter. 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| options | Optional\<[LinearGradientOptions](#lineargradientoptions18)> | Yes | Linear gradient.<br>If **options** is **undefined**, the linear gradient is disabled.| 48 49## LinearGradientOptions<sup>18+</sup> 50 51Defines the linear gradient parameters. 52 53**Atomic service API**: This API can be used in atomic services since API version 16. 54 55**System capability**: SystemCapability.ArkUI.ArkUI.Full 56 57| Name | Type | Mandatory| Description | 58| ------------------------------------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 59| angle | number \| string | No | Start angle of the linear gradient. A positive value indicates a clockwise rotation from the origin, (0, 0). The default value is **180**. If the angle is specified with a string, only the deg, grad, rad, and trun types are supported.| 60| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | No | Direction of the linear gradient. It does not take effect when **angle** is set. <br>Default value: **GradientDirection.Bottom**.| 61| [colors](#radialgradientoptions18) | Array[[ResourceColor](ts-types.md#resourcecolor), number] | Yes | Array of color stops, each of which consists of a color and its stop position. Invalid colors are automatically skipped.| 62| repeating | boolean | No | Whether the colors are repeated. Default value: **false**. | 63 64## sweepGradient 65 66sweepGradient(value: {center: [Length, Length]; start?: number | string; end?: number | string; rotation?: number | string; colors: Array\<[ResourceColor, number]>; repeating?: boolean;}) 67 68Creates a sweep gradient. 69 70**Atomic service API**: This API can be used in atomic services since API version 11. 71 72**System capability**: SystemCapability.ArkUI.ArkUI.Full 73 74**Widget capability**: This API can be used in ArkTS widgets since API version 9. 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 80| value | {<br>center: [[Length](./ts-types.md#length), Length],<br>start?: number \| string,<br>end?: number \| string,<br>rotation?: number \| string,<br>colors: Array<[[ResourceColor](ts-types.md#resourcecolor), number]>,<br>repeating?: boolean<br>} | Yes | Sweep gradient, which can sweep around the specified center point in the 0–360 degree range. If the rotation angle exceeds the range, a monochrome color instead of a gradient will be drawn.<br>- **center**: center of the sweep gradient, that is, the coordinates relative to the upper left corner of the current component.<br>- **start**: start angle of the sweep gradient.<br> Default value: **0**<br>If the angle is specified with a string, only the deg, grad, rad, and turn types are supported.<br>- **end**: end angle of the sweep gradient.<br> Default value: **0**<br>If the angle is specified with a string, only the deg, grad, rad, and turn types are supported.<br>- **rotation**: rotation angle of the sweep gradient.<br> Default value: **0**<br>If the angle is specified with a string, only the deg, grad, rad, and turn types are supported.<br>- [colors](#radialgradientoptions18): array of color stops, each of which consists of a color and its stop position. Invalid colors are automatically skipped.<br>- **repeating**: whether the colors are repeated.<br> Default value: **false**<br>**NOTE**<br>A value less than 0 is treated as **0**. A value greater than 360 is treated as **360**.<br>When **start**, **end**, or **rotation** is specified with a string, the string must be a number or a number followed by one of the following units: deg, rad, grad, and turn. Valid value examples are "90", "90deg", and "1.57rad".| 81 82## sweepGradient<sup>18+</sup> 83 84sweepGradient(options: Optional\<SweepGradientOptions>) 85 86Creates a sweep gradient. Compared to [sweepGradient](#sweepgradient), this API supports the **undefined** type for the **options** parameter. 87 88**Atomic service API**: This API can be used in atomic services since API version 18. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92**Widget capability**: This API can be used in ArkTS widgets since API version 18. 93 94**Parameters** 95 96| Name | Type | Mandatory| Description | 97| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 98| options | Optional\<[SweepGradientOptions](#sweepgradientoptions18)> | Yes | Sweep gradient.<br>If **options** is **undefined**, the sweep gradient is disabled.| 99 100## SweepGradientOptions<sup>18+</sup> 101 102Defines the sweep gradient parameters. 103 104**Atomic service API**: This API can be used in atomic services since API version 18. 105 106**System capability**: SystemCapability.ArkUI.ArkUI.Full 107 108| Name | Type | Mandatory| Description | 109| ------------------------------------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 110| center | [[Length](./ts-types.md#length), Length] | Yes | Center of the sweep gradient, that is, the coordinates relative to the upper left corner of the current component. | 111| start | number \| string | No | Start point of the sweep gradient. <br>Default value: **0**. | 112| end | number \| string | No | End point of the sweep gradient. <br>Default value: **0**. | 113| rotation | number \| string | No | Rotation angle of the sweep gradient. Default value: **0**. | 114| [colors](#radialgradientoptions18) | Array<[[ResourceColor](ts-types.md#resourcecolor), number] | Yes | Array of color stops, each of which consists of a color and its stop position. Invalid colors are automatically skipped.| 115| repeating | boolean | No | Whether the colors are repeated. Default value: **false**. | 116 117## radialGradient 118 119radialGradient(value: { center: [Length, Length]; radius: number | string; colors: Array\<[ResourceColor, number]>; repeating?: boolean }) 120 121Creates a radial gradient. 122 123**Atomic service API**: This API can be used in atomic services since API version 11. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Widget capability**: This API can be used in ArkTS widgets since API version 9. 128 129**Parameters** 130 131 132| Name| Type | Mandatory| Description | 133| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 134| value | {<br>center: [[Length](./ts-types.md#length), Length],<br> radius: number \| string,<br>colors: Array<[[ResourceColor](ts-types.md#resourcecolor), number]>,<br>repeating?: boolean<br>} | Yes | Radial gradient.<br>- **center**: center of the radial gradient, that is, the coordinates relative to the upper left corner of the current component.<br>- **radius**: radius of the radial gradient.<br> Value range: [0, +∞).<br>**NOTE**<br>A value less than 0 is treated as **0**.<br>- [colors](#radialgradientoptions18): array of color stops, each of which consists of a color and its stop position. Invalid colors are automatically skipped.<br>- **repeating**: whether the colors are repeated.<br> Default value: **false**.| 135 136## radialGradient<sup>18+</sup> 137 138radialGradient(options: Optional\<RadialGradientOptions>) 139 140Creates a radial gradient. Compared to [radialGradient](#radialgradient), this API supports the **undefined** type for the **options** parameter. 141 142**Atomic service API**: This API can be used in atomic services since API version 18. 143 144**System capability**: SystemCapability.ArkUI.ArkUI.Full 145 146**Widget capability**: This API can be used in ArkTS widgets since API version 18. 147 148**Parameters** 149 150 151| Name | Type | Mandatory | Description | 152| -------------- | -------------------------------------------- | ----------------------------------- | ----------------------------------- | 153| options | Optional\<[RadialGradientOptions](#radialgradientoptions18)> | Yes| Radial gradient.<br>If **options** is **undefined**, the radial gradient is disabled.| 154## RadialGradientOptions<sup>18+</sup> 155 156Defines the radial gradient parameters. 157 158**Atomic service API**: This API can be used in atomic services since API version 18. 159 160**System capability**: SystemCapability.ArkUI.ArkUI.Full 161 162| Name | Type | Mandatory| Description | 163| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------ | 164| center | [[Length](./ts-types.md#length), Length] | Yes | Center of the radial gradient, that is, the coordinates relative to the upper left corner of the current component. | 165| radius | number \| string | Yes | Radius of the radial gradient.<br>Value range: [0, +∞). | 166| colors | Array<[[ResourceColor](ts-types.md#resourcecolor), number]> | Yes | Array of color stops, each of which consists of a color and its stop position. Invalid colors are automatically skipped.| 167| repeating | boolean | No | Whether the colors are repeated. Default value: **false**. | 168 169> **NOTE** 170> 171> When using the **colors** parameter, take note of the following: 172> 173> [ResourceColor](ts-types.md#resourcecolor) indicates the color, and **number** indicates the color's position, which ranges from 0 to 1.0: **0** indicates the start of the container, and **1.0** indicates the end of the container. To create a gradient with multiple color stops, you are advised to set the **number** values in ascending order. If a value of **number** in an array is smaller than that in the previous one, it is considered as equal to the previous value. 174 175 176## Example 177 178### Example 1: Creating a Linear Gradient 179 180This example demonstrates how to create a linear gradient using **linearGradient**. 181 182```ts 183// xxx.ets 184@Entry 185@Component 186struct ColorGradientExample { 187 build() { 188 Column({ space: 5 }) { 189 Text('linearGradient').fontSize(12).width('90%').fontColor(0xCCCCCC) 190 Row() 191 .width('90%') 192 .height(50) 193 .linearGradient({ 194 angle: 90, 195 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 196 }) 197 Text('linearGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC) 198 Row() 199 .width('90%') 200 .height(50) 201 .linearGradient({ 202 direction: GradientDirection.Left, // Gradient direction. 203 repeating: true, // Whether the gradient colors are repeated. 204 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // The gradient colors are repeated because the last color stop is less than 1. 205 }) 206 } 207 .width('100%') 208 .padding({ top: 5 }) 209 } 210} 211``` 212 213 214 215### Example 2: Creating a Sweep Gradient 216 217This example demonstrates how to create a sweep gradient that changes color based on a rotation angle using **sweepGradient**. 218 219```ts 220@Entry 221@Component 222struct ColorGradientExample { 223 build() { 224 Column({ space: 5 }) { 225 Text('sweepGradient').fontSize(12).width('90%').fontColor(0xCCCCCC) 226 Row() 227 .width(100) 228 .height(100) 229 .sweepGradient({ 230 center: [50, 50], 231 start: 0, 232 end: 359, 233 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 234 }) 235 236 Text('sweepGradient Reapeat').fontSize(12).width('90%').fontColor(0xCCCCCC) 237 Row() 238 .width(100) 239 .height(100) 240 .sweepGradient({ 241 center: [50, 50], 242 start: 0, 243 end: 359, 244 rotation: 45, // Rotation angle. 245 repeating: true, // Whether the gradient colors are repeated. 246 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // The gradient colors are repeated because the last color stop is less than 1. 247 }) 248 } 249 .width('100%') 250 .padding({ top: 5 }) 251 } 252} 253``` 254 255 256 257### Example 3: Creating a Radial Gradient 258 259This example demonstrates how to create a radial gradient using **radialGradient**. 260 261```ts 262// xxx.ets 263@Entry 264@Component 265struct ColorGradientExample { 266 build() { 267 Column({ space: 5 }) { 268 Text('radialGradient').fontSize(12).width('90%').fontColor(0xCCCCCC) 269 Row() 270 .width(100) 271 .height(100) 272 .radialGradient({ 273 center: [50, 50], 274 radius: 60, 275 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 276 }) 277 Text('radialGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC) 278 Row() 279 .width(100) 280 .height(100) 281 .radialGradient({ 282 center: [50, 50], 283 radius: 60, 284 repeating: true, 285 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // The gradient colors are repeated because the last color stop is less than 1. 286 }) 287 } 288 .width('100%') 289 .padding({ top: 5 }) 290 } 291} 292``` 293 294 295
