渐变对象,可通过addColorStop方法设置多个颜色断点,实现平滑的颜色过渡,适用于Canvas填充和描边等场景。
本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
addColorStop(offset: number, color: string): void
设置渐变断点值,包括偏移和颜色。调用多次addColorStop可设置多个断点,断点按offset值从小到大排序,渲染时在相邻断点间进行颜色插值。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| offset | number | 是 | 设置渐变断点距离起点的位置占总体长度的比例,范围为[0, 1]。 设置offset<0或offset>1无渐变效果。 异常值undefined和null按无效值处理,不添加该断点。NaN会导致CanvasGradient对象异常,无法正常生成渐变效果;Infinity会导致整个CanvasGradient不生效。 |
| color | string | 是 | 设置渐变的颜色。string类型支持'rgb(255, 255, 255)'、'rgba(255, 255, 255, 1.0)'、'#RGB'、'#ARGB'、'#RRGGBB'、'#AARRGGBB'格式,参考ResourceColor中string类型说明。 未按格式设置颜色无渐变效果。设置null和undefined时按无效值处理,不添加该断点。 |
示例:
通过addColorStop设置渐变断点值,包括偏移和颜色。
// xxx.ets
@Entry
@Component
struct AddColorStop {
private settings: RenderingContextSettings = new RenderingContextSettings(true);
private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Canvas(this.context)
.width('100%')
.height('100%')
.backgroundColor('rgb(213,213,213)')
.onReady(() => {
let grad = this.context.createLinearGradient(50, 0, 300, 100)
grad.addColorStop(0.0, 'rgb(39,135,217)')
grad.addColorStop(0.5, 'rgb(255,238,240)')
grad.addColorStop(1.0, 'rgb(23,169,141)')
this.context.fillStyle = grad
this.context.fillRect(0, 0, 400, 400)
})
}
.width('100%')
.height('100%')
}
} 
addColorStop(offset: number, color: string | ColorMetrics): void
设置渐变断点值,包括偏移和颜色。支持设置rgb或argb格式颜色。支持通过传入ColorMetrics类型设置P3广色域颜色值。
卡片能力: 从API version 20开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 20开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| offset | number | 是 | 设置渐变断点距离起点的位置占总体长度的比例,范围为[0, 1]。 设置offset<0或offset>1无渐变效果。 异常值undefined和null按无效值处理,不添加该断点。NaN会导致CanvasGradient对象异常,无法正常生成渐变效果;Infinity会导致整个CanvasGradient不生效。 |
| color | string | ColorMetrics | 是 | 设置渐变的颜色。string类型支持'rgb(255, 255, 255)'、'rgba(255, 255, 255, 1.0)'、'#RGB'、'#ARGB'、'#RRGGBB'、'#AARRGGBB'格式。 可以使用colorWithSpace方法构造指定色域属性的颜色。ColorMetrics类型可以构造指定色域属性ColorSpace为sRGB或DISPLAY_P3的颜色。从API版本26.0.0开始,新增支持构造BT2020色域的颜色,并支持HDR提亮。同一CanvasGradient对象中的所有渐变断点必须使用相同的色域属性,设置不同色域时将抛出异常,错误码:103701,此时不会添加该断点,CanvasGradient对象保持之前的状态。 未按格式设置颜色无渐变效果。设置null和undefined时按无效值处理,不添加该断点。 |
错误码:
以下错误码的详细介绍请参见Canvas组件错误码。
| 错误码ID | 错误信息 |
|---|---|
| 103701 | The color's ColorSpace is not the same as the last color's. |
仅CanvasRenderingContext2D对象的fillStyle和strokeStyle属性支持设置广色域的CanvasGradient对象。使用HDR颜色时,需将Canvas组件所在窗口的色域模式通过setWindowColorSpace方法设置为广色域模式WIDE_GAMUT。不满足上述条件时,广色域颜色设置将无法正常生效。
示例:
通过addColorStop设置指定色域的渐变断点值,包括偏移和颜色。设置窗口色域模式为广色域参照方法setWindowColorSpace。
// xxx.ets
import { BusinessError } from '@kit.BasicServicesKit';
import { ColorMetrics } from '@kit.ArkUI'
@Entry
@Component
struct AddColorStop {
private settings: RenderingContextSettings = new RenderingContextSettings(true);
private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Canvas(this.context)
.width('100%')
.height('100%')
.onReady(() => {
// 设置fillStyle为sRGB色域效果的gradient
let gradSRGB = this.context.createLinearGradient(85, 10, 160, 110)
// 使用try catch对可能出现的异常进行捕获
try {
gradSRGB.addColorStop(0.0, ColorMetrics.colorWithSpace(ColorSpace.SRGB, 1.0, 0.0, 0.0, 1.0))
gradSRGB.addColorStop(0.5, ColorMetrics.colorWithSpace(ColorSpace.SRGB, 1.0, 1.0, 1.0, 1.0))
gradSRGB.addColorStop(1.0, ColorMetrics.colorWithSpace(ColorSpace.SRGB, 0.0, 1.0, 0.0, 1.0))
} catch (error) {
let e: BusinessError = error as BusinessError;
console.error(`Failed to addColorStop. Code: ${e.code}, message: ${e.message}`);
}
this.context.fillStyle = gradSRGB
this.context.fillRect(10, 10, 150, 150)
// 设置fillStyle为DISPLAY_P3色域效果的gradient
let gradP3 = this.context.createLinearGradient(245, 10, 320, 110)
// 使用try catch对可能出现的异常进行捕获
try {
gradP3.addColorStop(0.0, ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 1.0, 0.0, 0.0, 1.0))
gradP3.addColorStop(0.5, ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 1.0, 1.0, 1.0, 1.0))
gradP3.addColorStop(1.0, ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0.0, 1.0, 0.0, 1.0))
} catch (error) {
let e: BusinessError = error as BusinessError;
console.error(`Failed to addColorStop. Code: ${e.code}, message: ${e.message}`);
}
this.context.fillStyle = gradP3
this.context.fillRect(170, 10, 150, 150)
})
}
.width('100%')
.height('100%')
}
} 