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?:&nbsp;number&nbsp;\|&nbsp;string,<br/>direction?:&nbsp;[GradientDirection](ts-appendix-enums.md#gradientdirection),<br/>colors:&nbsp;Array&lt;[[ResourceColor](ts-types.md#resourcecolor),&nbsp;number]&gt;,<br/>repeating?:&nbsp;boolean<br/>} | 是   | 线性渐变。<br/>- angle:&nbsp;线性渐变的起始角度。0点方向顺时针旋转为正向角度。<br/>  默认值：180<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- direction:&nbsp;线性渐变的方向，设置angle后不生效。<br/>  默认值：GradientDirection.Bottom <br/>- colors:&nbsp;指定某百分比位置处的渐变色颜色,设置非法颜色直接跳过。<br/>- repeating:&nbsp;为渐变的颜色重复着色。 <br/>  默认值：false |
30
31## sweepGradient
32
33sweepGradient(value: {center: [Length, Length]; start?: number | string; end?: number | string; rotation?: number | string; colors: Array\<[ResourceColor, number]>; repeating?: boolean;})
34
35角度渐变。
36
37**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
38
39**系统能力：** SystemCapability.ArkUI.ArkUI.Full
40
41**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
42
43**参数：**
44
45| 参数名 | 类型                                                         | 必填 | 说明                                                         |
46| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
47| value  | {<br/>center:&nbsp;[[Length](./ts-types.md#length), Length],<br/>start?:&nbsp;number&nbsp;\|&nbsp;string,<br/>end?:&nbsp;number&nbsp;\|&nbsp;string,<br/>rotation?:&nbsp;number&nbsp;\|&nbsp;string,<br/>colors:&nbsp;Array&lt;[[ResourceColor](ts-types.md#resourcecolor),&nbsp;number]&gt;,<br/>repeating?:&nbsp;boolean<br/>} | 是   | 角度渐变，仅绘制0-360度范围内的角度，超出时不绘制渐变色，只绘制纯色。<br/>- center：为角度渐变的中心点，即相对于当前组件左上角的坐标。<br/>- start：角度渐变的起点。<br/>&nbsp;默认值：0<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- end：角度渐变的终点。<br/>&nbsp;默认值：0<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- rotation:&nbsp;角度渐变的旋转角度。<br/>&nbsp;默认值：0<br/>角度为字符串时仅支持类型deg，grad，rad，trun。<br/>- colors:&nbsp;指定某百分比位置处的渐变色颜色，设置非法颜色直接跳过。<br/>- repeating:&nbsp;为渐变的颜色重复着色。<br/>  默认值：false<br/>**说明：** <br/>设置为小于0的值时，按值为0处理，设置为大于360的值时，按值为360处理。<br/>当start、end、rotation的数据类型为string，合法的取值为纯数字或纯数字后带"deg"(度)、"rad"(弧度)、"grad"(梯度)、"turn"(圈)单位，例如："90"、 "90deg"、"1.57rad"。 |
48
49## radialGradient
50
51radialGradient(value: { center: [Length, Length]; radius: number | string; colors: Array\<[ResourceColor, number]>; repeating?: boolean })
52
53径向渐变。
54
55**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
56
57**系统能力：** SystemCapability.ArkUI.ArkUI.Full
58
59**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
60
61**参数：**
62
63
64| 参数名     | 类型                                         | 必填                             | 说明                               |
65| -------------- | -------------------------------------------- | ----------------------------------- | ----------------------------------- |
66| value | {<br/>center:&nbsp;[[Length](./ts-types.md#length), Length],<br/> radius:&nbsp;number \| string,<br/>colors:&nbsp;Array&lt;[[ResourceColor](ts-types.md#resourcecolor),&nbsp;number]&gt;,<br/>repeating?:&nbsp;boolean<br/>} | 是 | 径向渐变。<br/>- center：径向渐变的中心点，即相对于当前组件左上角的坐标。<br/>- radius：径向渐变的半径。<br/>&nbsp;取值范围：[0,+∞)<br>**说明：** <br/>设置为小于的0值时，按值为0处理。<br/>- colors:&nbsp;指定某百分比位置处的渐变色颜色，设置非法颜色直接跳过。<br/>- repeating:&nbsp;为渐变的颜色重复着色。<br/>  默认值：false |
67
68>  **说明：**
69>
70>  colors参数的约束：
71>
72>  [ResourceColor](ts-types.md#resourcecolor)表示填充的颜色，number表示指定颜色所处的位置，取值范围为[0,1.0]，0表示需要设置渐变色的容器的开始处，1.0表示容器的结尾处。想要实现多个颜色渐变效果时，多个数组中number参数建议递增设置，如后一个数组number参数比前一个数组number小的话，按照等于前一个数组number的值处理。
73
74
75## 示例
76
77### 示例1（颜色从右向左线性渐变）
78
79该示例通过linearGradient来实现组件颜色线性渐变。
80
81```ts
82// xxx.ets
83@Entry
84@Component
85struct ColorGradientExample {
86  build() {
87    Column({ space: 5 }) {
88      Text('linearGradient').fontSize(12).width('90%').fontColor(0xCCCCCC)
89      Row()
90        .width('90%')
91        .height(50)
92        .linearGradient({
93          angle: 90,
94          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]]
95        })
96      Text('linearGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC)
97      Row()
98        .width('90%')
99        .height(50)
100        .linearGradient({
101          direction: GradientDirection.Left, // 渐变方向
102          repeating: true, // 渐变颜色是否重复
103          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果
104        })
105    }
106    .width('100%')
107    .padding({ top: 5 })
108  }
109}
110```
111
112![zh-cn_image_0000001219864149](figures/gradientColor1.png)
113
114### 示例2（颜色按旋转角度渐变）
115
116该示例通过sweepGradient来实现组件颜色旋转角度渐变。
117
118```ts
119@Entry
120@Component
121struct ColorGradientExample {
122  build() {
123    Column({ space: 5 }) {
124      Text('sweepGradient').fontSize(12).width('90%').fontColor(0xCCCCCC)
125      Row()
126        .width(100)
127        .height(100)
128        .sweepGradient({
129          center: [50, 50],
130          start: 0,
131          end: 359,
132          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]]
133        })
134
135      Text('sweepGradient Reapeat').fontSize(12).width('90%').fontColor(0xCCCCCC)
136      Row()
137        .width(100)
138        .height(100)
139        .sweepGradient({
140          center: [50, 50],
141          start: 0,
142          end: 359,
143          rotation: 45, // 旋转角度
144          repeating: true, // 渐变颜色是否重复
145          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果
146        })
147    }
148    .width('100%')
149    .padding({ top: 5 })
150  }
151}
152```
153
154![zh-cn_image_0000001219864149](figures/gradientColor2.png)
155
156### 示例3（颜色按径向渐变）
157
158该示例通过radialGradient来实现组件颜色径向渐变。
159
160```ts
161// xxx.ets
162@Entry
163@Component
164struct ColorGradientExample {
165  build() {
166    Column({ space: 5 }) {
167      Text('radialGradient').fontSize(12).width('90%').fontColor(0xCCCCCC)
168      Row()
169        .width(100)
170        .height(100)
171        .radialGradient({
172          center: [50, 50],
173          radius: 60,
174          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]]
175        })
176      Text('radialGradient Repeat').fontSize(12).width('90%').fontColor(0xCCCCCC)
177      Row()
178        .width(100)
179        .height(100)
180        .radialGradient({
181          center: [50, 50],
182          radius: 60,
183          repeating: true,
184          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 0.5]] // 数组末尾元素占比小于1时满足重复着色效果
185        })
186    }
187    .width('100%')
188    .padding({ top: 5 })
189  }
190}
191```
192
193![zh-cn_image_0000001219864149](figures/gradientColor3.png)
194