# 图像效果

> phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+

设置组件的模糊、阴影、球面效果以及设置图像效果。
> 说明
>
> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

## blur

blur(value: number, options?: BlurOptions): T

为组件添加内容模糊效果。当组件设置了BlendApplyType.OFFSCREEN的blendMode时，该接口可能无法截取到正确画面。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-----------|:-------------------------------------------------------------------------------------------------------------------------------------------|:-|:----------------------------------------------------------------------|
|value|number|是|模糊半径，模糊半径越大越模糊，值小于等于0时不模糊。 单位：px|
|options^11+^|[BlurOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-foreground-blur-style#bluroptions11)|否|灰阶模糊参数。对图像中的黑白色进行色阶调整，使黑白灰度过渡更加平滑柔和，对图像中的彩色调整没有效果。 默认值：grayscale: [0,0]|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## blur^18+^

blur(blurRadius: Optional<number>, options?: BlurOptions): T

为组件添加内容模糊效果。与[blur](#blur)相比，blurRadius参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------------------------------|
|blurRadius|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|模糊半径，模糊半径越大越模糊，值小于等于0时不模糊。 单位：px 当blurRadius的值为undefined时，维持之前取值。从未设置该属性时，默认值为0，表示不模糊。|
|options|[BlurOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-foreground-blur-style#bluroptions11)|否|灰阶模糊参数。对图像中的黑白色进行色阶调整，使其趋于灰色更为柔和美观，对图像中的彩色调整没有效果。 默认值：grayscale: [0,0]|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## blur^19+^

blur(blurRadius: Optional<number>, options?: BlurOptions, sysOptions?: SystemAdaptiveOptions): T

为组件添加内容模糊效果。与[blur^18+^](#blur18)相比，新增了sysOptions参数，即支持系统自适应调节参数。

**卡片能力：** 从API version 19开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 19开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------------------------------|
|blurRadius|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|模糊半径，模糊半径越大越模糊，值小于等于0时不模糊。 单位：px 当blurRadius的值为undefined时，维持之前取值。从未设置该属性时，默认值为0，表示不模糊。|
|options|[BlurOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-foreground-blur-style#bluroptions11)|否|灰阶模糊参数。对图像中的黑白色进行色阶调整，使其趋于灰色更为柔和美观，对图像中的彩色调整没有效果。 默认值：grayscale: [0,0]|
|sysOptions|[SystemAdaptiveOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#systemadaptiveoptions19)|否|系统自适应调节参数。 默认值：{ disableSystemAdaptation: false }|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## shadow

shadow(value: ShadowOptions | ShadowStyle): T

为组件添加阴影效果。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用，ArkTS卡片上不支持参数为 [ShadowStyle](#shadowstyle10枚举说明)类型。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:---------------------------------------------------------------------------|:-|:--------------------------------------------------------------------------------------|
|value|[ShadowOptions](#shadowoptions对象说明) | [ShadowStyle](#shadowstyle10枚举说明)^10+^|是|为当前组件添加阴影效果。 入参类型为ShadowOptions时，可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。 入参类型为ShadowStyle时，可指定不同阴影样式。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## shadow^18+^

shadow(options: Optional<ShadowOptions | ShadowStyle>): T

为组件添加阴影效果。与[shadow](#shadow)相比，options参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用，ArkTS卡片上不支持参数为[ShadowStyle](#shadowstyle10枚举说明)类型。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:----------------------------------------------------------------------------------------------------------------------|
|options|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<[ShadowOptions](#shadowoptions对象说明) | [ShadowStyle](#shadowstyle10枚举说明)>|是|为当前组件添加阴影效果。 入参类型为ShadowOptions时，可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。 入参类型为ShadowStyle时，可指定不同阴影样式。 当options的值为undefined时，恢复为无阴影效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## grayscale

grayscale(value: number): T

为组件添加灰度效果。上层渲染灰度会覆盖下层子组件渲染。未设置时，默认无变化。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:-----------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|为当前组件添加灰度效果。值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参0.0则图像无变化，入参在0.0和1.0之间时，效果呈线性变化。 取值范围：[0.0, 1.0] **说明：** 设置小于0.0的值时，按值为0.0处理，设置大于1.0的值时，按值为1.0处理。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## grayscale^18+^

grayscale(grayscale: Optional<number>): T

为组件添加灰度效果。上层渲染灰度会覆盖下层子组件渲染。未设置时，默认无变化。与[grayscale](#grayscale)相比，grayscale参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:--------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|grayscale|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|为当前组件添加灰度效果。值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参0.0则图像无变化，入参在0.0和1.0之间时，效果呈线性变化。 取值范围：[0.0, 1.0] **说明：** 设置小于0.0的值时，按值为0.0处理，设置大于1.0的值时，按值为1.0处理。 当grayscale的值为undefined时，取默认值0.0。恢复为无灰度效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## brightness

brightness(value: number): T

为组件添加高光效果。未设置时，默认无变化。与lightUpEffect方法相比，brightness以乘数方式调节亮度（值大于1可超过原始亮度），适合需要增强或减弱亮度的场景；lightUpEffect以程度方式调节亮度（值范围[0,1]，不能超过原始亮度），适合需要控制图像亮起程度的场景。当组件设置了BlendApplyType.OFFSCREEN的blendMode时，该接口可能无法截取到正确画面。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|为当前组件添加高光效果，入参为高光比例，值为1时没有效果，小于1时亮度变暗，小于或等于0为全黑，大于1时亮度增加，数值越大亮度越大，亮度大于或等于2时会变为全白。 取值范围：[0, +∞) 推荐取值范围：[0, 2] **说明：** 设置小于0的值时，按值为0处理。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## brightness^18+^

brightness(brightness: Optional<number>): T

为组件添加高光效果。未设置时，默认无变化。与[brightness](#brightness)相比，brightness参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|brightness|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|为当前组件添加高光效果，入参为高光比例，值为1时没有效果，小于1时亮度变暗，小于或等于0为全黑，大于1时亮度增加，数值越大亮度越大，亮度大于或等于2时会变为全白。 取值范围：[0, +∞) 推荐取值范围：[0, 2] **说明：** 设置小于0的值时，按值为0处理。 当brightness的值为undefined时，恢复为亮度为1的高光效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## saturate

saturate(value: number): T

为组件添加饱和度效果。未设置时，默认无变化。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:---------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|为当前组件添加饱和度效果，饱和度为颜色中的含色成分和消色成分（灰）的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大，小于1时消色成分越大，饱和度越小。 取值范围：[0, +∞) 推荐取值范围：[0, 50) **说明：** 设置小于0的值时，按值为0处理。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## saturate^18+^

saturate(saturate: Optional<number>): T

为组件添加饱和度效果。未设置时，默认无变化。与[saturate](#saturate)相比，saturate参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|saturate|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|为当前组件添加饱和度效果，饱和度为颜色中的含色成分和消色成分（灰）的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大，小于1时消色成分越大，饱和度越小。 取值范围：[0, +∞) 推荐取值范围：[0, 50) **说明：** 设置小于0的值时，按值为0处理。 当saturate的值为undefined时，恢复为饱和度为1的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## contrast

contrast(value: number): T

为组件添加对比度效果。未设置时，默认无变化。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:---------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|为当前组件添加对比度效果，入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。 取值范围：[0, +∞) 推荐取值范围：[0, 10) **说明：** 设置小于0的值时，按值为0处理。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## contrast^18+^

contrast(contrast: Optional<number>): T

为组件添加对比度效果。未设置时，默认无变化。与[contrast](#contrast)相比，contrast参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|contrast|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|为当前组件添加对比度效果，入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。 取值范围：[0, +∞) 推荐取值范围：[0, 10) **说明：** 设置小于0的值时，按值为0处理。 当contrast的值为undefined时，恢复为对比度为1的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## invert

invert(value: number | InvertOptions): T

反转输入的图像。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:--------------------------------------------------|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|value|number | [InvertOptions](#invertoptions11对象说明)^11+^|是|反转输入的图像。 入参对象为number时，入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。 取值范围：[0, 1]。 设置小于0的值时，按值为0处理。设置大于1的值时，按值为1处理。 入参对象为 InvertOptions时，对比背景颜色灰度值和阈值区间，背景颜色灰度值小于阈值区间时反色取high值，当背景颜色灰度值大于阈值区间时反色取low值，背景颜色灰度值在阈值区间内取值由high线性渐变到low。 **说明：** number和InvertOptions两种形式的入参对应不同的反转效果。两种类型的入参切换时，不会清除之前已设置的反转效果，两种反转效果会同时存在，建议始终使用同一种形式的入参。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## invert^18+^

invert(options: Optional<number | InvertOptions>): T

反转输入的图像。与[invert](#invert)相比，options参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|options|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number | [InvertOptions](#invertoptions11对象说明)>|是|反转输入的图像。 入参对象为number时，入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。 取值范围：[0, 1]。 设置小于0的值时，按值为0处理。设置大于1的值时，按值为1处理。 入参对象为 InvertOptions时，对比背景颜色灰度值和阈值区间，背景颜色灰度值小于阈值区间时反色取high值，当背景颜色灰度值大于阈值区间时反色取low值，背景颜色灰度值在阈值区间内取值由high线性渐变到low。 当options的值为undefined时，恢复为图像无变化的效果。 **说明：** number和InvertOptions两种形式的入参对应不同的反转效果。两种类型的入参切换时，不会清除之前已设置的反转效果，两种反转效果会同时存在，建议始终使用同一种形式的入参。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## sepia

sepia(value: number): T

将图像转换为深褐色。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:---------------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|将图像转换为深褐色，降低色彩度，产生温暖复古的图像风格。入参为褐色滤镜强度，值为1则完全是深褐色的，值小于等于0则图像无变化，值大于1会进一步放大色彩偏移比例，图像整体会变得更亮且色彩更加偏黄/偏红，但不属于标准sepia效果。 取值范围：[0, +∞)，推荐取值范围：(0, 1]。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## sepia^18+^

sepia(sepia: Optional<number>): T

将图像转换为深褐色。与[sepia](#sepia)相比，sepia参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|sepia|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|将图像转换为深褐色，降低色彩度，产生温暖复古的图像风格。入参为褐色滤镜强度，值为1则完全是深褐色的，值小于等于0则图像无变化，值大于1会进一步放大色彩偏移比例，图像整体会变得更亮且色彩更加偏黄/偏红，但不属于标准sepia效果。 取值范围：[0, +∞)，推荐取值范围：(0, 1]。 当sepia的值为undefined时，恢复为图像无变化的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## hueRotate

hueRotate(value: number | string): T

色相旋转效果。未设置时，默认无变化。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:--------------|:-|:--------------------------------------------------------------------------------------------------------------------------|
|value|number | string|是|色相旋转效果，输入参数为旋转角度。 单位：度（°） 取值范围：(-∞, +∞) **说明：** 色相旋转360度会显示原始颜色。先将色相旋转180度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和'90deg'效果一致。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## hueRotate^18+^

hueRotate(rotation: Optional<number | string>): T

色相旋转效果。未设置时，默认无变化。与[hueRotate](#huerotate)相比，rotation参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-------|:-----------------------------------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|rotation|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number | string>|是|色相旋转效果，输入参数为旋转角度。单位为度（°） 取值范围：(-∞, +∞) string需为数值字符串类型。 **说明：** 色相旋转360度会显示原始颜色。先将色相旋转180度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和'90deg'效果一致。 当rotation的值为undefined时，恢复为无色相旋转的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## colorBlend

colorBlend(value: Color | string | Resource): T

为组件添加颜色叠加效果。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:----------------------------------------------------------------------------------------------------------|
|value|[Color](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#color) | string | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource)|是|为当前组件添加颜色叠加效果，入参为叠加的颜色。取值可为Color类型、string类型或Resource类型，如使用Color.Green，或string类型如'0x000000'、'rgba(0,0,0,1)'。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## colorBlend^18+^

colorBlend(color: Optional<Color | string | Resource>): T

为组件添加颜色叠加效果。与[colorBlend](#colorblend)相比，color参数新增了对undefined类型的支持。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-----------------------------------------------------------------------------------------------------------------------|
|color|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<[Color](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#color) | string | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource)>|是|为当前组件添加颜色叠加效果，入参为叠加的颜色。取值可为Color枚举值、string类型（如'0x000000'、'rgba(0,0,0,1)'）或Resource资源引用。 当color的值为undefined时，恢复为无颜色叠加的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## linearGradientBlur^12+^

linearGradientBlur(value: number, options: LinearGradientBlurOptions): T

为组件添加内容线性渐变模糊效果。当组件设置了BlendApplyType.OFFSCREEN的blendMode时，该接口可能无法截取到正确画面。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:--------------------------------------------------------|:-|:--------------------------------------------------------------|
|value|number|是|模糊半径，模糊半径越大越模糊，为0时不模糊。 单位：px 取值范围：[0, 1000]|
|options|[LinearGradientBlurOptions](#lineargradientbluroptions12)|是|设置线性渐变模糊效果。 线性渐变参数，包含模糊程度和模糊位置数组fractionStops，及渐变模糊方向direction。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## linearGradientBlur^18+^

linearGradientBlur(blurRadius: Optional<number>, options: Optional<LinearGradientBlurOptions>): T

为组件添加内容线性渐变模糊效果。与[linearGradientBlur^12+^](#lineargradientblur12)相比，新增了对undefined类型的支持。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:---------------------------------------------------------------------------------------------------|
|blurRadius|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|模糊半径，模糊半径越大越模糊，为0时不模糊。 单位：px 取值范围：[0, 1000] 当blurRadius的值为undefined时，恢复为渐变模糊为0的效果。|
|options|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<[LinearGradientBlurOptions](#lineargradientbluroptions12)>|是|设置线性渐变模糊效果。 线性渐变参数，包含模糊程度和模糊位置数组fractionStops，及渐变模糊方向direction。 当options的值为undefined时，恢复为无线性渐变模糊的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## renderGroup^10+^

renderGroup(value: boolean): T

设置是否组成节点组。节点组表示当前组件和子组件组成的子树先在离屏画布中渲染，再与父组件融合绘制。设置为节点组后，系统会缓存绘制结果，提升性能。与[freeze](#freeze12)方法相比，renderGroup允许组件属性继续更新（但频繁更新会导致缓存失效），适合需要动态更新且希望缓存优化的场景；freeze完全停止内部属性更新，适合静态内容的稳定缓存优化。但如果节点组内的组件频繁更新，缓存失效，可能导致性能下降。此外，设置为节点组后，当前组件的不透明度不为1时，绘制效果可能有差异。

不设置该属性时，默认不组成节点组。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:------|:-|:----------------------------------------------------------------------------------|
|value|boolean|是|设置当前组件和子组件是否组成节点组。 false表示不组成节点组，不进行离屏渲染直接绘制。 true表示当前组件和子组件组成节点组，进行离屏渲染后再与父组件融合绘制。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## renderGroup^18+^

renderGroup(isGroup: Optional<boolean>): T

设置是否组成节点组。节点组表示当前组件和子组件组成的子树先在离屏画布中渲染，再与父组件融合绘制。设置为节点组后，系统会缓存绘制结果，提升性能。但如果节点组内的组件频繁更新，缓存失效，可能导致性能下降。此外，设置为节点组后，当前组件的不透明度不为1时，绘制效果可能有差异。
> 说明
>
> 与[freeze](#freeze12)不同，renderGroup在缓存绘制结果后仍允许内部属性更新（更新时缓存失效），适用于组件需要动态更新的场景；freeze则完全停止内部属性更新，适用于组件内容稳定不需要更新的场景。

与[renderGroup^10+^](#rendergroup10)相比，isGroup参数新增了对undefined类型的支持。

不设置该属性时，默认不组成节点组。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:------|:---------------------------------------------------------------------------------------------------------------------------------------|:-|:--------------------------------------------------------------------------------------------------------------------|
|isGroup|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<boolean>|是|设置当前组件和子组件是否组成节点组。 false表示不组成节点组，不进行离屏渲染直接绘制。 true表示当前组件和子组件组成节点组，进行离屏渲染后再与父组件融合绘制。 当isGroup的值为undefined时，按照不组成节点组处理。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## blendMode^11+^

blendMode(value: BlendMode, type?: BlendApplyType): T

将当前控件的内容（包含子节点内容）与下方画布（可能为离屏画布）已有内容进行混合。

**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:--------------------------------------|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|value|[BlendMode](#blendmode11枚举说明)|是|混合模式。 默认值：BlendMode.NONE **说明：** 混合模式设置为BlendMode.NONE时，blend效果实际为默认的BlendMode.SRC_OVER，且BlendApplyType不生效。|
|type|[BlendApplyType](#blendapplytype11枚举说明)|否|blendMode实现方式是否离屏。 默认值：BlendApplyType.FAST **说明：** 1. 设置BlendApplyType.FAST时，不离屏。 2. 设置BlendApplyType.OFFSCREEN时，会创建当前组件大小的离屏画布，再将当前组件（含子组件）的内容绘制到离屏画布上，再用指定的混合模式与下方画布已有内容进行混合。使用该实现方式时，将导致[linearGradientBlur^12+^](#lineargradientblur12)、[backgroundEffect](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundeffect11)、[brightness](#brightness)、[blur](#blur)等需要截屏的接口无法截取到正确的画面。 3. 混合模式设置为BlendMode.NONE时，BlendApplyType不生效。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## blendMode^18+^

blendMode(mode: Optional<BlendMode>, type?: BlendApplyType): T

将当前控件的内容（包含子节点内容）与下方画布（可能为离屏画布）已有内容进行混合。与[blendMode^11+^](#blendmode11)相比，mode参数新增了对undefined类型的支持。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---|:-------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|mode|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<[BlendMode](#blendmode11枚举说明)>|是|混合模式。 默认值：BlendMode.NONE 当mode的值为undefined时，恢复为内容不进行混合的效果。 **说明：** 混合模式设置为BlendMode.NONE时，blend效果实际为默认的BlendMode.SRC_OVER，且BlendApplyType不生效。|
|type|[BlendApplyType](#blendapplytype11枚举说明)|否|blendMode实现方式是否离屏。 默认值：BlendApplyType.FAST **说明：** 1. 设置BlendApplyType.FAST时，不离屏。 2. 设置BlendApplyType.OFFSCREEN时，会创建当前组件大小的离屏画布，再将当前组件（含子组件）的内容绘制到离屏画布上，再用指定的混合模式与下方画布已有内容进行混合。使用该实现方式时，将导致[linearGradientBlur^12+^](#lineargradientblur12)、[backgroundEffect](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundeffect11)、[brightness](#brightness)、[blur](#blur)等需要截屏的接口无法截取到正确的画面。 3. 混合模式设置为BlendMode.NONE时，BlendApplyType不生效。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## BlendApplyType^11+^枚举说明

指示如何将指定的混合模式应用于视图的内容。

**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|值|说明|
|:--------|:-|:---------------------------|
|FAST|0|在目标图像上按顺序混合视图的内容。|
|OFFSCREEN|1|将此组件和子组件内容绘制到离屏画布上，然后整体进行混合。|

## useShadowBatching^11+^

useShadowBatching(value: boolean): T

控件内部子节点的阴影是否进行同层绘制，控制同层元素阴影重叠效果。需配合[shadow](#shadow)方法使用，当子节点已通过shadow()设置阴影时，useShadowBatching可控制这些阴影是否进行同层绘制。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:------|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|value|boolean|是|控件内部子节点的阴影是否进行同层绘制。 默认值：false true：控件内部子节点的阴影进行同层绘制，子节点的阴影不会产生重叠覆盖效果。 false：控件内部子节点的阴影不进行同层绘制，子节点的阴影重叠区域有覆盖效果。 **说明：** 1. 默认不开启，如果子节点的阴影半径较大，阴影有重叠区域，后绘制的子节点阴影会覆盖在之前绘制的子节点阴影之上。 当开启时，子节点的阴影将同时绘制，不会产生覆盖效果。 2. 不推荐useShadowBatching嵌套使用，如果嵌套使用，只会对当前的子节点生效，无法递推。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## useShadowBatching^18+^

useShadowBatching(use: Optional<boolean>): T

控件内部子节点的阴影是否进行同层绘制，同层绘制时子节点阴影不会产生重叠覆盖效果。需配合[shadow](#shadow)方法使用，当子节点设置了shadow效果时，useShadowBatching可控制子节点阴影进行同层绘制，实现同层阴影不重叠效果。调用顺序：先在子节点上设置shadow属性，再在父容器上设置useShadowBatching(true)。与[useShadowBatching^11+^](#useshadowbatching11)相比，use参数新增了对undefined类型的支持。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:--|:---------------------------------------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|use|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<boolean>|是|控件内部子节点的阴影是否进行同层绘制。 默认值：false true：控件内部子节点的阴影进行同层绘制，子节点的阴影不会产生重叠覆盖效果。 false：控件内部子节点的阴影不进行同层绘制，子节点的阴影重叠区域有覆盖效果。 **说明：** 1. 默认不开启，如果子节点的阴影半径较大，阴影有重叠区域，后绘制的子节点阴影会覆盖在之前绘制的子节点阴影之上。 当开启时，子节点的阴影将同时绘制，不会产生覆盖效果。 2. 不推荐useShadowBatching嵌套使用，如果嵌套使用，只会对当前的子节点生效，无法递推。 当use的值为undefined时，恢复为不使用元素阴影重叠的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## sphericalEffect^12+^

sphericalEffect(value: number): T

设置组件的图像球面化程度。球面化效果将组件内容映射到球面曲面上，使图像呈现出类似球体的立体视觉效果，值越大球面弧度越高、立体感越强。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|设置组件的图像球面化程度。球面化效果将组件内容映射到球面曲面上，使图像呈现出类似球体的立体视觉效果，值越大球面弧度越高、立体感越强。 取值范围：[0,1]。 **说明：** 1. 如果value等于0则图像保持原样，如果value等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。 value < 0或者value > 1为异常情况，value < 0按0处理，value > 1按1处理。 2. 组件阴影和外描边不支持球面效果。 3. 设置value大于0时，组件冻屏并且把组件内容绘制到透明离屏buffer上，如果要更新组件属性则需要把value设置为0。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## sphericalEffect^18+^

sphericalEffect(effect: Optional<number>): T

设置组件的图像球面化程度。球面化效果将组件内容映射到球面曲面上，使图像呈现出类似球体的立体视觉效果，值越大球面弧度越高、立体感越强。与[sphericalEffect^12+^](#sphericaleffect12)相比，effect参数新增了对undefined类型的支持。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-----|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|effect|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|设置组件的图像球面化程度。球面化效果将组件内容映射到球面曲面上，使图像呈现出类似球体的立体视觉效果，值越大球面弧度越高、立体感越强。 取值范围：[0,1]。 **说明：** 1. 如果effect等于0则图像保持原样，如果effect等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。 effect < 0或者effect > 1为异常情况，effect < 0按0处理，effect > 1按1处理。 2. 组件阴影和外描边不支持球面效果。 3. 设置effect大于0时，组件冻屏并且把组件内容绘制到透明离屏buffer上，如果要更新组件属性则需要把effect设置为0。 当effect的值为undefined时，恢复为图像球面化程度为0的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## lightUpEffect^12+^

lightUpEffect(value: number): T

设置组件图像亮起程度。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:--------------------------------------------------------------------------------------------------------------------------------------|
|value|number|是|设置组件图像亮起程度。 取值范围：[0,1]。 如果value等于0则图像为全黑，如果value等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。value < 0 或者 value > 1为异常情况，value < 0按0处理，value > 1按1处理。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## lightUpEffect^18+^

lightUpEffect(degree: Optional<number>): T

设置组件图像亮起程度。与[lightUpEffect^12+^](#lightupeffect12)相比，degree参数新增了对undefined类型的支持。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-----|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|degree|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<number>|是|设置组件图像亮起程度。 取值范围：[0,1]。 如果degree等于0则图像为全黑，如果degree等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。degree < 0 或者 degree > 1为异常情况，degree < 0按0处理，degree > 1按1处理。 当degree的值为undefined时，恢复为亮起为1的效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## pixelStretchEffect^12+^

pixelStretchEffect(options: PixelStretchEffectOptions): T

设置组件的图像边缘像素扩展距离。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:--------------------------------------------------------|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|options|[PixelStretchEffectOptions](#pixelstretcheffectoptions10)|是|设置组件的图像边缘像素扩展距离。 参数options包括上下左右四个方向的边缘像素扩展距离。 **说明：** 1. 如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。 2. 如果距离为负值，表示内缩，但是最终图像大小不变。 内缩方式： 图像根据options的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。 图像用边缘像素扩展到原来大小。 3. 对options的输入约束： 上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。 所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。 所有异常情况下，显示为{0, 0, 0, 0}效果，即跟原图保持一致。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## pixelStretchEffect^18+^

pixelStretchEffect(options: Optional<PixelStretchEffectOptions>): T

设置组件的图像边缘像素扩展距离。与[pixelStretchEffect^12+^](#pixelstretcheffect12)相比，options参数新增了对undefined类型的支持。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|options|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<[PixelStretchEffectOptions](#pixelstretcheffectoptions10)>|是|设置组件的图像边缘像素扩展距离。 参数options包括上下左右四个方向的边缘像素扩展距离。 **说明：** 1. 如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。 2. 如果距离为负值，表示内缩，但是最终图像大小不变。 内缩方式： 图像根据options的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。 图像用边缘像素扩展到原来大小。 3. 对options的输入约束： 上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。 所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。 所有异常情况下，显示为{0, 0, 0, 0}效果，即跟原图保持一致。 当options的值为undefined时，恢复为无像素扩展效果。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## PixelStretchEffectOptions^10+^

像素扩展属性集合，用于描述像素扩展的信息。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|类型|只读|可选|说明|
|:-----|:------------------------------------------------------------------------------------------|:-|:-|:-------------------------------------------------------------------------------|
|left|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|组件图像左边沿像素扩展距离。需与right、top、bottom方向保持一致：四个方向的扩展统一为非正值或者非负值，不支持百分比和具体值混用。 默认值：0vp|
|right|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|组件图像右边沿像素扩展距离。需与left、top、bottom方向保持一致：四个方向的扩展统一为非正值或者非负值，不支持百分比和具体值混用。 默认值：0vp|
|top|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|组件图像上边沿像素扩展距离。需与left、right、bottom方向保持一致：四个方向的扩展统一为非正值或者非负值，不支持百分比和具体值混用。 默认值：0vp|
|bottom|[Length](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#length)|否|是|组件图像下边沿像素扩展距离。需与left、right、top方向保持一致：四个方向的扩展统一为非正值或者非负值，不支持百分比和具体值混用。 默认值：0vp|

## systemBarEffect^12+^

systemBarEffect(): T

根据背景颜色自动判断反色区域和反色程度，并叠加模糊效果。智能反色基于背景内容的颜色与亮度特征自动确定反色策略，使组件在不同背景下保持内容可视性；模糊效果对背景内容进行模糊处理，增强系统栏与背景的视觉融合效果。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## ShadowType^10+^枚举说明

阴影类型。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|值|说明|
|:----|:-|:-------------------|
|COLOR|0|颜色阴影，基于指定颜色值绘制阴影效果。|
|BLUR|1|模糊阴影，基于组件内容模糊绘制阴影效果。|

## ShadowOptions对象说明

阴影属性集合，用于设置阴影的模糊半径、阴影的颜色、X轴和Y轴的偏移量。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|类型|只读|可选|说明|
|:--------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|radius|number | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource)|否|否|阴影模糊半径。 取值范围：[0, +∞)，API版本26.0.0开始取值范围变更为(-∞, +∞) 单位：px **说明：** API版本26.0.0之前，设置小于0的值时，按值为0处理，此时不绘制阴影；从API版本26.0.0开始，设置的值即为最终取值，值为0时仍绘制阴影，设置负数值时不绘制阴影。 如需使用vp单位的数值可用[vp2px](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#vp2px12)进行转换。 如果radius为Resource类型，则传入的值需为number类型。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。|
|type^10+^|[ShadowType](#shadowtype10枚举说明)|否|是|阴影类型。 默认值：COLOR **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **模型约束：** 此接口仅可在Stage模型下使用。|
|color|[Color](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#color) | string | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource) | [ColoringStrategy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#coloringstrategy10)^11+^|否|是|阴影的颜色。 默认为黑色。 **说明：** 从API version 11开始，该接口支持使用ColoringStrategy实现智能取色，智能取色功能不支持在ArkTS卡片、[textShadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textshadow10)中使用。 当前仅支持平均取色和主色取色，智能取色区域为shadow绘制区域。 支持使用'average'字符串触发智能平均取色模式，支持使用'primary'字符串触发智能主色模式。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。|
|offsetX|number | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource)|否|是|阴影的X轴偏移量。 默认值：0 单位：px **说明：** 如需使用vp单位的数值可用[vp2px](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#vp2px12)进行转换。 如果offsetX为Resource类型，则传入的值需为number类型。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。|
|offsetY|number | [Resource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-types#resource)|否|是|阴影的Y轴偏移量。 默认值：0 单位：px **说明：** 如需使用vp单位的数值可用[vp2px](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#vp2px12)进行转换。 如果offsetY为Resource类型，则传入的值需为number类型。 **元服务API：** 从API version 11开始，该接口支持在元服务中使用。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。|
|fill^11+^|boolean|否|是|阴影是否内部填充。true表示阴影在内部填充，false表示阴影在外部填充。 默认值：false。 **说明：** [textShadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#textshadow10)中该字段不生效。 **元服务API：** 从API version 12开始，该接口支持在元服务中使用。 **模型约束：** 此接口仅可在Stage模型下使用。|

## ShadowStyle^10+^枚举说明

组件阴影效果。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|值|说明|
|:----------------|:-|:-----|
|OUTER_DEFAULT_XS|0|超小阴影。|
|OUTER_DEFAULT_SM|1|小阴影。|
|OUTER_DEFAULT_MD|2|中阴影。|
|OUTER_DEFAULT_LG|3|大阴影。|
|OUTER_FLOATING_SM|4|浮动小阴影。|
|OUTER_FLOATING_MD|5|浮动中阴影。|

## BlendMode^11+^枚举说明

混合模式。
> 说明
>
> blendMode枚举中，s表示源像素，d表示目标像素，sa表示源像素透明度，da表示目标像素透明度，r表示混合后像素，ra表示混合后像素透明度。

**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|值|说明|
|:----------|:-|:-------------------------------------------------------------------------------------------|
|NONE|0|将上层图像直接覆盖到下层图像上，不进行任何混合操作。|
|CLEAR|1|将源像素覆盖的目标像素清除为完全透明。|
|SRC|2|r = s，只显示源像素。|
|DST|3|r = d，只显示目标像素。|
|SRC_OVER|4|r = s + (1 - sa) * d，将源像素按照透明度进行混合，覆盖在目标像素上。|
|DST_OVER|5|r = d + (1 - da) * s，将目标像素按照透明度进行混合，覆盖在源像素上。|
|SRC_IN|6|r = s * da，只显示源像素中与目标像素重叠的部分。|
|DST_IN|7|r = d * sa，只显示目标像素中与源像素重叠的部分。|
|SRC_OUT|8|r = s * (1 - da)，只显示源像素中与目标像素不重叠的部分。|
|DST_OUT|9|r = d * (1 - sa)，只显示目标像素中与源像素不重叠的部分。|
|SRC_ATOP|10|r = s * da + d * (1 - sa)，在源像素和目标像素重叠的地方绘制源像素，在源像素和目标像素不重叠的地方绘制目标像素。|
|DST_ATOP|11|r = d * sa + s * (1 - da)，在源像素和目标像素重叠的地方绘制目标像素，在源像素和目标像素不重叠的地方绘制源像素。|
|XOR|12|r = s * (1 - da) + d * (1 - sa)，在源像素和目标像素重叠的地方不显示像素，不重叠的地方显示源像素和目标像素。|
|PLUS|13|r = min(s + d, 1)，将源像素值与目标像素值相加，并将结果作为新的像素值。|
|MODULATE|14|r = s * d，将源像素与目标像素进行乘法运算，并将结果作为新的像素值。|
|SCREEN|15|r = s + d - s * d，将两个图像的像素值相加，然后减去它们的乘积来实现混合。|
|OVERLAY|16|根据目标像素来决定使用MULTIPLY混合模式还是SCREEN混合模式。|
|DARKEN|17|rc = s + d - max(s * da, d * sa), ra = kSrcOver，当两个颜色重叠时，较暗的颜色会覆盖较亮的颜色。|
|LIGHTEN|18|rc = s + d - min(s * da, d * sa), ra = kSrcOver，将源图像和目标图像中的像素进行比较，选取两者中较亮的像素作为最终的混合结果。|
|COLOR_DODGE|19|使目标像素变得更亮来反映源像素。|
|COLOR_BURN|20|使目标像素变得更暗来反映源像素。|
|HARD_LIGHT|21|根据源像素的值来决定目标像素变得更亮或者更暗。根据源像素来决定使用MULTIPLY混合模式还是SCREEN混合模式。|
|SOFT_LIGHT|22|根据源像素来决定使用LIGHTEN混合模式还是DARKEN混合模式。|
|DIFFERENCE|23|rc = s + d - 2 * (min(s * da, d * sa)), ra = kSrcOver，对比源像素和目标像素，亮度更高的像素减去亮度更低的像素，产生高对比度的效果。|
|EXCLUSION|24|rc = s + d - 2 * (s * d), ra = kSrcOver，对比源像素和目标像素，亮度更高的像素减去亮度更低的像素，产生柔和的效果。|
|MULTIPLY|25|r = s * (1 - da) + d * (1 - sa) + s * d，将源图像与目标图像进行乘法混合，得到一张新的图像。|
|HUE|26|保留源图像的亮度和饱和度，但会使用目标图像的色调来替换源图像的色调。|
|SATURATION|27|保留目标像素的亮度和色调，但会使用源像素的饱和度来替换目标像素的饱和度。|
|COLOR|28|保留源像素的饱和度和色调，但会使用目标像素的亮度来替换源像素的亮度。|
|LUMINOSITY|29|保留目标像素的色调和饱和度，但会用源像素的亮度替换目标像素的亮度。|

## LinearGradientBlurOptions^12+^

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|类型|只读|可选|说明|
|:------------|:-------------------------------------------------------------------------------------------------------------------------|:-|:-|:------------------------------------------------------------------------------------------------------------|
|fractionStops|[FractionStop](#fractionstop12)[]|否|否|数组中保存的每一个二元数组（取值0-1，小于0则为0，大于1则为1）表示[模糊分数, 模糊位置]；模糊位置需严格递增，开发者传入的数据不符合规范会记录日志，渐变模糊数组中二元数组个数必须大于等于2，否则渐变模糊不生效。|
|direction|[GradientDirection](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#gradientdirection)|否|否|渐变模糊方向。 默认值： GradientDirection.Bottom|

## FractionStop^12+^

type FractionStop = [ number, number ]

定义模糊段。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|类型|说明|
|:-----------------|:-------------------------------------------------------------------------------------------|
|[ number, number ]|第一个number表示分数，值1表示不透明，0表示完全透明。 取值范围：[0, 1] 第二个number表示停止位置，值1表示区域结束位置，0表示区域开始位置。 取值范围：[0, 1]|

## InvertOptions^11+^对象说明

前景智能取反色。基于灰度阈值区间决定反色取值，参见[invert](#invert)中的详细机制说明。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|类型|只读|可选|说明|
|:-------------|:-----|:-|:-|:------------------------------------------------------------------------------------------------------------------|
|low|number|否|否|背景颜色灰度值大于阈值区间时的取值。 取值范围：[0, 1]。设置小于0的值时，按值为0处理。设置大于1的值时，按值为1处理。|
|high|number|否|否|背景颜色灰度值小于阈值区间时的取值。 取值范围：[0, 1]。设置小于0的值时，按值为0处理。设置大于1的值时，按值为1处理。|
|threshold|number|否|否|灰度阈值。与thresholdRange配合使用，灰度阈值上下偏移thresholdRange构成阈值区间。 取值范围：[0, 1]|
|thresholdRange|number|否|否|阈值范围。 取值范围：[0, 1]。设置小于0的值时，按值为0处理；设置大于1的值时，按值为1处理。 **说明：** 灰度阈值上下偏移thresholdRange构成阈值区间，背景颜色灰度值在区间内取值由high线性渐变到low。|

## BackgroundImageOptions^18+^

定义背景图选项。
> 说明
>
> 背景图片的同步加载可能会带来潜在性能问题，详情可见[Image](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-image#image-1)中说明。

**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|类型|只读|可选|说明|
|:-------|:-------------------------------------------------------------------------------------------------------------|:-|:-|:-------------------------------------------------------------------------|
|syncLoad|boolean|否|是|是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。 默认值：false false：异步加载图片。 true：同步加载图片。|
|repeat|[ImageRepeat](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#imagerepeat)|否|是|设置背景图片的重复样式。默认值为ImageRepeat.NoRepeat。|

## freeze^12+^

freeze(value: boolean): T

设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当freeze设置为true时，组件属性更新将被冻结；若需恢复属性更新，需先将freeze设置为false。
> 说明
>
> 从API version 20开始，该接口支持在[attributeModifier](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-attribute-modifier#attributemodifier)中调用。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:------|:-|:----------------------------------------------------------------------------------------------------------------|
|value|boolean|是|设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当前控件的不透明度不为1时绘制效果可能有差异。 默认值：false true时离屏渲染绘制后重复绘制缓存，false时离屏渲染绘制后不重复绘制缓存。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## freeze^18+^

freeze(freeze: Optional<boolean>): T

设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当freeze设置为true时，组件属性更新将被冻结；若需恢复属性更新，需先将freeze设置为false。与[freeze](#freeze12)相比，freeze参数新增了对undefined类型的支持。
> 说明
>
> 从API version 20开始，该接口支持在[attributeModifier](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-attribute-modifier#attributemodifier)中调用。

**元服务API：** 从API version 18开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-----|:---------------------------------------------------------------------------------------------------------------------------------------|:-|:---------------------------------------------------------------------------------------------------------------------------------------------|
|freeze|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<boolean>|是|设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当前控件的不透明度不为1时绘制效果可能有差异。 默认值：false true时离屏渲染绘制后重复绘制缓存，false时离屏渲染绘制后不重复绘制缓存。 当freeze的值为undefined时，维持之前取值。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## systemMaterial

systemMaterial(material: SystemUiMaterial | undefined): T

设置组件的系统材质。不同系统材质对应不同的属性影响效果，该接口可以影响背景色[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)、边框颜色[borderColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-border#bordercolor)、边框宽度[borderWidth](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-border#borderwidth)、阴影[shadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#shadow)、材质层滤镜[materialFilter](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-filter-effect#materialfilter23)效果，影响的属性与设备材质等级相关，参考[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)。[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)只有在支持沉浸式材质的设备上设置才有效果，在不支持沉浸式材质的设备上可设置但无效果，可通过[isImmersiveMaterialSupported](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#uimaterialisimmersivematerialsupported)判断设备是否支持沉浸式材质。使用示例请参考[示例1（设置沉浸式系统材质）](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#示例1设置沉浸式系统材质)。
> 说明
>
> * 通过该属性设置组件的系统材质时，仅在Navigation或NavDestination的标题栏，或横向Tabs中barPosition为BarPosition.End的底部TabBar中生效。
>
> * [ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)只有在支持沉浸式材质的设备上设置才有效果，在不支持沉浸式材质的设备上可设置但无效果，可通过[isImmersiveMaterialSupported](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#uimaterialisimmersivematerialsupported)判断设备是否支持沉浸式材质。在不支持沉浸式材质的设备上，设置ImmersiveMaterial后，组件的样式仍由已设置的通用属性决定，ImmersiveMaterial不会覆盖任何通用属性。
>
> * 在同时设置了材质影响的通用属性发生冲突时，除阴影外，总体原则为后设置的生效，对于阴影属性取决于[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)的applyShadow参数。
>
>   * 先设置[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)属性后设置[systemMaterial](#systemmaterial)属性：backgroundColor属性被覆盖。在支持沉浸式材质的高算力和中算力设备上，背景色属性被清空为透明色；在支持沉浸式材质的低算力设备上，材质自带的背景色效果覆盖了先设置的backgroundColor属性。
>   * 先设置[systemMaterial](#systemmaterial)属性后设置[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)属性：systemMaterial属性影响的背景色效果被覆盖，背景色属性生效为后设置的backgroundColor属性的颜色。
> * 对于所有设备算力档位均需要材质颜色的场景，可以通过[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)的materialColor参数承载，不再设置[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)属性。
>
> * 该样式仅限当前组件使用，不会影响或继承至子组件。

**起始版本：** 26.0.0

**模型约束：** 此接口仅可在Stage模型下使用。

**卡片能力：** 从API版本26.0.0开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API版本26.0.0开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-------|:------------------------------------------------|:-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|material|[SystemUiMaterial](#systemuimaterial) | undefined|是|组件的系统材质对象。设置为undefined时恢复为无材质的效果，若同时设置了材质对象影响的通用属性，会恢复至对应通用属性设置的值，冲突的属性由材质对象决定，参考[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## SystemUiMaterial

type SystemUiMaterial = import('../api/@ohos.arkui.uiMaterial').default.Material

系统材质对象基类。

**起始版本：** 26.0.0

**模型约束：** 此接口仅可在Stage模型下使用。

**卡片能力：** 从API版本26.0.0开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API版本26.0.0开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|类型|说明|
|:-----------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
|import('../api/@ohos.arkui.uiMaterial').default.[Material](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#material)|系统材质对象基类。|

## doubleSided

doubleSided(value: Optional<boolean>): T

是否绘制组件的双面。

**起始版本：** 26.0.0

**模型约束：** 此接口仅可在Stage模型下使用。

**卡片能力：** 从API版本26.0.0开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API版本26.0.0开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:---------------------------------------------------------------------------------------------------------------------------------------|:-|:-----------------------------------------------------------------------------------------------------------|
|value|[Optional](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-custom-property#optionalt)<boolean>|是|是否绘制组件的双面。 设置为true表示组件的正面和背面都是可见的。 设置为false表示组件的正面是可见的，旋转时组件的背面是不可见的。 设置为undefined时效果和设置为true时保持一致，默认开启双面绘制。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## 示例

### 示例1（设置图片不同属性效果）

设置图片的效果，包括阴影、灰度、高光、饱和度、对比度、图像反转、叠色、色相旋转等。

```ts
// xxx.ets
@Entry
@Component
struct ImageEffectsExample {
  build() {
    Column({ space: 5 }) {
      // 添加阴影效果，图片效果不变
      Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image'))
        .width('90%')
        .height(30)
        .shadow({
          radius: 10,
          color: Color.Green,
          offsetX: 20,
          offsetY: 20
        })

      // 添加内部阴影效果
      Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image'))
        .width('90%')
        .height(30)
        .shadow({
          radius: 5,
          color: Color.Green,
          offsetX: 20,
          offsetY: 20,
          fill: true
        }).opacity(0.5)

      // 灰度效果0~1，越接近1，灰度越明显
      Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).grayscale(0.3)
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).grayscale(0.8)

      // 高光效果，1为正常图片，<1变暗，>1亮度增大
      Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).brightness(1.2)

      // 饱和度，原图为1
      Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).saturate(2.0)
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).saturate(0.7)

      // 对比度，1为原图，>1值越大越清晰，<1值越小越模糊
      Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).contrast(2.0)
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).contrast(0.8)

      // 图像反转比例
      Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).invert(0.2)
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).invert(0.8)

      // 叠色添加
      Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Green)
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Blue)

      // 深褐色
      Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).sepia(0.8)

      // 色相旋转
      Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // $r("app.media.image")需要替换为开发者所需的图像资源文件。
      Image($r('app.media.image')).width('90%').height(30).hueRotate(90)
    }.width('100%').margin({ top: 5 })
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d8/v3/w4rsCwlhSQ-sGg4lxLM_9A/zh-cn_image_0000002753296557.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=CD2F5E5D90159625EBD0F43F9093E3B27B83BA3D319A0183EF90DF8118B25C42)

### 示例2（设置组件线性渐变模糊效果）

该示例主要演示通过[linearGradientBlur](#lineargradientblur12)设置组件的内容线性渐变模糊效果。

```ts
// xxx.ets
@Entry
@Component
struct LinearGradientBlurExample {
  // $r('app.media.testlinearGradientBlurOrigin')需要替换为开发者所需的资源文件。
  privateResource1: Resource = $r('app.media.testlinearGradientBlurOrigin')
  @State imageSrc: Resource = this.privateResource1

  build() {
    Column() {
      Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
        Row({ space: 5 }) {
          Image(this.imageSrc)
            .blur(0) // 设置图片模糊效果为不模糊
            .linearGradientBlur(60,
              { fractionStops: [[0, 0], [0, 0.33], [1, 0.66], [1, 1]], direction: GradientDirection.Bottom })
        }
      }
    }
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/84/v3/BQm-djiVRLSx7X_fBwn8kg/zh-cn_image_0000002753456475.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=05E02886F18D60A8B3BE9533F6CBDCB7BBF7EE73077B19A5FFA13DCA2C3DB9D3)

### 示例3（设置离屏渲染效果）

该示例主要演示通过[renderGroup](#rendergroup10)来设置组件是否先整体离屏渲染绘制后，再与父组件融合绘制。

```ts
// xxx.ets
@Component
struct RenderGroupChildComponent {
  @Prop renderGroupValue: boolean;

  build() {
    Row() {
      Row() {
        Row()
          .backgroundColor(Color.Black)
          .width(100)
          .height(100)
          .opacity(1)
      }
      .backgroundColor(Color.White)
      .width(150)
      .height(150)
      .justifyContent(FlexAlign.Center)
      .opacity(0.6)
      .renderGroup(this.renderGroupValue)
    }
    .backgroundColor(Color.Black)
    .width(200)
    .height(200)
    .justifyContent(FlexAlign.Center)
    .opacity(1)
  }
}

@Entry
@Component
struct RenderGroupExample {
  build() {
    Column() {
      RenderGroupChildComponent({ renderGroupValue: true })
        .margin(20)
      RenderGroupChildComponent({ renderGroupValue: false })
        .margin(20)
    }
    .width("100%")
    .height("100%")
    .alignItems(HorizontalAlign.Center)
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d9/v3/QSTJC-fLTCOTLrNf3gqjEw/zh-cn_image_0000002723856710.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=C45805BCCE4B6587F3003B00CFA7BB502F229025B20951354A6ADCCB2ADFF2F8)

### 示例4（当前组件内容与下方画布内容混合）

该示例主要演示通过[blendMode](#blendmode11)将当前组件内容与下方画布内容混合。

```ts
// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Text("blendMode")
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .fontColor('#ffff0101')
      Row() {
        Circle()
          .width(200)
          .height(200)
          .fill(Color.Green)
          .position({ x: 50, y: 50 })
        Circle()
          .width(200)
          .height(200)
          .fill(Color.Blue)
          .position({ x: 150, y: 50 })
      }
      .blendMode(BlendMode.OVERLAY, BlendApplyType.OFFSCREEN)
      .alignItems(VerticalAlign.Center)
      .height(300)
      .width('100%')
    }
    .height('100%')
    .width('100%')
    // $r("app.media.image")需要替换为开发者所需的图像资源文件。
    .backgroundImage($r('app.media.image'))
    .backgroundImageSize(ImageSize.Cover)
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6f/v3/I7gD7tCmQUe_cge_mF4zoQ/zh-cn_image_0000002723696792.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=BE75218CEDE04629F5D169EDD82F07AD6620230998161716E73855488D13AEDD)

### 示例5（前景智能取反色）

该示例主要通过[InvertOptions](#invertoptions11对象说明)来实现前景智能取反色。

```ts
// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column()
      Stack() {
        // $r("app.media.r")需要替换为开发者所需的图像资源文件。
        // 该示例中图片为从左到右，颜色由浅到深。
        Image($r('app.media.r')).width('100%')
        Column() {
          Column().width("100%").height(30).invert({
            low: 0,
            high: 1,
            threshold: 0.5,
            thresholdRange: 0.2
          })
          Column().width("100%").height(30).invert({
            low: 0.2,
            high: 0.5,
            threshold: 0.3,
            thresholdRange: 0.2
          })
        }
      }
      .width('100%')
      .height('100%')
    }
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/10/v3/vf7bG3IcTN-O-lvosKnAgw/zh-cn_image_0000002753296559.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=D8528745102E8E4043106607E90E1B7DB4C742939FB7D9AF152443C0D532D315)

### 示例6（设置同层阴影不重叠效果）

该示例主要通过[useShadowBatching](#useshadowbatching11)搭配[shadow](#shadow)实现同层阴影不重叠效果。

```ts
// xxx.ets
@Entry
@Component
struct UseShadowBatchingExample {
  build() {
    Column() {
      Column({ space: 10 }) {
        Stack() {

        }
        .width('90%')
        .height(50)
        .margin({ top: 5 })
        .backgroundColor(0xFFE4C4)
        .shadow({
          radius: 120,
          color: Color.Green,
          offsetX: 0,
          offsetY: 0
        })
        .align(Alignment.TopStart)
        .shadow({
          radius: 120,
          color: Color.Green,
          offsetX: 0,
          offsetY: 0
        })

        Stack() {

        }
        .width('90%')
        .height(50)
        .margin({ top: 5 })
        .backgroundColor(0xFFE4C4)
        .align(Alignment.TopStart)
        .shadow({
          radius: 120,
          color: Color.Red,
          offsetX: 0,
          offsetY: 0
        })
        .width('90%')
        .backgroundColor(Color.White)

        Column() {
          Text()
            .fontWeight(FontWeight.Bold)
            .fontSize(20)
            .fontColor(Color.White)
        }
        .justifyContent(FlexAlign.Center)
        .width(150)
        .height(150)
        .borderRadius(10)
        .backgroundColor(0xf56c6c)
        .shadow({
          radius: 300,
          color: Color.Yellow,
          offsetX: 0,
          offsetY: 0
        })

        Column() {
          Text()
            .fontWeight(FontWeight.Bold)
            .fontSize(20)
            .fontColor(Color.White)
        }
        .justifyContent(FlexAlign.Center)
        .width(150)
        .height(150)
        .backgroundColor(0x67C23A)
        .borderRadius(10)
        .translate({ y: -50 })
        .shadow({
          radius: 220,
          color: Color.Blue,
          offsetX: 0,
          offsetY: 0
        })
      }
      .useShadowBatching(true)
    }
    .width('100%').margin({ top: 5 })
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/53/v3/QY1wA0pcST2BroMTGi9bTw/zh-cn_image_0000002753456477.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=D0ED7719ABC939757D18F07406DA934405950141B37F1D3413DB0445E9C8905F)

### 示例7（设置组件图像球面效果）

该示例主要演示通过[sphericalEffect](#sphericaleffect12)设置组件的图像球面效果。

```ts
// xxx.ets
@Entry
@Component
struct SphericalEffectExample {
  build() {
    Stack() {
      TextInput({ placeholder: "请输入变化范围百分比（[0%,100%]）" })
        .width('50%')
        .height(35)
        .type(InputType.Number)
        .enterKeyType(EnterKeyType.Done)
        .caretColor(Color.Red)
        .placeholderColor(Color.Blue)
        .placeholderFont({
          size: 20,
          style: FontStyle.Italic,
          weight: FontWeight.Bold
        })
        .sphericalEffect(0.5)
    }.alignContent(Alignment.Center).width("100%").height("100%")
  }
}
```

效果图如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7b/v3/qFQnRTQ8TgGCeVD0wFNXLg/zh-cn_image_0000002723856712.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=0F3400ACC61E9D2BCCF1588373806B6DFD4969F986BF5D3EAD3B54B42E3EFB29)

去掉sphericalEffect的设置，效果如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0/v3/NSBmGUGiRrewGmDjphEBDQ/zh-cn_image_0000002723696794.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=F351979B2991F244F401DD208183EE4F4D14CB6A8DFCADF63B6FE546F6672B93)

### 示例8（设置组件图像渐亮效果）

该示例主要演示通过[lightUpEffect](#lightupeffect12)设置组件的图像渐亮效果。

```ts
// xxx.ets
@Entry
@Component
struct LightUpExample {
  build() {
    Stack() {
      Text('This is the text content with letterSpacing 0.')
        .letterSpacing(0)
        .fontSize(12)
        .border({ width: 1 })
        .padding(10)
        .width('50%')
        .lightUpEffect(0.6)
    }.alignContent(Alignment.Center).width("100%").height("100%")
  }
}
```

效果图如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/fa/v3/Z9LNR3TMQLy38bLb6JUQ-g/zh-cn_image_0000002753296561.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=098E005B0A0869262704570ABB0F1E8C6347B0FB116716517618BA7A5260954F)

修改lightUpEffect参数值为0.2：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0/v3/aEGkUON3Q5eR7O__gTcRmA/zh-cn_image_0000002753456479.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=06F2B62C926647D7F22BEE66BEE72C76D5191D746CC9C7DA55E7D8056D22E636)

去掉lightUpEffect的设置，效果如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f0/v3/EHaVcs7SR26RK3f3zF1R3A/zh-cn_image_0000002723856714.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=5C99E9DA2E1A2EFC0F0CEB62BABFE34AD0DAADC76C2C987D85B9FF225B754A55)

### 示例9（设置组件图像边缘像素扩展效果）

该示例主要演示通过[pixelStretchEffect](#pixelstretcheffect12)设置组件的图像边缘像素扩展效果。

```ts
// xxx.ets
@Entry
@Component
struct PixelStretchExample {
  build() {
    Stack() {
      Text('This is the text content with letterSpacing 0.')
        .letterSpacing(0)
        .fontSize(12)
        .border({ width: 1 })
        .padding(10)
        .clip(false)
        .width('50%')
        .pixelStretchEffect({
          top: 10,
          left: 10,
          right: 10,
          bottom: 10
        })
    }.alignContent(Alignment.Center).width("100%").height("100%")
  }
}
```

效果图如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b6/v3/WPRfq6nbQGyqqmi93ZSVUA/zh-cn_image_0000002723696796.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=0E1049E3F30C41434632846EE0F6ABC7A4799E92E337C9DB59280D9FA0FA2131)

去掉pixelStretchEffect的设置，原图效果如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b/v3/arrALXEwQd2d7jGeR1mpLA/zh-cn_image_0000002753296563.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=A22FFA1EEF6CDD0BB6EDA0F1B5B3FF0E7B999D7679762B4837CD7B176D06A894)

### 示例10（系统导航条智能反色）

该示例主要演示通过[systemBarEffect](#systembareffect12)来实现系统导航条智能反色。

```ts
// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Stack() {
        // $r("app.media.testImage")需要替换为开发者所需的图像资源文件。
        Image($r('app.media.testImage')).width('100%').height('100%')
        Column()
          .width(150)
          .height(10)
          .systemBarEffect()
          .border({ radius: 5 })
          .margin({ bottom: 80 })
      }.alignContent(Alignment.Center)
    }
  }
}
```

效果图如下：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/97/v3/4F6906dBTq2YoGzXSp4RXA/zh-cn_image_0000002753456481.png?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=73E771AEF36A2A2A3E0FD1B1D519A2B2F8DF0F5729863FB26A2A95E1DAB68D50)

### 示例11（设置组件是否双面绘制）

该示例主要演示通过[doubleSided](#doublesided)来设置组件是否双面绘制。

从API版本26.0.0开始，新增doubleSided方法。

```ts
// xxx.ets
@Entry
@Component
struct DoubleSided {
  @State angleY: number = 0;
  @State isAnimating: boolean = false;
  @State isDoubleSided: boolean = true;
  build() {
    Column({space: 30}) {
      Text('DoubleSided 背面剔除验证')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.White)
      Stack() {
        Stack() {
          Text('FRONT')
            .fontSize(32)
            .fontColor(Color.White)
        }
        .width(300)
        .height(300)
        .backgroundColor(Color.Blue)
        .border({ width: 2, color: Color.Gray })
        .doubleSided(this.isDoubleSided)
        .rotate({ x: 0, y: 1, z: 0, angle: this.angleY})
      }
      .width(300)
      .height(300)
      Text(`Y轴旋转： ${Math.round(this.angleY)}°`)
        .fontSize(16)
        .fontColor(Color.White)
      Button(this.isAnimating ? '复原' : '翻转')
        .onClick(() => {
          if (this.isAnimating) {
            this.angleY = 0
            this.isAnimating = false
          } else {
            this.isAnimating = true
            this.angleY = 180
          }
        })
      Button(`doubleSided: ${this.isDoubleSided ? 'true (双面)' : 'false (单面)'}`)
        .backgroundColor(this.isDoubleSided ? '#4CAF50' : '#F44336')
        .onClick(() => {
          this.isDoubleSided = !this.isDoubleSided
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#1a1a1a')
  }
}
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5f/v3/ZGmQJvHHRfmDB8xFmMHWcg/zh-cn_image_0000002723856716.gif?HW-CC-KV=V1&HW-CC-Date=20260910T092828Z&HW-CC-Expire=31536000000&HW-CC-Sign=60560E2233F969F7A1C28B54CBD4A88DE8CCD55C58CC259F8D27CD3D12450E12)