1# 图像效果 2 3设置组件的模糊、阴影、球面效果以及设置图片的图像效果。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## blur 10 11blur(value: number, options?: BlurOptions) 12 13为组件添加内容模糊效果。 14 15**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21**参数：** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 25| value | number | 是 | 当前组件添加内容模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。 | 26| options<sup>11+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 27 28## blur<sup>18+</sup> 29 30blur(blurRadius: Optional\<number>, options?: BlurOptions, sysOptions?: [SystemAdaptiveOptions](ts-universal-attributes-background.md#systemadaptiveoptions18)) 31 32为组件添加内容模糊效果。与[blur](#blur)相比，blurRadius参数新增了对undefined类型的支持。 33 34**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 35 36**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 37 38**系统能力：** SystemCapability.ArkUI.ArkUI.Full 39 40**参数：** 41 42| 参数名 | 类型 | 必填 | 说明 | 43| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 44| blurRadius | Optional\<number> | 是 | 当前组件添加内容模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>当blurRadius的值为undefined时，维持之前取值。 | 45| options<sup>16+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 46| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](ts-universal-attributes-background.md#systemadaptiveoptions18) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 47 48## shadow 49 50shadow(value: ShadowOptions | ShadowStyle) 51 52为组件添加阴影效果。 53 54**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用，ArkTS卡片上不支持参数为 [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明)类型。 55 56**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 64| value | [ShadowOptions](#shadowoptions对象说明) \| [ShadowStyle](#shadowstyle10枚举说明)<sup>10+</sup> | 是 | 为当前组件添加阴影效果。<br/>入参类型为ShadowOptions时，可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。<br/>入参类型为ShadowStyle时，可指定不同阴影样式。 | 65 66## shadow<sup>18+</sup> 67 68shadow(options: Optional\<ShadowOptions | ShadowStyle>) 69 70为组件添加阴影效果。与[shadow](#shadow)相比，options参数新增了对undefined类型的支持。 71 72**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用，ArkTS卡片上不支持参数为 [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明)类型。 73 74**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.ArkUI.ArkUI.Full 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---- | 82| options | Optional\<[ShadowOptions](#shadowoptions对象说明) \| [ShadowStyle](#shadowstyle10枚举说明)<sup>10+</sup>> | 是 | 为当前组件添加阴影效果。<br/>入参类型为ShadowOptions时，可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。<br/>入参类型为ShadowStyle时，可指定不同阴影样式。<br/>当options的值为undefined时，恢复为无样式的阴影效果。 | 83 84## grayscale 85 86grayscale(value: number) 87 88为组件添加灰度效果。 89 90**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 91 92**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| ------ | ------ | ---- | ------------------------------------------------------------ | 100| value | number | 是 | 为当前组件添加灰度效果。值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参0.0则图像无变化，入参在0.0和1.0之间时，效果呈线性变化。（百分比)<br/>默认值：0.0<br/>取值范围：[0.0, 1.0]<br/>**说明：**<br/>设置小于0.0的值时，按值为0.0处理，设置大于1.0的值时，按值为1.0处理。 | 101 102## grayscale<sup>18+</sup> 103 104grayscale(grayscale: Optional\<number>) 105 106为组件添加灰度效果。与[grayscale](#grayscale)相比，grayscale参数新增了对undefined类型的支持。 107 108**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 109 110**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 111 112**系统能力：** SystemCapability.ArkUI.ArkUI.Full 113 114**参数：** 115 116| 参数名 | 类型 | 必填 | 说明 | 117| --------- | ----------------- | ---- | ------------------------------------------------------------ | 118| grayscale | Optional\<number> | 是 | 为当前组件添加灰度效果。值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参0.0则图像无变化，入参在0.0和1.0之间时，效果呈线性变化。（百分比)<br/>默认值：0.0<br/>取值范围：[0.0, 1.0]<br/>**说明：**<br/>设置小于0.0的值时，按值为0.0处理，设置大于1.0的值时，按值为1.0处理。<br/>当grayscale的值为undefined时，取默认值0.0。恢复为无灰度效果。 | 119 120## brightness 121 122brightness(value: number) 123 124为组件添加高光效果。 125 126**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 127 128**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 129 130**系统能力：** SystemCapability.ArkUI.ArkUI.Full 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| ------ | ------ | ---- | ------------------------------------------------------------ | 136| value | number | 是 | 为当前组件添加高光效果，入参为高光比例，值为1时没有效果，小于1时亮度变暗，0为全黑，大于1时亮度增加，数值越大亮度越大，亮度为2时会变为全白。<br/>默认值：1.0<br/>推荐取值范围：[0, 2]<br/>**说明：**<br/>设置小于0的值时，按值为0处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 137 138## brightness<sup>18+</sup> 139 140brightness(brightness: Optional\<number>) 141 142为组件添加高光效果。与[brightness](#brightness)相比，brightness参数新增了对undefined类型的支持。 143 144**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 145 146**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| ---------- | ----------------- | ---- | ------------------------------------------------------------ | 154| brightness | Optional\<number> | 是 | 为当前组件添加高光效果，入参为高光比例，值为1时没有效果，小于1时亮度变暗，0为全黑，大于1时亮度增加，数值越大亮度越大，亮度为2时会变为全白。<br/>默认值：1.0<br/>推荐取值范围：[0, 2]<br/>**说明：**<br/>设置小于0的值时，按值为0处理。<br/>当brightness的值为undefined时，恢复为亮度为1的高光效果。 | 155 156## saturate 157 158saturate(value: number) 159 160为组件添加饱和度效果。 161 162**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 163 164**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 165 166**系统能力：** SystemCapability.ArkUI.ArkUI.Full 167 168**参数：** 169 170| 参数名 | 类型 | 必填 | 说明 | 171| ------ | ------ | ---- | ------------------------------------------------------------ | 172| value | number | 是 | 为当前组件添加饱和度效果，饱和度为颜色中的含色成分和消色成分(灰)的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大，小于1时消色成分越大，饱和度越小。（百分比）<br/>默认值：1.0<br/>推荐取值范围：[0, 50)<br/>**说明：**<br/>设置小于0的值时，按值为0处理。 | 173 174## saturate<sup>18+</sup> 175 176saturate(saturate: Optional\<number>) 177 178为组件添加饱和度效果。与[saturate](#saturate)相比，saturate参数新增了对undefined类型的支持。 179 180**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 181 182**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 183 184**系统能力：** SystemCapability.ArkUI.ArkUI.Full 185 186**参数：** 187 188| 参数名 | 类型 | 必填 | 说明 | 189| -------- | ----------------- | ---- | ------------------------------------------------------------ | 190| saturate | Optional\<number> | 是 | 为当前组件添加饱和度效果，饱和度为颜色中的含色成分和消色成分(灰)的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大，小于1时消色成分越大，饱和度越小。（百分比）<br/>默认值：1.0<br/>推荐取值范围：[0, 50)<br/>**说明：**<br/>设置小于0的值时，按值为0处理。<br/>当saturate的值为undefined时。恢复为饱和度为1的效果。 | 191 192## contrast 193 194contrast(value: number) 195 196为组件添加对比度效果。 197 198**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 199 200**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 201 202**系统能力：** SystemCapability.ArkUI.ArkUI.Full 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| ------ | ------ | ---- | ------------------------------------------------------------ | 208| value | number | 是 | 为当前组件添加对比度效果，入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。（百分比）<br/>默认值：1.0<br/>推荐取值范围：[0, 10)<br/>**说明：**<br/>设置小于0的值时，按值为0处理。 | 209 210## contrast<sup>18+</sup> 211 212contrast(contrast: Optional\<number>) 213 214为组件添加对比度效果。与[contrast](#contrast)相比，contrast参数新增了对undefined类型的支持。 215 216**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 217 218**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 219 220**系统能力：** SystemCapability.ArkUI.ArkUI.Full 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| -------- | ----------------- | ---- | ------------------------------------------------------------ | 226| contrast | Optional\<number> | 是 | 为当前组件添加对比度效果，入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。（百分比）<br/>默认值：1.0<br/>推荐取值范围：[0, 10)<br/>**说明：**<br/>设置小于0的值时，按值为0处理。<br/>当contrast的值为undefined时，恢复为对比度为1的效果。 | 227 228## invert 229 230invert(value: number | InvertOptions) 231 232反转输入的图像。 233 234**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 235 236**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 237 238**系统能力：** SystemCapability.ArkUI.ArkUI.Full 239 240**参数：** 241 242| 参数名 | 类型 | 必填 | 说明 | 243| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 244| value | number \| [InvertOptions](#invertoptions11对象说明)<sup>11+</sup> | 是 | 反转输入的图像。<br/>入参对象为number时,入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。（百分比）<br/>取值范围：[0, 1]。<br/>设置小于0的值时，按值为0处理。设置大于1的值时，按值为1处理。<br/>入参对象为 InvertOptions时，对比背景颜色灰度值和阈值区间，背景颜色灰度值小于阈值区间时反色取high值，当背景颜色灰度值大于阈值区间时反色取low值，背景颜色灰度值在阈值区间内取值由high线性渐变到low。 | 245 246## invert<sup>18+</sup> 247 248invert(options: Optional\<number | InvertOptions>) 249 250反转输入的图像。与[invert](#invert)相比，options参数新增了对undefined类型的支持。 251 252**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 253 254**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 255 256**系统能力：** SystemCapability.ArkUI.ArkUI.Full 257 258**参数：** 259 260| 参数名 | 类型 | 必填 | 说明 | 261| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 262| options | Optional\<number \| [InvertOptions](#invertoptions11对象说明)<sup>11+</sup>> | 是 | 反转输入的图像。<br/>入参对象为number时,入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。（百分比）<br/>取值范围：[0, 1]。<br/>设置小于0的值时，按值为0处理。设置大于1的值时，按值为1处理。<br/>入参对象为 InvertOptions时，对比背景颜色灰度值和阈值区间，背景颜色灰度值小于阈值区间时反色取high值，当背景颜色灰度值大于阈值区间时反色取low值，背景颜色灰度值在阈值区间内取值由high线性渐变到low。<br/>当options的值为undefined时，恢复为图像无变化的效果。 | 263 264## sepia 265 266sepia(value: number) 267 268将图像转换为深褐色。 269 270**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 271 272**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 273 274**系统能力：** SystemCapability.ArkUI.ArkUI.Full 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| ------ | ------ | ---- | ------------------------------------------------------------ | 280| value | number | 是 | 将图像转换为深褐色，降低色彩度，产生温暖复古的图像风格。入参为褐色滤镜强度，值为1则完全是深褐色的，值小于等于0则图像无变化，值大于1会进一步放大色彩偏移比例，图像整体会变得更亮且色彩更加偏黄/偏红，但不属于标准sepia效果。（百分比）<br/>取值范围：[0, +∞)，推荐取值范围：(0, 1]。 | 281 282## sepia<sup>18+</sup> 283 284sepia(sepia: Optional\<number>) 285 286将图像转换为深褐色。与[sepia](#sepia)相比，sepia参数新增了对undefined类型的支持。 287 288**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 289 290**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 291 292**系统能力：** SystemCapability.ArkUI.ArkUI.Full 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| ------ | ----------------- | ---- | ------------------------------------------------------------ | 298| sepia | Optional\<number> | 是 | 将图像转换为深褐色，降低色彩度，产生温暖复古的图像风格。入参为褐色滤镜强度，值为1则完全是深褐色的，值小于等于0则图像无变化，值大于1会进一步放大色彩偏移比例，图像整体会变得更亮且色彩更加偏黄/偏红，但不属于标准sepia效果。（百分比）<br/>当sepia的值为undefined时，恢复为图像无变化的效果。<br/> 取值范围：[0, +∞)，推荐取值范围：(0, 1]。 | 299 300## hueRotate 301 302hueRotate(value: number | string) 303 304色相旋转效果。 305 306**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 307 308**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 309 310**系统能力：** SystemCapability.ArkUI.ArkUI.Full 311 312**参数：** 313 314| 参数名 | 类型 | 必填 | 说明 | 315| ------ | -------------------------- | ---- | ------------------------------------------------------------ | 316| value | number \| string | 是 | 色相旋转效果，输入参数为旋转角度。<br/>默认值：'0deg'<br/>取值范围：(-∞, +∞)<br/>**说明：**<br/>色调旋转360度会显示原始颜色。先将色调旋转180 度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和'90deg'效果一致。 | 317 318## hueRotate<sup>18+</sup> 319 320hueRotate(rotation: Optional\<number | string>) 321 322色相旋转效果。与[hueRotate](#huerotate)相比，rotation参数新增了对undefined类型的支持。 323 324**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 325 326**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 327 328**系统能力：** SystemCapability.ArkUI.ArkUI.Full 329 330**参数：** 331 332| 参数名 | 类型 | 必填 | 说明 | 333| -------- | ------------------------------------- | ------------------------------------------------------------ | ---- | 334| rotation | Optional\<number \| string> | 是 |色相旋转效果，输入参数为旋转角度。<br/>默认值：'0deg'<br/>取值范围：(-∞, +∞)<br/>string需为数值字符串类型。<br/>**说明：**<br/>色调旋转360度会显示原始颜色。先将色调旋转180 度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和'90deg'效果一致。<br/>当rotation的值为undefined时，恢复为无色相旋转的效果。 | 335 336## colorBlend<sup>7+</sup> 337 338colorBlend(value: Color | string | Resource) 339 340为组件添加颜色叠加效果。 341 342**系统能力：** SystemCapability.ArkUI.ArkUI.Full 343 344**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 345 346**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 347 348**参数：** 349 350| 参数名 | 类型 | 必填 | 说明 | 351| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------- | 352| value | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | 是 | 为当前组件添加颜色叠加效果，入参为叠加的颜色字符串。 | 353 354## colorBlend<sup>18+</sup> 355 356colorBlend(color: Optional\<Color | string | Resource>) 357 358为组件添加颜色叠加效果。与[colorBlend<sup>7+</sup>](#colorblend7)相比，color参数新增了对undefined类型的支持。 359 360**系统能力：** SystemCapability.ArkUI.ArkUI.Full 361 362**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 363 364**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 365 366**参数：** 367 368| 参数名 | 类型 | 必填 | 说明 | 369| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 370| color | Optional\<[Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource)> | 是 | 为当前组件添加颜色叠加效果，入参为叠加的颜色。<br/>当color的值为undefined时，恢复为无颜色叠加的效果。 | 371 372## linearGradientBlur<sup>12+</sup> 373 374linearGradientBlur(value: number, options: LinearGradientBlurOptions) 375 376为组件添加内容线性渐变模糊效果。 377 378**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 379 380**系统能力：** SystemCapability.ArkUI.ArkUI.Full 381 382**参数：** 383 384| 参数名 | 类型 | 必填 | 说明 | 385| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 386| value | number | 是 | 为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>取值范围：[0, 1000]<br/>线性梯度模糊包含两个部分fractionStops和direction。 | 387| options | [LinearGradientBlurOptions](#lineargradientbluroptions12对象说明) | 是 | 设置线性渐变模糊效果。 | 388 389## linearGradientBlur<sup>18+</sup> 390 391linearGradientBlur(value: Optional\<number>, options: Optional\<LinearGradientBlurOptions>) 392 393为组件添加内容线性渐变模糊效果。与[linearGradientBlur<sup>12+</sup>](#lineargradientblur12)相比，value参数新增了对undefined类型的支持。 394 395**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 396 397**系统能力：** SystemCapability.ArkUI.ArkUI.Full 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 403| value | Optional\<number> | 是 | 为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>取值范围：[0, 1000]<br/>线性梯度模糊包含两个部分fractionStops和direction。<br/>当value的值为undefined时，恢复为渐变模糊为0的效果。 | 404| options | Optional\<[LinearGradientBlurOptions](#lineargradientbluroptions12对象说明)> | 是 | 设置线性渐变模糊效果。<br/>当options的值为undefined时，恢复为渐变模糊为0的效果。 | 405 406## renderGroup<sup>10+</sup> 407 408renderGroup(value: boolean) 409 410设置当前控件和子控件是否先整体离屏渲染绘制后再与父控件融合绘制。 411 412**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 413 414**系统能力：** SystemCapability.ArkUI.ArkUI.Full 415 416**参数：** 417 418| 参数名 | 类型 | 必填 | 说明 | 419| ------ | ------- | ---- | ------------------------------------------------------------ | 420| value | boolean | 是 | 设置当前控件和子控件是否先整体离屏渲染绘制后再与父控件融合绘制。当前控件的不透明度不为1时绘制效果可能有差异。<br/>默认值：false <br/> false表示不进行离屏渲染直接绘制。 | 421 422## renderGroup<sup>18+</sup> 423 424renderGroup(isGroup: Optional\<boolean>) 425 426设置当前控件和子控件是否先整体离屏渲染绘制后再与父控件融合绘制。与[renderGroup<sup>10+</sup>](#rendergroup10)相比，isGroup参数新增了对undefined类型的支持。 427 428**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 429 430**系统能力：** SystemCapability.ArkUI.ArkUI.Full 431 432**参数：** 433 434| 参数名 | 类型 | 必填 | 说明 | 435| ------- | ------------------ | ---- | ------------------------------------------------------------ | 436| isGroup | Optional\<boolean> | 是 | 设置当前控件和子控件是否先整体离屏渲染绘制后再与父控件融合绘制。当前控件的不透明度不为1时绘制效果可能有差异。<br/>默认值：false<br/>当isGroup的值为undefined时，恢复为不开启整体离屏渲染绘制后再与父控件融合绘制的效果。 | 437 438## blendMode<sup>11+</sup> 439 440blendMode(value: BlendMode, type?: BlendApplyType) 441 442将当前控件的内容（包含子节点内容）与下方画布（可能为离屏画布）已有内容进行混合。 443 444**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 445 446**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 447 448**系统能力：** SystemCapability.ArkUI.ArkUI.Full 449 450**参数：** 451 452| 参数名 | 类型 | 必填 | 说明 | 453| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 454| value | [BlendMode](#blendmode11枚举说明) | 是 | 混合模式。<br/>默认值：BlendMode.NONE<br/>**说明：**<br/>混合模式设置为BlendMode.NONE时，blend效果实际为默认的BlendMode.SRC_OVER，且BlendApplyType不生效。 | 455| type | [BlendApplyType](#blendapplytype11枚举说明) | 否 | blendMode实现方式是否离屏。<br/>默认值：BlendApplyType.FAST<br/>**说明：**<br/>1. 设置BlendApplyType.FAST时，不离屏。<br/>2. 设置BlendApplyType.OFFSCREEN时，会创建当前组件大小的离屏画布，再将当前组件（含子组件）的内容绘制到离屏画布上，再用指定的混合模式与下方画布已有内容进行混合。使用该实现方式时，将导致[linearGradientBlur<sup>12+</sup>](#lineargradientblur12)，[backgroundEffect](ts-universal-attributes-background.md#backgroundeffect11)，[brightness](#brightness)等需要截屏的接口无法截取到正确的画面。 | 456 457## blendMode<sup>18+</sup> 458 459blendMode(mode: Optional\<BlendMode>, type?: BlendApplyType) 460 461将当前控件的内容（包含子节点内容）与下方画布（可能为离屏画布）已有内容进行混合。与[blendMode<sup>11+</sup>](#blendmode11)相比，mode参数新增了对undefined类型的支持。 462 463**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 464 465**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 466 467**系统能力：** SystemCapability.ArkUI.ArkUI.Full 468 469**参数：** 470 471| 参数名 | 类型 | 必填 | 说明 | 472| ------ | ------------------------------- | ---- | ------------------------------------------------------------ | 473| mode | Optional\<[BlendMode](#blendmode11枚举说明)> | 是 | 混合模式。<br/>默认值：BlendMode.NONE<br/>当mode的值为undefined时，恢复为内容不进行混合的效果。<br/>**说明：**<br/>混合模式设置为BlendMode.NONE时，blend效果实际为默认的BlendMode.SRC_OVER，且BlendApplyType不生效。 | 474| type | [BlendApplyType](#blendapplytype11枚举说明) | 否 | blendMode实现方式是否离屏。<br/>默认值：BlendApplyType.FAST<br/>**说明：**<br/>1. 设置BlendApplyType.FAST时，不离屏。<br/>2. 设置BlendApplyType.OFFSCREEN时，会创建当前组件大小的离屏画布，再将当前组件（含子组件）的内容绘制到离屏画布上，再用指定的混合模式与下方画布已有内容进行混合。使用该实现方式时，将导致[linearGradientBlur<sup>12+</sup>](#lineargradientblur12)，[backgroundEffect](ts-universal-attributes-background.md#backgroundeffect11)，[brightness](#brightness)等需要截屏的接口无法截取到正确的画面。| 475 476## BlendApplyType<sup>11+</sup>枚举说明 477 478指示如何将指定的混合模式应用于视图的内容。 479 480**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 481 482**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 483 484**系统能力：** SystemCapability.ArkUI.ArkUI.Full 485 486| 名称 | 描述 | 487| ---------------| ---------------------------------------------------------------- | 488| FAST | 在目标图像上按顺序混合视图的内容。 | 489| OFFSCREEN | 将此组件和子组件内容绘制到离屏画布上，然后整体进行混合。 | 490 491## useShadowBatching<sup>11+</sup> 492 493useShadowBatching(value: boolean) 494 495控件内部子节点的阴影进行同层绘制，同层元素阴影重叠。 496 497**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 498 499**系统能力：** SystemCapability.ArkUI.ArkUI.Full 500 501**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 502 503**参数：** 504 505| 参数名 | 类型 | 必填 | 说明 | 506| ------ | ------- | ---- | ------------------------------------------------------------ | 507| value | boolean | 是 | 控件内部子节点的阴影进行同层绘制，同层元素阴影重叠。<br/>默认值：false<br/>**说明：**<br/>1. 默认不开启，如果子节点的阴影半径较大，节点各自的阴影会互相重叠。 当开启时，元素的阴影将不会重叠。<br/>2. 不推荐useShadowBatching嵌套使用，如果嵌套使用，只会对当前的子节点生效，无法递推。 | 508 509## useShadowBatching<sup>18+</sup> 510 511useShadowBatching(use: Optional\<boolean>) 512 513控件内部子节点的阴影进行同层绘制，同层元素阴影重叠。与[useShadowBatching<sup>11+</sup>](#useshadowbatching11)相比，use参数新增了对undefined类型的支持。 514 515**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 516 517**系统能力：** SystemCapability.ArkUI.ArkUI.Full 518 519**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 520 521**参数：** 522 523| 参数名 | 类型 | 必填 | 说明 | 524| ------ | ------------------ | ---- | ------------------------------------------------------------ | 525| use | Optional\<boolean> | 是 | 控件内部子节点的阴影进行同层绘制，同层元素阴影重叠。<br/>默认值：false<br/>**说明：**<br/>1. 默认不开启，如果子节点的阴影半径较大，节点各自的阴影会互相重叠。 当开启时，元素的阴影将不会重叠。<br/>2. 不推荐useShadowBatching嵌套使用，如果嵌套使用，只会对当前的子节点生效，无法递推。<br/>当use的值为undefined时，恢复为不使用元素阴影重叠的效果。 | 526 527## sphericalEffect<sup>12+</sup> 528 529sphericalEffect(value: number) 530 531设置组件的图像球面化程度。 532 533**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 534 535**系统能力：** SystemCapability.ArkUI.ArkUI.Full 536 537**参数：** 538 539| 参数名 | 类型 | 必填 | 说明 | 540| ------ | ------ | ---- | ------------------------------------------------------------ | 541| value | number | 是 | 设置组件的图像球面化程度。<br/>取值范围：[0,1]。<br/>**说明：**<br/>1. 如果value等于0则图像保持原样，如果value等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。<br/>`value < 0 `或者` value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。<br/>2. 组件阴影和外描边不支持球面效果。<br>3. 设置value大于0时，组件冻屏不更新并且把组件内容绘制到透明离屏buffer上，如果要更新组件属性则需要把value设置为0。 | 542 543## sphericalEffect<sup>18+</sup> 544 545sphericalEffect(effect: Optional\<number>) 546 547设置组件的图像球面化程度。与[sphericalEffect<sup>12+</sup>](#sphericaleffect12)相比，effect参数新增了对undefined类型的支持。 548 549**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 550 551**系统能力：** SystemCapability.ArkUI.ArkUI.Full 552 553**参数：** 554 555| 参数名 | 类型 | 必填 | 说明 | 556| ------ | ----------------- | ---- | ------------------------------------------------------------ | 557| effect | Optional\<number> | 是 | 设置组件的图像球面化程度。<br/>取值范围：[0,1]。<br/>**说明：**<br/>1. 如果value等于0则图像保持原样，如果value等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。<br/>`effect < 0 `或者` effect > 1`为异常情况，`effect < 0`按0处理，`effect > 1`按1处理。<br/>2. 组件阴影和外描边不支持球面效果。<br/>3. 设置effect大于0时，组件冻屏不更新并且把组件内容绘制到透明离屏buffer上，如果要更新组件属性则需要把effect设置为0。<br/>当effect的值为undefined时，恢复为图像球面化程度为0的效果。 | 558 559## lightUpEffect<sup>12+</sup> 560 561lightUpEffect(value: number) 562 563设置组件图像亮起程度。 564 565**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 566 567**系统能力：** SystemCapability.ArkUI.ArkUI.Full 568 569**参数：** 570 571| 参数名 | 类型 | 必填 | 说明 | 572| ------ | ------ | ---- | ------------------------------------------------------------ | 573| value | number | 是 | 设置组件图像亮起程度。<br/>取值范围：[0,1]。<br/>如果value等于0则图像为全黑，如果value等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。`value < 0` 或者 `value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。 | 574 575## lightUpEffect<sup>18+</sup> 576 577lightUpEffect(degree: Optional\<number>) 578 579设置组件图像亮起程度。与[lightUpEffect<sup>12+</sup>](#lightupeffect12)相比，degree参数新增了对undefined类型的支持。 580 581**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 582 583**系统能力：** SystemCapability.ArkUI.ArkUI.Full 584 585**参数：** 586 587| 参数名 | 类型 | 必填 | 说明 | 588| ------ | ----------------- | ---- | ------------------------------------------------------------ | 589| degree | Optional\<number> | 是 | 设置组件图像亮起程度。<br/>取值范围：[0,1]。<br/>如果value等于0则图像为全黑，如果value等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。`degree < 0` 或者 `degree > 1`为异常情况，`degree < 0`按0处理，`degree > 1`按1处理。<br/>当degree的值为undefined时，恢复为亮起为1的效果。 | 590 591## pixelStretchEffect<sup>12+</sup> 592 593pixelStretchEffect(options: PixelStretchEffectOptions) 594 595设置组件的图像边缘像素扩展距离。 596 597**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 598 599**系统能力：** SystemCapability.ArkUI.ArkUI.Full 600 601**参数：** 602 603| 参数名 | 类型 | 必填 | 说明 | 604| ------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 605| options | [PixelStretchEffectOptions](#pixelstretcheffectoptions10) | 是 | 设置组件的图像边缘像素扩展距离。<br/>参数`options`包括上下左右四个方向的边缘像素扩展距离。<br/>**说明：**<br/>1. 如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。<br/>2. 如果距离为负值，表示内缩，但是最终图像大小不变。<br/>内缩方式：<br/>图像根据`options`的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。<br/>图像用边缘像素扩展到原来大小。<br/>3. 对`options`的输入约束：<br/>上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。<br/>所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。<br/>所有异常情况下，显示为{0，0，0，0}效果，即跟原图保持一致。 | 606 607## pixelStretchEffect<sup>18+</sup> 608 609pixelStretchEffect(options: Optional\<PixelStretchEffectOptions>) 610 611设置组件的图像边缘像素扩展距离。与[pixelStretchEffect<sup>12+</sup>](#pixelstretcheffect12)相比，options参数新增了对undefined类型的支持。 612 613**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 614 615**系统能力：** SystemCapability.ArkUI.ArkUI.Full 616 617**参数：** 618 619| 参数名 | 类型 | 必填 | 说明 | 620| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 621| options | Optional\<[PixelStretchEffectOptions](#pixelstretcheffectoptions10)> | 是 | 设置组件的图像边缘像素扩展距离。<br/>参数`options`包括上下左右四个方向的边缘像素扩展距离。<br/>**说明：**<br/>1. 如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。<br/>2. 如果距离为负值，表示内缩，但是最终图像大小不变。<br/>内缩方式：<br/>图像根据`options`的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。<br/>图像用边缘像素扩展到原来大小。<br/>3. 对`options`的输入约束：<br/>上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。<br/>所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。<br/>所有异常情况下，显示为{0，0，0，0}效果，即跟原图保持一致。<br/>当options的值为undefined时，恢复为无像素扩展效果。 | 622 623## PixelStretchEffectOptions<sup>10+</sup> 624 625像素扩展属性集合,用于描述像素扩展的信息。 626 627**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 628 629**系统能力：** SystemCapability.ArkUI.ArkUI.Full 630 631| 名称 | 类型 | 必填 | 说明 | 632| ------ | ----------------- | ---- | -------------- | 633| left | [Length](ts-types.md#length) | 否 | 组件图像左边沿像素扩展距离。 | 634| right | [Length](ts-types.md#length) | 否 | 组件图像右边沿像素扩展距离。 | 635| top | [Length](ts-types.md#length) | 否 | 组件图像上边沿像素扩展距离。 | 636| bottom | [Length](ts-types.md#length) | 否 | 组件图像下边沿像素扩展距离。 | 637 638## systemBarEffect<sup>12+</sup> 639 640systemBarEffect() 641 642根据背景进行智能反色并且带有模糊效果。 643 644**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 645 646**系统能力：** SystemCapability.ArkUI.ArkUI.Full 647 648## ShadowType<sup>10+<sup>枚举说明 649 650阴影类型。 651 652**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 653 654**系统能力：** SystemCapability.ArkUI.ArkUI.Full 655 656| 名称 | 描述 | 657| -------- | ---------------------------------------- | 658| COLOR | 颜色。 | 659| BLUR | 模糊。 | 660 661 662## ShadowOptions对象说明 663 664阴影属性集合，用于设置阴影的模糊半径、阴影的颜色、X轴和Y轴的偏移量。 665 666 667**系统能力：** SystemCapability.ArkUI.ArkUI.Full 668 669**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 670 671| 名称 | 类型 | 必填 | 说明 | 672| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 673| radius | number \| [Resource](ts-types.md#resource) | 是 | 阴影模糊半径。<br/>取值范围：[0, +∞)<br/>单位：px<br/>**说明：** <br/>设置小于0的值时，按值为0处理。<br/>如需使用vp单位的数值可用[vp2px](ts-pixel-units.md#像素单位转换)进行转换。<br/>如果radius为Resource类型，则传入的值需为number类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 674| type<sup>10+</sup> | [ShadowType<sup>10+</sup>](#shadowtype10枚举说明) | 否 | 阴影类型。<br/>默认为COLOR。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 675| color | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource)\| [ColoringStrategy<sup>10+</sup> ](ts-appendix-enums.md#coloringstrategy10) | 否 | 阴影的颜色。<br/>默认为黑色。 <br/>**说明：** <br/>从API version 11开始，该接口支持使用ColoringStrategy实现智能取色，智能取色功能不支持在ArkTS卡片、[textShadow](ts-basic-components-text.md#textshadow10)中使用。<br/>当前仅支持平均取色和主色取色，智能取色区域为shadow绘制区域。<br/>支持使用'average'字符串触发智能平均取色模式，支持使用'primary'字符串触发智能主色模式。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 676| offsetX | number \| [Resource](ts-types.md#resource) | 否 | 阴影的X轴偏移量。<br/>默认值：0<br/>单位：px<br/>**说明：** <br/>如需使用vp单位的数值可用[vp2px](ts-pixel-units.md#像素单位转换)进行转换。<br/>如果offsetX为Resource类型，则传入的值需为number类型。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 677| offsetY | number \| [Resource](ts-types.md#resource) | 否 | 阴影的Y轴偏移量。<br/>默认值：0<br/>单位：px<br/>**说明：** <br/>如需使用vp单位的数值可用[vp2px](ts-pixel-units.md#像素单位转换)进行转换。<br/>如果offsetY为Resource类型，则传入的值需为number类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 678| fill<sup>11+</sup> | boolean | 否 | 阴影是否内部填充。true表示阴影在内部填充，false表示阴影在外部填充。<br/>默认为false。<br/>**说明：**<br/>[textShadow](ts-basic-components-text.md#textshadow10)中该字段不生效。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 679 680## ShadowStyle<sup>10+</sup>枚举说明 681 682**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 683 684| 名称 | 描述 | 685| ----------------- | ------ | 686| OUTER_DEFAULT_XS | 超小阴影。 | 687| OUTER_DEFAULT_SM | 小阴影。 | 688| OUTER_DEFAULT_MD | 中阴影。 | 689| OUTER_DEFAULT_LG | 大阴影。 | 690| OUTER_FLOATING_SM | 浮动小阴影。 | 691| OUTER_FLOATING_MD | 浮动中阴影。 | 692 693## BlendMode<sup>11+</sup>枚举说明 694 695> **说明：** 696> 697> blendMode枚举中，s表示源像素，d表示目标像素，sa表示原像素透明度，da表示目标像素透明度，r表示混合后像素，ra表示混合后像素透明度。 698 699**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 700 701**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 702 703| 名称 | 描述 | 704| ---------------| ------ | 705| NONE | 将上层图像直接覆盖到下层图像上，不进行任何混合操作。 | 706| CLEAR | 将源像素覆盖的目标像素清除为完全透明。 | 707| SRC | r = s，只显示源像素。 | 708| DST | r = d，只显示目标像素。 | 709| SRC_OVER | r = s + (1 - sa) * d，将源像素按照透明度进行混合，覆盖在目标像素上。 | 710| DST_OVER | r = d + (1 - da) * s，将目标像素按照透明度进行混合，覆盖在源像素上。 | 711| SRC_IN | r = s * da，只显示源像素中与目标像素重叠的部分。 | 712| DST_IN | r = d * sa，只显示目标像素中与源像素重叠的部分。 | 713| SRC_OUT | r = s * (1 - da)，只显示源像素中与目标像素不重叠的部分。 | 714| DST_OUT | r = d * (1 - sa)，只显示目标像素中与源像素不重叠的部分。 | 715| SRC_ATOP | r = s * da + d * (1 - sa)，在源像素和目标像素重叠的地方绘制源像素，在源像素和目标像素不重叠的地方绘制目标像素。 | 716| DST_ATOP | r = d * sa + s * (1 - da)，在源像素和目标像素重叠的地方绘制目标像素，在源像素和目标像素不重叠的地方绘制源像素。 | 717| XOR | r = s * (1 - da) + d * (1 - sa)，只显示源像素与目标像素不重叠的部分。 | 718| PLUS | r = min(s + d, 1)，将源像素值与目标像素值相加，并将结果作为新的像素值。 | 719| MODULATE | r = s * d，将源像素与目标像素进行乘法运算，并将结果作为新的像素值。 | 720| SCREEN | r = s + d - s * d，将两个图像的像素值相加，然后减去它们的乘积来实现混合。 | 721| OVERLAY | 根据目标像素来决定使用MULTIPLY混合模式还是SCREEN混合模式。 | 722| DARKEN | rc = s + d - max(s * da, d * sa), ra = kSrcOver，当两个颜色重叠时，较暗的颜色会覆盖较亮的颜色。 | 723| LIGHTEN | rc = s + d - min(s * da, d * sa), ra = kSrcOver，将源图像和目标图像中的像素进行比较，选取两者中较亮的像素作为最终的混合结果。 | 724| COLOR_DODGE | 使目标像素变得更亮来反映源像素。 | 725| COLOR_BURN | 使目标像素变得更暗来反映源像素。 | 726| HARD_LIGHT | 根据源像素的值来决定目标像素变得更亮或者更暗。根据源像素来决定使用MULTIPLY混合模式还是SCREEN混合模式。 | 727| SOFT_LIGHT | 根据源像素来决定使用LIGHTEN混合模式还是DARKEN混合模式。 | 728| DIFFERENCE | rc = s + d - 2 * (min(s * da, d * sa)), ra = kSrcOver，对比源像素和目标像素，亮度更高的像素减去亮度更低的像素，产生高对比度的效果。 | 729| EXCLUSION | rc = s + d - two(s * d), ra = kSrcOver，对比源像素和目标像素，亮度更高的像素减去亮度更低的像素，产生柔和的效果。 | 730| MULTIPLY | r = s * (1 - da) + d * (1 - sa) + s * d，将源图像与目标图像进行乘法混合，得到一张新的图像。 | 731| HUE | 保留源图像的亮度和饱和度，但会使用目标图像的色调来替换源图像的色调。 | 732| SATURATION | 保留目标像素的亮度和色调，但会使用源像素的饱和度来替换目标像素的饱和度。 | 733| COLOR | 保留源像素的饱和度和色调，但会使用目标像素的亮度来替换源像素的亮度。 | 734| LUMINOSITY | 保留目标像素的色调和饱和度，但会用源像素的亮度替换目标像素的亮度。 | 735 736## LinearGradientBlurOptions<sup>12+</sup>对象说明 737 738**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 739 740| 名称 | 类型 | 必填 | 说明 | 741| ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | 742| fractionStops | Array\<[FractionStop](#fractionstop12)> | 是 | 数组中保存的每一个二元数组（取值0-1，小于0则为0，大于1则为1）表示[模糊程度, 模糊位置]；模糊位置需严格递增，开发者传入的数据不符合规范会记录日志，渐变模糊数组中二元数组个数必须大于等于2，否则渐变模糊不生效。 | 743| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | 是 | 渐变模糊方向。<br/>默认值：<br/>GradientDirection.Bottom | 744 745## FractionStop<sup>12+</sup> 746 747FractionStop = [ number, number ] 748 749定义模糊段。 750 751**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 752 753**系统能力：** SystemCapability.ArkUI.ArkUI.Full 754 755| 取值范围 | 说明 | 756| ------------- | ---------------------------------------------------------- | 757| number | 分数,值1表示不透明，0表示完全透明。<br/>取值范围：[0,1] | 758| number | 停止位置,值1表示区域结束位置，0表示区域开始位置。<br/> 取值范围:[0,1] | 759 760## InvertOptions<sup>11+</sup>对象说明 761 762前景智能取反色。 763 764**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 765 766| 名称 | 类型 | 必填 | 说明 | 767| -------------- | ------ | ----- | ------------------------------------------ | 768| low | number | 是 | 背景颜色灰度值大于阈值区间时的取值。 <br/>取值范围：[0,1] | 769| high | number | 是 | 背景颜色灰度值小于阈值区间时的取值。 <br/>取值范围：[0,1] | 770| threshold | number | 是 | 灰度阈值。 <br/>取值范围：[0,1] | 771| thresholdRange | number | 是 | 阈值范围。<br/>取值范围：[0,1]<br/>**说明：**<br/>灰度阈值上下偏移thresholdRange构成阈值区间，背景颜色灰度值在区间内取值由high线性渐变到low。| 772 773## BackgroundImageOptions<sup>18+</sup> 774 775定义背景图选项。 776 777**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 778 779**系统能力：** SystemCapability.ArkUI.ArkUI.Full 780 781> **说明：** 782> 783> 背景图片的同步加载可能会带来潜在性能问题，详情可见[Image](ts-basic-components-image.md#image-1)中说明。 784 785| 名称 | 类型 | 必填 | 说明 | 786| -------------- | ------------------------------------------------| ----- | --------------------------------------------------------| 787| syncLoad | boolean | 否 | 设置背景图片的同步或异步加载模式。<br/>默认值：false <br/>true时为同步加载模式，false时为异步加载模式。 | 788| repeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 否 | 设置背景图片的重复样式。 | 789 790## freeze<sup>12+</sup> 791 792freeze(value: boolean) 793 794设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。 795 796**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 797 798**系统能力：** SystemCapability.ArkUI.ArkUI.Full 799 800**参数：** 801 802| 参数名 | 类型 | 必填 | 说明 | 803| ------ | ------- | ---- | ------------------------------------------------------------ | 804| value | boolean | 是 | 设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当前控件的不透明度不为1时绘制效果可能有差异。<br/>默认值：false <br/> true时离屏渲染绘制后重复绘制缓存，false时离屏渲染绘制后不重复绘制缓存。| 805 806## freeze<sup>18+</sup> 807 808freeze(freeze: Optional\<boolean>) 809 810设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。与[freeze](#freeze12)相比，freeze参数新增了对undefined类型的支持。 811 812**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 813 814**系统能力：** SystemCapability.ArkUI.ArkUI.Full 815 816**参数：** 817 818| 参数名 | 类型 | 必填 | 说明 | 819| ------ | ------------------ | ---- | ------------------------------------------------------------ | 820| freeze | Optional\<boolean> | 是 | 设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当前控件的不透明度不为1时绘制效果可能有差异。<br/>默认值：false<br/> true时离屏渲染绘制后重复绘制缓存，false时离屏渲染绘制后不重复绘制缓存。<br/>当freeze的值为undefined时，维持之前取值。 | 821 822## 示例 823 824### 示例1（设置图片不同属性效果） 825设置图片的效果，包括阴影，灰度，高光，饱和度，对比度，图像反转，叠色，色相旋转等。 826```ts 827// xxx.ets 828@Entry 829@Component 830struct ImageEffectsExample { 831 build() { 832 Column({ space: 5 }) { 833 // 添加阴影效果，图片效果不变 834 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 835 Image($r('app.media.image')) 836 .width('90%') 837 .height(30) 838 .shadow({ 839 radius: 10, 840 color: Color.Green, 841 offsetX: 20, 842 offsetY: 20 843 }) 844 845 // 添加内部阴影效果 846 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 847 Image($r('app.media.image')) 848 .width('90%') 849 .height(30) 850 .shadow({ 851 radius: 5, 852 color: Color.Green, 853 offsetX: 20, 854 offsetY: 20, 855 fill: true 856 }).opacity(0.5) 857 858 // 灰度效果0~1，越接近1，灰度越明显 859 Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%') 860 Image($r('app.media.image')).width('90%').height(30).grayscale(0.3) 861 Image($r('app.media.image')).width('90%').height(30).grayscale(0.8) 862 863 // 高光效果，1为正常图片，<1变暗，>1亮度增大 864 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 865 Image($r('app.media.image')).width('90%').height(30).brightness(1.2) 866 867 // 饱和度，原图为1 868 Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%') 869 Image($r('app.media.image')).width('90%').height(30).saturate(2.0) 870 Image($r('app.media.image')).width('90%').height(30).saturate(0.7) 871 872 // 对比度，1为原图，>1值越大越清晰，<1值越小越模糊 873 Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%') 874 Image($r('app.media.image')).width('90%').height(30).contrast(2.0) 875 Image($r('app.media.image')).width('90%').height(30).contrast(0.8) 876 877 // 图像反转比例 878 Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%') 879 Image($r('app.media.image')).width('90%').height(30).invert(0.2) 880 Image($r('app.media.image')).width('90%').height(30).invert(0.8) 881 882 // 叠色添加 883 Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%') 884 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Green) 885 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Blue) 886 887 // 深褐色 888 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 889 Image($r('app.media.image')).width('90%').height(30).sepia(0.8) 890 891 // 色相旋转 892 Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%') 893 Image($r('app.media.image')).width('90%').height(30).hueRotate(90) 894 }.width('100%').margin({ top: 5 }) 895 } 896} 897``` 898 899 900 901 902### 示例2（设置组件线性渐变模糊效果） 903 904该示例主要演示通过linearGradientBlur设置组件的内容线性渐变模糊效果。 905 906```ts 907// xxx.ets 908@Entry 909@Component 910struct ImageExample1 { 911 private_resource1: Resource = $r('app.media.testlinearGradientBlurOrigin') 912 @State image_src: Resource = this.private_resource1 913 914 build() { 915 Column() { 916 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 917 Row({ space: 5 }) { 918 Image(this.image_src) 919 .linearGradientBlur(60, 920 { fractionStops: [[0, 0], [0, 0.33], [1, 0.66], [1, 1]], direction: GradientDirection.Bottom }) 921 } 922 } 923 } 924 } 925} 926``` 927 928 929 930### 示例3（设置离屏渲染效果） 931 932该示例主要演示通过renderGroup来设置组件是否先整体离屏渲染绘制后，再与父控件融合绘制。 933 934```ts 935// xxx.ets 936@Component 937struct Component1 { 938 @Prop renderGroupValue: boolean; 939 940 build() { 941 Row() { 942 Row() { 943 Row() 944 .backgroundColor(Color.Black) 945 .width(100) 946 .height(100) 947 .opacity(1) 948 } 949 .backgroundColor(Color.White) 950 .width(150) 951 .height(150) 952 .justifyContent(FlexAlign.Center) 953 .opacity(0.6) 954 .renderGroup(this.renderGroupValue) 955 } 956 .backgroundColor(Color.Black) 957 .width(200) 958 .height(200) 959 .justifyContent(FlexAlign.Center) 960 .opacity(1) 961 } 962} 963 964@Entry 965@Component 966struct RenderGroupExample { 967 build() { 968 Column() { 969 Component1({ renderGroupValue: true }) 970 .margin(20) 971 Component1({ renderGroupValue: false }) 972 .margin(20) 973 } 974 .width("100%") 975 .height("100%") 976 .alignItems(HorizontalAlign.Center) 977 } 978} 979``` 980 981 982 983### 示例4（当前组件内容与下方画布内容混合） 984 985该示例主要演示通过blendMode将当前组件内容与下方画布内容混合。 986 987```ts 988// xxx.ets 989@Entry 990@Component 991struct Index { 992 build() { 993 Column() { 994 Text("blendMode") 995 .fontSize(20) 996 .fontWeight(FontWeight.Bold) 997 .fontColor('#ffff0101') 998 Row() { 999 Circle() 1000 .width(200) 1001 .height(200) 1002 .fill(Color.Green) 1003 .position({ x: 50, y: 50 }) 1004 Circle() 1005 .width(200) 1006 .height(200) 1007 .fill(Color.Blue) 1008 .position({ x: 150, y: 50 }) 1009 } 1010 .blendMode(BlendMode.OVERLAY, BlendApplyType.OFFSCREEN) 1011 .alignItems(VerticalAlign.Center) 1012 .height(300) 1013 .width('100%') 1014 } 1015 .height('100%') 1016 .width('100%') 1017 .backgroundImage($r('app.media.image')) 1018 .backgroundImageSize(ImageSize.Cover) 1019 } 1020} 1021``` 1022 1023<br/>BlendMode.OVERLAY,BlendApplyType.OFFSCREEN<br/> 1024 1025<br/>不同的混合模式搭配是否需要离屏从而产生不同的效果。 1026 1027### 示例5（前景智能取反色） 1028 1029该示例主要通过InvertOptions来实现前景智能取反色。 1030 1031```ts 1032// xxx.ets 1033@Entry 1034@Component 1035struct Index { 1036 build() { 1037 Stack() { 1038 Column() 1039 Stack() { 1040 Image($r('app.media.r')).width('100%') 1041 Column() { 1042 Column().width("100%").height(30).invert({ 1043 low: 0, 1044 high: 1, 1045 threshold: 0.5, 1046 thresholdRange: 0.2 1047 }) 1048 Column().width("100%").height(30).invert({ 1049 low: 0.2, 1050 high: 0.5, 1051 threshold: 0.3, 1052 thresholdRange: 0.2 1053 }) 1054 } 1055 } 1056 .width('100%') 1057 .height('100%') 1058 } 1059 } 1060} 1061``` 1062 1063 1064 1065### 示例6（设置同层阴影不重叠效果） 1066 1067该示例主要通过useShadowBatching搭配shadow实现同层阴影不重叠效果。 1068 1069```ts 1070// xxx.ets 1071@Entry 1072@Component 1073struct UseShadowBatchingExample { 1074 build() { 1075 Column() { 1076 Column({ space: 10 }) { 1077 Stack() { 1078 1079 } 1080 .width('90%') 1081 .height(50) 1082 .margin({ top: 5 }) 1083 .backgroundColor(0xFFE4C4) 1084 .shadow({ 1085 radius: 120, 1086 color: Color.Green, 1087 offsetX: 0, 1088 offsetY: 0 1089 }) 1090 .align(Alignment.TopStart) 1091 .shadow({ 1092 radius: 120, 1093 color: Color.Green, 1094 offsetX: 0, 1095 offsetY: 0 1096 }) 1097 1098 Stack() { 1099 1100 } 1101 .width('90%') 1102 .height(50) 1103 .margin({ top: 5 }) 1104 .backgroundColor(0xFFE4C4) 1105 .align(Alignment.TopStart) 1106 .shadow({ 1107 radius: 120, 1108 color: Color.Red, 1109 offsetX: 0, 1110 offsetY: 0 1111 }) 1112 .width('90%') 1113 .backgroundColor(Color.White) 1114 1115 Column() { 1116 Text() 1117 .fontWeight(FontWeight.Bold) 1118 .fontSize(20) 1119 .fontColor(Color.White) 1120 } 1121 .justifyContent(FlexAlign.Center) 1122 .width(150) 1123 .height(150) 1124 .borderRadius(10) 1125 .backgroundColor(0xf56c6c) 1126 .shadow({ 1127 radius: 300, 1128 color: Color.Yellow, 1129 offsetX: 0, 1130 offsetY: 0 1131 }) 1132 1133 Column() { 1134 Text() 1135 .fontWeight(FontWeight.Bold) 1136 .fontSize(20) 1137 .fontColor(Color.White) 1138 } 1139 .justifyContent(FlexAlign.Center) 1140 .width(150) 1141 .height(150) 1142 .backgroundColor(0x67C23A) 1143 .borderRadius(10) 1144 .translate({ y: -50 }) 1145 .shadow({ 1146 radius: 220, 1147 color: Color.Blue, 1148 offsetX: 0, 1149 offsetY: 0 1150 }) 1151 } 1152 .useShadowBatching(true) 1153 } 1154 .width('100%').margin({ top: 5 }) 1155 } 1156} 1157``` 1158 1159 1160 1161### 示例7（设置组件图像球面效果） 1162 1163该示例主要演示通过sphericalEffect设置组件的图像球面效果。 1164 1165```ts 1166// xxx.ets 1167@Entry 1168@Component 1169struct SphericalEffectExample { 1170 build() { 1171 Stack() { 1172 TextInput({ placeholder: "请输入变化范围百分比（[0%,100%]）" }) 1173 .width('50%') 1174 .height(35) 1175 .type(InputType.Number) 1176 .enterKeyType(EnterKeyType.Done) 1177 .caretColor(Color.Red) 1178 .placeholderColor(Color.Blue) 1179 .placeholderFont({ 1180 size: 20, 1181 style: FontStyle.Italic, 1182 weight: FontWeight.Bold 1183 }) 1184 .sphericalEffect(0.5) 1185 }.alignContent(Alignment.Center).width("100%").height("100%") 1186 } 1187} 1188``` 1189 1190效果图如下： 1191 1192 1193 1194去掉sphericalEffect的设置，效果如下： 1195 1196 1197 1198### 示例8（设置组件图像渐亮效果） 1199 1200该示例主要演示通过lightUpEffect设置组件的图像渐亮效果。 1201 1202```ts 1203// xxx.ets 1204@Entry 1205@Component 1206struct LightUpExample { 1207 build() { 1208 Stack() { 1209 Text('This is the text content with letterSpacing 0.') 1210 .letterSpacing(0) 1211 .fontSize(12) 1212 .border({ width: 1 }) 1213 .padding(10) 1214 .width('50%') 1215 .lightUpEffect(0.6) 1216 }.alignContent(Alignment.Center).width("100%").height("100%") 1217 } 1218} 1219 1220``` 1221 1222效果图如下： 1223 1224 1225 1226修改lightUpEffect参数值为0.2： 1227 1228 1229 1230去掉lightUpEffect的设置，效果如下： 1231 1232 1233 1234### 示例9（设置组件图像边缘像素扩展效果） 1235 1236该示例主要演示通过pixelStretchEffect设置组件的图像边缘像素扩展效果。 1237 1238```ts 1239// xxx.ets 1240@Entry 1241@Component 1242struct PixelStretchExample { 1243 build() { 1244 Stack() { 1245 Text('This is the text content with letterSpacing 0.') 1246 .letterSpacing(0) 1247 .fontSize(12) 1248 .border({ width: 1 }) 1249 .padding(10) 1250 .clip(false) 1251 .width('50%') 1252 .pixelStretchEffect({ 1253 top: 10, 1254 left: 10, 1255 right: 10, 1256 bottom: 10 1257 }) 1258 }.alignContent(Alignment.Center).width("100%").height("100%") 1259 } 1260} 1261``` 1262 1263效果图如下： 1264 1265 1266 1267去掉pixelStretchEffect的设置，原图效果如下： 1268 1269 1270 1271 1272### 示例10（系统导航条智能反色） 1273 1274该示例主要演示通过systemBarEffect来实现系统导航条智能反色。 1275 1276```ts 1277// xxx.ets 1278@Entry 1279@Component 1280struct Index { 1281 build() { 1282 Column() { 1283 Stack() { 1284 Image($r('app.media.testImage')).width('100%').height('100%') 1285 Column() 1286 .width(150) 1287 .height(10) 1288 .systemBarEffect() 1289 .border({ radius: 5 }) 1290 .margin({ bottom: 80 }) 1291 }.alignContent(Alignment.Center) 1292 } 1293 } 1294} 1295``` 1296 1297效果图如下： 1298 1299
