1# CanvasGradient 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @sd-wu--> 5<!--Designer: @sunbees--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9渐变对象。 10 11> **说明：** 12> 13> 从 API version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15 16 17## addColorStop 18 19addColorStop(offset: number, color: string): void 20 21设置渐变断点值，包括偏移和颜色。 22 23**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------ | ------ | ---- | ---------------------------------------- | 33| offset | number | 是 | 设置渐变点距离起点的位置占总体长度的比例，范围为[0, 1]。</br>设置offset<0或offset>1无渐变效果。 | 34| color | string | 是 | 设置渐变的颜色。颜色格式参考[ResourceColor](ts-types.md#resourcecolor)中string类型说明。</br>未按格式设置颜色无渐变效果。 | 35 36 37**示例：** 38 39通过addColorStop设置渐变断点值，包括偏移和颜色。支持设置rgb或者argb格式颜色。 40 41 ```ts 42 // xxx.ets 43 @Entry 44 @Component 45 struct AddColorStop { 46 private settings: RenderingContextSettings = new RenderingContextSettings(true); 47 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); 48 49 build() { 50 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 51 Canvas(this.context) 52 .width('100%') 53 .height('100%') 54 .backgroundColor('#ffff00') 55 .onReady(() => { 56 let grad = this.context.createLinearGradient(50, 0, 300, 100) 57 grad.addColorStop(0.0, '#ff0000') 58 grad.addColorStop(0.5, '#ffffff') 59 grad.addColorStop(1.0, '#00ff00') 60 this.context.fillStyle = grad 61 this.context.fillRect(0, 0, 400, 400) 62 }) 63 } 64 .width('100%') 65 .height('100%') 66 } 67 } 68 ``` 69  70 71 72 ## addColorStop<sup>20+</sup> 73 74addColorStop(offset: number, color: string | ColorMetrics): void 75 76设置渐变断点值，包括偏移和颜色。支持设置rgb或者argb格式颜色。支持通过传入[ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12)类型设置P3色域颜色值，可在支持高色域的设备上获得更丰富的色彩表现。 77 78**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。 79 80**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 81 82**系统能力：** SystemCapability.ArkUI.ArkUI.Full 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| ------ | ------ | ---- | ---------------------------------------- | 88| offset | number | 是 | 设置渐变点距离起点的位置占总体长度的比例，范围为[0, 1]。</br>设置offset<0或offset>1无渐变效果。 | 89| color | string \| [ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12) | 是 | 设置渐变填充的颜色。</br>可以使用[colorWithSpace](../js-apis-arkui-graphics.md#colorwithspace20)方法构造指定色域属性[ColorSpace](ts-appendix-enums.md#colorspace20)为SRGB或DISPLAY_P3的颜色。每个渐变ColorMetrics的色域属性应当统一，设置不同色域的属性时将抛出异常，错误码：103701。</br>设置null和undefined无效。 | 90 91**错误码：** 92 93以下错误码的详细介绍请参见[Canvas组件错误码](../errorcode-canvas.md)。 94 95| 错误码ID | 错误信息 | 96| -------- | -------- | 97| 103701 | The color's ColorSpace is not the same as the last color's. | 98 99> **说明：** 100> 101> 仅[CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md)对象的[fillStyle](ts-canvasrenderingcontext2d.md#fillstyle)和[strokeStyle](ts-canvasrenderingcontext2d.md#strokestyle)属性支持设置P3广色域的CanvasGradient对象，且需要将Canvas组件所在窗口的色域模式通过[setWindowColorSpace](../arkts-apis-window-Window.md#setwindowcolorspace9)方法设置为广色域模式WIDE_GAMUT。</br> 102 103 104**示例：** 105 106通过addColorStop设置指定色域的渐变断点值，包括偏移和颜色。设置窗口色域模式为广色域参照方法[setWindowColorSpace](../arkts-apis-window-Window.md#setwindowcolorspace9)。 107 ```ts 108// xxx.ets 109import { BusinessError } from '@kit.BasicServicesKit'; 110import { ColorMetrics } from '@kit.ArkUI' 111 112@Entry 113@Component 114struct AddColorStop { 115 private settings: RenderingContextSettings = new RenderingContextSettings(true); 116 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); 117 118 build() { 119 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 120 Canvas(this.context) 121 .width('100%') 122 .height('100%') 123 .onReady(() => { 124 // 设置fillStyle为SRGB色域效果的gradient 125 let gradSRGB = this.context.createLinearGradient(85, 10, 160, 110) 126 // 使用try catch对可能出现的异常进行捕获 127 try { 128 gradSRGB.addColorStop(0.0, ColorMetrics.colorWithSpace(ColorSpace.SRGB, 1.0, 0.0, 0.0, 1.0)) 129 gradSRGB.addColorStop(0.5, ColorMetrics.colorWithSpace(ColorSpace.SRGB, 1.0, 1.0, 1.0, 1.0)) 130 gradSRGB.addColorStop(1.0, ColorMetrics.colorWithSpace(ColorSpace.SRGB, 0.0, 1.0, 0.0, 1.0)) 131 } catch (error) { 132 let e: BusinessError = error as BusinessError; 133 console.error(`Failed to addColorStop. Code: ${e.code}, message: ${e.message}`); 134 } 135 this.context.fillStyle = gradSRGB 136 this.context.fillRect(10, 10, 150, 150) 137 138 // 设置fillStyle为DISPLAY_P3色域效果的gradient 139 let gradP3 = this.context.createLinearGradient(245, 10, 320, 110) 140 // 使用try catch对可能出现的异常进行捕获 141 try { 142 gradP3.addColorStop(0.0, ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 1.0, 0.0, 0.0, 1.0)) 143 gradP3.addColorStop(0.5, ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 1.0, 1.0, 1.0, 1.0)) 144 gradP3.addColorStop(1.0, ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0.0, 1.0, 0.0, 1.0)) 145 } catch (error) { 146 let e: BusinessError = error as BusinessError; 147 console.error(`Failed to addColorStop. Code: ${e.code}, message: ${e.message}`); 148 } 149 this.context.fillStyle = gradP3 150 this.context.fillRect(170, 10, 150, 150) 151 }) 152 } 153 .width('100%') 154 .height('100%') 155 } 156} 157 ``` 158  159 160
