1# 颜色渐变 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9设置组件的颜色渐变效果。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 颜色渐变属于组件内容，绘制在背景上方。 16> 17> 颜色渐变不支持宽高显式动画，执行宽高动画时颜色渐变会直接过渡到终点。 18 19## linearGradient 20 21linearGradient(value: LinearGradientOptions): T 22 23线性渐变。 24 25**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 35| value | [LinearGradientOptions](#lineargradientoptions18对象说明) | 是 | 线性渐变。 | 36 37**返回值：** 38 39| 类型 | 说明 | 40| ------ | ------------------------ | 41| T | 返回当前组件。 | 42 43## linearGradient<sup>18+</sup> 44 45linearGradient(options: Optional\<LinearGradientOptions>): T 46 47线性渐变。与[linearGradient](#lineargradient)相比，options参数新增了对undefined类型的支持。 48 49**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 50 51**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55**参数：** 56 57| 参数名 | 类型 | 必填 | 说明 | 58| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 59| options | Optional\<[LinearGradientOptions](#lineargradientoptions18对象说明)> | 是 | 线性渐变。<br/>当options的值为undefined时，恢复为无线性渐变的效果。 | 60 61**返回值：** 62 63| 类型 | 说明 | 64| ------ | ------------------------ | 65| T | 返回当前组件。 | 66 67## LinearGradientOptions<sup>18+</sup>对象说明 68 69线性渐变的参数。 70 71> **说明：** 72> 73> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 74 75**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 80 81| 名称 | 类型 | 只读 | 可选 | 说明 | 82| ------------------------------------------ | ------------------------------------------------------------ | ---- | ---- |------------------------------------------------------------ | 83| angle<sup>7+</sup> | number \| string | 否 | 是 | 线性渐变的起始角度。角度为0度时渐变方向为从下往上（即0点方向）。0点方向顺时针旋转为正向角度。<br/> 取值范围：(-∞,+∞)，设置的值大于0时，按顺时针方向，小于0时，按逆时针方向。 </br>默认值：180 </br>角度为字符串时，合法的取值为纯数字或纯数字后带"deg"（度）、"rad"（弧度）、"grad"（梯度）、"turn"（圈）单位，例如："90"、 "90deg"、"1.57rad"。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。| 84| direction<sup>7+</sup> | [GradientDirection](ts-appendix-enums.md#gradientdirection) | 否 | 是 | 线性渐变的方向，设置angle为非undefined后不生效。设置为GradientDirection.None时，按默认方向渐变。默认值：GradientDirection.Bottom。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。| 85| [colors](#radialgradientoptions18对象说明)<sup>7+</sup> | Array<[[ResourceColor](ts-types.md#resourcecolor), number]> | 否 | 否 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。ResourceColor表示颜色，number表示该颜色所处的位置，取值范围为[0, 1.0]，设置的值小于0时，按0处理，设置的值大于1.0时，按1.0处理。0表示需要设置渐变色的开始处，1.0表示渐变色的结束处。为了实现多个颜色渐变效果，多个数组中的number类型参数应递增设置。如果后一个数组中的number类型参数小于前一个数组的number类型参数，将按照等于前一个数组number值处理。<br> 默认值：[]，无渐变效果。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。| 86| repeating<sup>7+</sup> | boolean | 否 | 是 | 为渐变的颜色重复着色。<br>默认值：false。<br>true：允许为渐变的颜色重复着色。<br>false：不允许为渐变的颜色重复着色。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。| 87 88## sweepGradient 89 90sweepGradient(value: SweepGradientOptions): T 91 92角度渐变。 93 94**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 104| value | [SweepGradientOptions](#sweepgradientoptions18对象说明) | 是 | 角度渐变，仅绘制0-360度范围内的角度，超出时不绘制渐变色，只绘制纯色。 | 105 106**返回值：** 107 108| 类型 | 说明 | 109| ------ | ------------------------ | 110| T | 返回当前组件。 | 111 112## sweepGradient<sup>18+</sup> 113 114sweepGradient(options: Optional\<SweepGradientOptions>): T 115 116角度渐变。与[sweepGradient](#sweepgradient)相比，options参数新增了对undefined类型的支持。 117 118**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 119 120**系统能力：** SystemCapability.ArkUI.ArkUI.Full 121 122**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 128| options | Optional\<[SweepGradientOptions](#sweepgradientoptions18对象说明)> | 是 | 角度渐变。<br/>当options的值为undefined时，恢复为无角度渐变的效果。 | 129 130**返回值：** 131 132| 类型 | 说明 | 133| ------ | ------------------------ | 134| T | 返回当前组件。 | 135 136## SweepGradientOptions<sup>18+</sup>对象说明 137 138角度渐变参数。 139 140> **说明：** 141> 142> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 143 144**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 145 146**系统能力：** SystemCapability.ArkUI.ArkUI.Full 147 148**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 149 150| 名称 | 类型 | 只读 | 可选 | 说明 | 151| ------------------------------------------ | ------------------------------------------------------------ | ---- | ---- |------------------------------------------------------------- | 152| center<sup>7+</sup> | [[Length](./ts-types.md#length), Length] | 否 | 否 | 为角度渐变的中心点，即相对于当前组件左上角的坐标。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 153| start<sup>7+</sup> | number \| string | 否 | 是 | 角度渐变的起点。 默认值：0。<br/>角度为字符串时，合法的取值为纯数字或纯数字后带"deg"（度）、"rad"（弧度）、"grad"（梯度）、"turn"（圈）单位。例如："90"、 "90deg"、"1.57rad"。取值有0~360度的限制，转换为度的单位之后，值在0~360度之间，设置为小于0度的值时，按值为0度处理，设置为大于360度的值时，按值为360度处理。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 154| end<sup>7+</sup> | number \| string | 否 | 是 | 角度渐变的终点。 默认值：0。<br/>角度为字符串时，合法的取值为纯数字或纯数字后带"deg"（度）、"rad"（弧度）、"grad"（梯度）、"turn"（圈）单位。例如："90"、 "90deg"、"1.57rad"。取值有0~360度的限制，转换为度的单位之后，值在0~360度之间，设置为小于0度的值时，按值为0度处理，设置为大于360度的值时，按值为360度处理。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 155| rotation<sup>7+</sup> | number \| string | 否 | 是 | 角度渐变的旋转角度。默认值：0。<br/>角度为字符串时，合法的取值为纯数字或纯数字后带"deg"（度）、"rad"（弧度）、"grad"（梯度）、"turn"（圈）单位。例如："90"、 "90deg"、"1.57rad"。取值有0~360度的限制，转换为度的单位之后，值在0~360度之间，设置为小于0度的值时，按值为0度处理，设置为大于360度的值时，按值为360度处理。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 156| colors<sup>7+</sup> | Array<[[ResourceColor](ts-types.md#resourcecolor), number]> | 否 | 是 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。| 157| metricsColors<sup>20+</sup> | Array<[[ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12), number]> | 否 | 是 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。设置metricsColors时colors失效。每个渐变ColorMetrics的色域属性应当统一，设置不同色域属性则认为非法。默认值为透明色。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 158| repeating<sup>7+</sup> | boolean | 否 | 是 | 为渐变的颜色重复着色。<br>默认值：false <br>true：允许为渐变的颜色重复着色。<br>false：不允许为渐变的颜色重复着色。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 159 160> **说明：** 161> 162> metricsColors参数的约束： 163> 164> [ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12)表示填充的颜色，可以使用[colorWithSpace](../js-apis-arkui-graphics.md#colorwithspace20)方法构造指定色域属性的颜色。number表示指定颜色所处的位置，取值范围为[0, 1.0]，0表示需要设置渐变色的容器开始处，1.0表示容器的结束处。为了实现多个颜色渐变效果，多个数组中的number类型参数应递增设置。如果后一个数组中的number类型参数小于前一个数组的number类型参数，将按照等于前一个数组number值处理。 165 166## radialGradient 167 168radialGradient(value: RadialGradientOptions): T 169 170径向渐变。 171 172**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 182| value | [RadialGradientOptions](#radialgradientoptions18对象说明) | 是 | 径向渐变。 | 183 184**返回值：** 185 186| 类型 | 说明 | 187| ------ | ------------------------ | 188| T | 返回当前组件。 | 189 190## radialGradient<sup>18+</sup> 191 192radialGradient(options: Optional\<RadialGradientOptions>): T 193 194径向渐变。与[radialGradient](#radialgradient)相比，options参数新增了对undefined类型的支持。 195 196**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 197 198**系统能力：** SystemCapability.ArkUI.ArkUI.Full 199 200**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 201 202**参数：** 203 204 205| 参数名 | 类型 | 必填 | 说明 | 206| -------------- | -------------------------------------------- | ----------------------------------- | ----------------------------------- | 207| options | Optional\<[RadialGradientOptions](#radialgradientoptions18对象说明)> | 是 | 径向渐变。<br/>当options的值为undefined时，恢复为无径向渐变的效果。 | 208 209**返回值：** 210 211| 类型 | 说明 | 212| ------ | ------------------------ | 213| T | 返回当前组件。 | 214 215## RadialGradientOptions<sup>18+</sup>对象说明 216 217径向渐变参数。 218 219> **说明：** 220> 221> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 222 223**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 224 225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 226 227**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 228 229| 名称 | 类型 | 只读 | 可选 | 说明 | 230| --------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------ | 231| center<sup>7+</sup> | [[Length](./ts-types.md#length), Length] | 否| 否 | 径向渐变的中心点，即相对于当前组件左上角的坐标。 <br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 232| radius<sup>7+</sup> | [Length](./ts-types.md#length) | 否 | 否 | 径向渐变的半径。<br/>取值范围：[0,+∞)。设置的值小于0时，按值为0处理。设置的值为undefined时，系统会自适应渐变半径。 <br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 233| colors<sup>7+</sup> | Array<[[ResourceColor](ts-types.md#resourcecolor), number]> | 否 | 否 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。<br> 默认值：[]，无渐变效果。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 234| repeating<sup>7+</sup> | boolean | 否 | 是 | 为渐变的颜色重复着色。默认值：false。 <br>true：允许为渐变的颜色重复着色。<br>false：不允许为渐变的颜色重复着色。 <br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 235 236> **说明：** 237> 238> colors参数的约束： 239> 240> [ResourceColor](ts-types.md#resourcecolor)表示填充的颜色，number表示指定颜色所处的位置，取值范围为[0,1.0]，0表示需要设置渐变色的容器的开始处，1.0表示容器的结尾处。想要实现多个颜色渐变效果时，多个数组中number参数建议递增设置，如后一个数组number参数比前一个数组number小的话，按照等于前一个数组number的值处理。 241 242 243## 示例 244 245### 示例1（颜色从右向左线性渐变） 246 247该示例通过linearGradient来实现组件的颜色线性渐变。 248 249```ts 250// xxx.ets 251@Entry 252@Component 253struct ColorGradientExample { 254 build() { 255 Column({ space: 5 }) { 256 Text('linearGradient').fontSize(12).width('90%').fontColor(0xCCCCCC) 257 Row() 258 .width('90%') 259 .height(50) 260 .linearGradient({ 261 angle: 90, 262 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 263 }) 264 Text('linearGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC) 265 Row() 266 .width('90%') 267 .height(50) 268 .linearGradient({ 269 direction: GradientDirection.Left, // 渐变方向 270 repeating: true, // 渐变颜色是否重复 271 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果 272 }) 273 } 274 .width('100%') 275 .padding({ top: 5 }) 276 } 277} 278``` 279 280 281 282### 示例2（颜色按旋转角度渐变） 283 284该示例通过sweepGradient来实现组件颜色旋转角度渐变。 285 286```ts 287// 设置P3色域时需要在ets/entryability/EntryAbility.ets中，通过setColorSpace接口将当前窗口设置为广色域。 288import { ColorMetrics } from '@kit.ArkUI'; 289 290@Entry 291@Component 292struct ColorGradientExample { 293 @State p3Red: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 1, 0, 0, 1); 294 @State p3Green: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0, 1, 0, 1); 295 @State p3Blue: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0, 0, 1, 1); 296 297 build() { 298 Column({ space: 5 }) { 299 Text('sweepGradient').fontSize(12).width('90%').fontColor(0xCCCCCC) 300 Row() 301 .width(100) 302 .height(100) 303 .sweepGradient({ 304 center: [50, 50], 305 start: 0, 306 end: 359, 307 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 308 }) 309 310 Text('sweepGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC) 311 Row() 312 .width(100) 313 .height(100) 314 .sweepGradient({ 315 center: [50, 50], 316 start: 0, 317 end: 359, 318 rotation: 45, // 旋转角度 319 repeating: true, // 渐变颜色是否重复 320 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果 321 }) 322 323 Text('sweepGradient with metricsColors').fontSize(12).width('90%').fontColor(0xCCCCCC) 324 Row() 325 .width(100) 326 .height(100) 327 .sweepGradient({ 328 center: [50, 50], 329 start: 0, 330 end: 359, 331 rotation: 45, 332 repeating: true, 333 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]], // 数组末尾元素占比小于1时满足重复着色效果 334 metricsColors: [[this.p3Red, 0.0], [this.p3Green, 0.5], [this.p3Blue, 1.0]] // 设置metricsColors时colors设置的颜色失效，metricsColors的颜色生效 335 }) 336 } 337 .width('100%') 338 .padding({ top: 5 }) 339 } 340} 341``` 342 343 344 345### 示例3（颜色按径向渐变） 346 347该示例通过radialGradient来实现组件颜色径向渐变。 348 349```ts 350// xxx.ets 351@Entry 352@Component 353struct ColorGradientExample { 354 build() { 355 Column({ space: 5 }) { 356 Text('radialGradient').fontSize(12).width('90%').fontColor(0xCCCCCC) 357 Row() 358 .width(100) 359 .height(100) 360 .radialGradient({ 361 center: [50, 50], 362 radius: 60, 363 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 364 }) 365 Text('radialGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC) 366 Row() 367 .width(100) 368 .height(100) 369 .radialGradient({ 370 center: [50, 50], 371 radius: 60, 372 repeating: true, 373 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果 374 }) 375 } 376 .width('100%') 377 .padding({ top: 5 }) 378 } 379} 380``` 381 382 383
