1# 颜色渐变 2 3设置组件的颜色渐变效果。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 颜色渐变属于组件内容，绘制在背景上方。 10> 11> 颜色渐变不支持宽高显式动画，执行宽高动画时颜色渐变会直接过渡到终点。 12 13## linearGradient 14 15linearGradient(value: {angle?: number | string; direction?: GradientDirection; colors: Array\<[ResourceColor, number]>; repeating?: boolean;}) 16 17线性渐变。 18 19**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 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/>} | 是 | 线性渐变。<br/> 取值范围：(-∞,+∞) <br/>- angle: 线性渐变的起始角度。0点方向顺时针旋转为正向角度。<br/> 默认值：180<br/>角度为字符串时仅支持类型deg，grad，rad，turn。<br/>- direction: 线性渐变的方向，设置angle后不生效。<br/> 默认值：GradientDirection.Bottom <br/>- [colors](#radialgradientoptions18对象说明): 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。<br/>- repeating: 为渐变的颜色重复着色。 <br/> 默认值：false | 30 31## linearGradient<sup>18+</sup> 32 33linearGradient(options: Optional\<LinearGradientOptions>) 34 35线性渐变。与[linearGradient](#lineargradient)相比，options参数新增了对undefined类型的支持。 36 37**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 38 39**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 47| options | Optional\<[LinearGradientOptions](#lineargradientoptions18对象说明)> | 是 | 线性渐变。<br/>当options的值为undefined时，恢复为无线性渐变的效果。 | 48 49## LinearGradientOptions<sup>18+</sup>对象说明 50 51线性渐变参数。 52 53**原子化服务API：** 从API version 16开始，该接口支持在原子化服务中使用。 54 55**系统能力：** SystemCapability.ArkUI.ArkUI.Full 56 57| 名称 | 类型 | 必填 | 说明 | 58| ------------------------------------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 59| angle | number \| string | 否 | 线性渐变的起始角度。0点方向顺时针旋转为正向角度。默认值：180。角度为字符串时仅支持类型deg，grad，rad，trun。 | 60| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | 否 | 线性渐变的方向，设置angle后不生效。默认值：GradientDirection.Bottom。 | 61| [colors](#radialgradientoptions18对象说明) | Array[[ResourceColor](ts-types.md#resourcecolor), number] | 是 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。 | 62| repeating | boolean | 否 | 为渐变的颜色重复着色。默认值：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 68角度渐变。 69 70**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 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/>} | 是 | 角度渐变，仅绘制0-360度范围内的角度，超出时不绘制渐变色，只绘制纯色。<br/>- center：为角度渐变的中心点，即相对于当前组件左上角的坐标。<br/>- start：角度渐变的起点。<br/> 默认值：0<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- end：角度渐变的终点。<br/> 默认值：0<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- rotation: 角度渐变的旋转角度。<br/> 默认值：0<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- [colors](#radialgradientoptions18对象说明): 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。<br/>- repeating: 为渐变的颜色重复着色。<br/> 默认值：false<br/>**说明：** <br/>设置为小于0的值时，按值为0处理，设置为大于360的值时，按值为360处理。<br/>当start、end、rotation的数据类型为string，合法的取值为纯数字或纯数字后带"deg"(度)、"rad"(弧度)、"grad"(梯度)、"turn"(圈)单位，例如："90"、 "90deg"、"1.57rad"。 | 81 82## sweepGradient<sup>18+</sup> 83 84sweepGradient(options: Optional\<SweepGradientOptions>) 85 86角度渐变。与[sweepGradient](#sweepgradient)相比，options参数新增了对undefined类型的支持。 87 88**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 98| options | Optional\<[SweepGradientOptions](#sweepgradientoptions18对象说明)> | 是 | 角度渐变。<br/>当options的值为undefined时，恢复为无角度渐变的效果。 | 99 100## SweepGradientOptions<sup>18+</sup>对象说明 101 102角度渐变参数。 103 104**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108| 名称 | 类型 | 必填 | 说明 | 109| ------------------------------------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 110| center | [[Length](./ts-types.md#length), Length] | 是 | 为角度渐变的中心点，即相对于当前组件左上角的坐标。 | 111| start | number \| string | 否 | 角度渐变的起点。 默认值：0。 | 112| end | number \| string | 否 | 角度渐变的终点。 默认值：0。 | 113| rotation | number \| string | 否 | 角度渐变的旋转角度。默认值：0。 | 114| [colors](#radialgradientoptions18对象说明) | Array<[[ResourceColor](ts-types.md#resourcecolor), number] | 是 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。 | 115| repeating | boolean | 否 | 为渐变的颜色重复着色。默认值：false。 | 116 117## radialGradient 118 119radialGradient(value: { center: [Length, Length]; radius: number | string; colors: Array\<[ResourceColor, number]>; repeating?: boolean }) 120 121径向渐变。 122 123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 124 125**系统能力：** SystemCapability.ArkUI.ArkUI.Full 126 127**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 128 129**参数：** 130 131 132| 参数名 | 类型 | 必填 | 说明 | 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/>} | 是 | 径向渐变。<br/>- center：径向渐变的中心点，即相对于当前组件左上角的坐标。<br/>- radius：径向渐变的半径。<br/> 取值范围：[0,+∞)<br>**说明：** <br/>设置为小于的0值时，按值为0处理。<br/>- [colors](#radialgradientoptions18对象说明): 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。<br/>- repeating: 为渐变的颜色重复着色。<br/> 默认值：false | 135 136## radialGradient<sup>18+</sup> 137 138radialGradient(options: Optional\<RadialGradientOptions>) 139 140径向渐变。与[radialGradient](#radialgradient)相比，options参数新增了对undefined类型的支持。 141 142**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 145 146**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 147 148**参数：** 149 150 151| 参数名 | 类型 | 必填 | 说明 | 152| -------------- | -------------------------------------------- | ----------------------------------- | ----------------------------------- | 153| options | Optional\<[RadialGradientOptions](#radialgradientoptions18对象说明)> | 是 | 径向渐变。<br/>当options的值为undefined时，恢复为无径向渐变的效果。 | 154## RadialGradientOptions<sup>18+</sup>对象说明 155 156径向渐变参数。 157 158**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 159 160**系统能力：** SystemCapability.ArkUI.ArkUI.Full 161 162| 名称 | 类型 | 必填 | 说明 | 163| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------ | 164| center | [[Length](./ts-types.md#length), Length] | 是 | 径向渐变的中心点，即相对于当前组件左上角的坐标。 | 165| radius | [Length](./ts-types.md#length) | 是 | 径向渐变的半径。<br/>取值范围：[0,+∞) | 166| colors | Array<[[ResourceColor](ts-types.md#resourcecolor), number]> | 是 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。 | 167| repeating | boolean | 否 | 为渐变的颜色重复着色。默认值：false。 | 168 169> **说明：** 170> 171> colors参数的约束： 172> 173> [ResourceColor](ts-types.md#resourcecolor)表示填充的颜色，number表示指定颜色所处的位置，取值范围为[0,1.0]，0表示需要设置渐变色的容器的开始处，1.0表示容器的结尾处。想要实现多个颜色渐变效果时，多个数组中number参数建议递增设置，如后一个数组number参数比前一个数组number小的话，按照等于前一个数组number的值处理。 174 175 176## 示例 177 178### 示例1（颜色从右向左线性渐变） 179 180该示例通过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, // 渐变方向 203 repeating: true, // 渐变颜色是否重复 204 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果 205 }) 206 } 207 .width('100%') 208 .padding({ top: 5 }) 209 } 210} 211``` 212 213 214 215### 示例2（颜色按旋转角度渐变） 216 217该示例通过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, // 旋转角度 245 repeating: true, // 渐变颜色是否重复 246 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果 247 }) 248 } 249 .width('100%') 250 .padding({ top: 5 }) 251 } 252} 253``` 254 255 256 257### 示例3（颜色按径向渐变） 258 259该示例通过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]] // 数组末尾元素占比小于1时满足重复着色效果 286 }) 287 } 288 .width('100%') 289 .padding({ top: 5 }) 290 } 291} 292``` 293 294 295
