目录

Image Effect

Sets the blur, shadow, spherical, and image effects of the component.

The feature is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

blur

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

Applies a foreground blur effect to the component. When blendMode of BlendApplyType.OFFSCREEN is set for the component, this API may fail to capture the correct image.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Blur radius. A larger value indicates a more blurred image. If the value is less than or equal to 0, the image is not blurred.

Unit: px
options11+ BlurOptions No

Grayscale blur parameters. Adjusts the color level of black and white in the image to make the transition between black, white, and gray smoother and softer. This parameter has no effect on the color adjustment of the image.

Default value: grayscale: [0,0]

Return value

Type Description
T Returns the current component for chained calls.

blur18+

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

Applies a foreground blur effect to the component. Compared to blur, the blurRadius parameter supports the undefined type.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
blurRadius Optional<number> Yes

Blur radius. A larger value indicates a higher degree of blurring. If the value is less than or equal to 0, the image is not blurred.

Unit: px

If blurRadius is set to undefined, the previous value is retained. If this parameter is not set, the default value is 0, indicating that the content is not blurred.
options BlurOptions No

Grayscale blur parameters. The color gradation of the black and white in the image is adjusted to create different shades of gray. It has no impact on colored regions.

Default value: grayscale: [0,0]

Return value

Type Description
T Returns the current component for chained calls.

blur19+

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

Applies a foreground blur effect to the component. Compared to blur18+, this API adds the sysOptions parameter, which allows for system adaptive adjustments.

Widget capability: This API can be used in ArkTS widgets since API version 19.

Atomic service API: This API can be used in atomic services since API version 19.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
blurRadius Optional<number> Yes

Blur radius. A larger value indicates a more blurred effect. If the value is less than or equal to 0, the image is not blurred.

Unit: px

If blurRadius is set to undefined, the previous value is retained. If this parameter is not set, the default value is 0, indicating that the content is not blurred.
options BlurOptions No

Grayscale blur parameters. The color gradation of the black and white in the image is adjusted to create different shades of gray. It has no impact on colored regions.

Default value: grayscale: [0,0]
sysOptions SystemAdaptiveOptions No

System adaptive adjustment options.

Default value: { disableSystemAdaptation: false }

Return value

Type Description
T Returns the current component for chaining calls.

shadow

shadow(value: ShadowOptions | ShadowStyle): T

Applies a shadow effect to the component.

Widget capability: Since API version 9, this API can be used in ArkTS widgets. However, the ShadowStyle type is not supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value ShadowOptions | ShadowStyle10+ Yes

Shadow of the component.

When the value type is ShadowOptions, the blur radius, shadow color, and offset along the x-axis and y-axis can be specified.

When the value type is ShadowStyle, the shadow style can be specified.

Return value

Type Description
T Returns the current component for chaining calls.

shadow18+

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

Applies a shadow effect to the component. Compared to shadow, the options parameter supports the undefined type.

Widget capability: Since API version 18, this API can be used in ArkTS widgets. However, the ShadowStyle type is not supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
options Optional<ShadowOptions | ShadowStyle> Yes

Shadow of the component.

When the value type is ShadowOptions, the blur radius, shadow color, and offset along the x-axis and y-axis can be specified.

When the value type is ShadowStyle, the shadow style can be specified.

If the value of options is undefined, the shadow effect is removed.

Return value

Type Description
T Returns the current component for chaining calls.

grayscale

grayscale(value: number): T

Applies a grayscale effect to the component. The grayscale rendering of the upper layer will overlay that of lower-layer child components. If this parameter is not set, the default value is used.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Grayscale conversion ratio of the component. If the value is 1.0, the component is completely converted to grayscale. If the value is 0.0, the component remains unchanged. Between 0 and 1, the value applies a linear multiplier on the grayscale effect.

Value range: [0.0, 1.0]

NOTE

A value less than 0.0 evaluates to the value 0.0. A value greater than 1.0 evaluates to the value 1.0.

Return value

Type Description
T Returns the current component for chained calls.

grayscale18+

grayscale(grayscale: Optional<number>): T

Applies a grayscale effect to the component. The grayscale rendering of the upper layer will overlay that of lower-layer child components. If this parameter is not set, the image remains unchanged by default. Compared to grayscale, the grayscale parameter supports the undefined type.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
grayscale Optional<number> Yes

Grayscale conversion ratio of the component. If the value is 1.0, the component is completely converted to grayscale. If the value is 0.0, the component remains unchanged. Between 0 and 1, the value applies a linear multiplier on the grayscale effect.

Value range: [0.0, 1.0]

NOTE

A value less than 0.0 evaluates to the value 0.0. A value greater than 1.0 evaluates to the value 1.0.

If grayscale is set to undefined, the default value 0.0 is used, which means the component reverts to its original effect with no grayscale.

Return value

Type Description
T Returns the current component for chained calls.

brightness

brightness(value: number): T

Applies a brightness effect to the component. If this parameter is not set, the image remains unchanged by default. Compared with the lightUpEffect method, the brightness method adjusts the brightness in multiplication mode (the value greater than 1 can be higher than the original brightness), which is applicable to scenarios where the brightness needs to be enhanced or reduced. The lightUpEffect method adjusts the brightness in degree mode (the value range is [0, 1] and cannot be higher than the original brightness), which is applicable to scenarios where the image brightness needs to be controlled. If the blendMode of BlendApplyType.OFFSCREEN is set for the component, this API may fail to capture the correct image.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Brightness effect of the component. 1: No brightness adjustment. Less than 1.0: decreases brightness. 0 or less: Complete black. Greater than 1: increases brightness. 2 or greater: complete white.

Value range: [0, +∞)

Recommended value range: [0, 2]

NOTE

A value less than 0 evaluates to the value 0.

Return value

Type Description
T Returns the current component for chained calls.

brightness18+

brightness(brightness: Optional<number>): T

Applies a brightness effect to the component. If it is not set, the default value is used. Compared with brightness, this API supports the undefined type for the brightness parameter.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
brightness Optional<number> Yes

Brightness effect of the component. 1: No brightness adjustment. Less than 1.0: decreases brightness. 0 or less: Complete black. Greater than 1: increases brightness. 2 or greater: complete white.

Value range: [0, +∞)

Recommended value range: [0, 2]

NOTE

A value less than 0 evaluates to the value 0.

If brightness is undefined, the brightness level is reset to 1.

Return value

Type Description
T Returns the current component for chained calls.

saturate

saturate(value: number): T

Applies a saturation effect to the component. If this parameter is not set, the default value is used.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Saturation of the component. The saturation is the ratio of the chromatic component to the achromatic component (gray) in a color. If the value is 1, the original image is displayed. If the value is greater than 1, a higher percentage of the chromatic component indicates a higher saturation. If the value is less than 1, a higher percentage of the achromatic component indicates a lower saturation.

Value range: [0, +∞)

Recommended value range: [0, 50)

NOTE

A value less than 0 evaluates to the value 0.

Return value

Type Description
T Returns the current component for chained calls.

saturate18+

saturate(saturate: Optional<number>): T

Applies a saturation effect to the component. If this parameter is not set, the default value is used. Compared to saturate, the saturate parameter supports the undefined type.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
saturate Optional<number> Yes

Saturation of the component. The saturation is the ratio of the chromatic component to the achromatic component (gray) in a color. If the value is 1, the original image is displayed. If the value is greater than 1, a higher percentage of the chromatic component indicates a higher saturation. If the value is less than 1, a higher percentage of the achromatic component indicates a lower saturation.

Value range: [0, +∞)

Recommended value range: [0, 50)

NOTE

A value less than 0 evaluates to the value 0.

If the value of saturate is undefined, the saturation effect is restored to 1.

Return value

Type Description
T Returns the current component for chained calls.

contrast

contrast(value: number): T

Applies a contrast effect to the component. If this parameter is not set, there is no change by default.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Contrast of the component. The input parameter is a contrast value. If the value is 1, the source image is displayed. If the value is greater than 1, a larger value indicates a higher contrast and a clearer image. If the value is less than 1, a smaller value indicates a lower contrast. If the value is 0, the image becomes all gray.

Value range: [0, +∞)

Recommended value range: [0, 10)

NOTE

A value less than 0 evaluates to the value 0.

Return value

Type Description
T Returns the current component for chained calls.

contrast18+

contrast(contrast: Optional<number>): T

Applies a contrast effect to the component. If this parameter is not set, there is no change by default. Compared to contrast, the contrast parameter supports the undefined type.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
contrast Optional<number> Yes

Contrast of the component. The input parameter is a contrast value. If the value is 1, the source image is displayed. If the value is greater than 1, a larger value indicates a higher contrast and a clearer image. If the value is less than 1, a smaller value indicates a lower contrast. If the value is 0, the image becomes all gray.

Value range: [0, +∞)

Recommended value range: [0, 10)

NOTE

A value less than 0 evaluates to the value 0.

If contrast is undefined, the contrast effect is reset to 1.0.

Return value

Type Description
T Returns the current component for chained calls.

invert

invert(value: number | InvertOptions): T

Inverts an image.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number | InvertOptions11+ Yes

How an image is inverted.

When the input parameter is of the number type, it represents the image inversion ratio. A value of 1 yields full inversion, while a value of 0 leaves the image unchanged.

Value range: [0, 1].

A value less than 0 evaluates to the value 0. A value larger than 1 is treated as 1.

If the value is of the InvertOptions type, the grayscale value of the background color is compared with the threshold range. If the grayscale value is greater than the upper bound of the threshold range, the high value is used. If the grayscale value is less than the lower bound of the threshold range, the low value is used. If the grayscale value is within the threshold range, the background color changes linearly from high to low.

NOTE

The number and InvertOptions parameter types produce different inversion effects. When you switch parameter types, previous effects persist and both effects coexist. Use consistent parameter types for predictable results.

Return value

Type Description
T Returns the current component for chained calls.

invert18+

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

Inverts an image. Compared with invert, this API supports the undefined type for the options parameter.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
options Optional<number | InvertOptions > Yes

How an image is inverted.

When the input parameter is of the number type, it represents the image inversion ratio. A value of 1 yields full inversion, while a value of 0 leaves the image unchanged.

Value range: [0, 1].

A value less than 0 evaluates to the value 0. A value larger than 1 is treated as 1.

If the value is of the InvertOptions type, the grayscale value of the background color is compared with the threshold range. If the grayscale value is greater than the upper bound of the threshold range, the high value is used. If the grayscale value is less than the lower bound of the threshold range, the low value is used. If the grayscale value is within the threshold range, the background color changes linearly from high to low.

If options is undefined, the component reverts to its original effect.

NOTE

The number and InvertOptions parameter types produce different inversion effects. When you switch parameter types, previous effects persist and both effects coexist. Use consistent parameter types for predictable results.

Return value

Type Description
T Returns the current component for chained calls.

sepia

sepia(value: number): T

Converts the image to a sepia tone, reducing color intensity to create a warm, vintage image style.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Intensity of the sepia filter. A value of 1 results in a completely sepia image, values less than or equal to 0 leave the image unchanged, and values greater than 1 increase the color shift, making the image brighter and more yellow or red, though this is not a standard sepia effect.

Value range: [0, +∞). Recommended value range: (0, 1].

Return value

Type Description
T Returns the current component for chained calls.

sepia18+

sepia(sepia: Optional<number>): T

Converts the image to a sepia tone, reducing color intensity to create a warm, vintage image style. Compared to sepia, this API supports the undefined type for the sepia parameter.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
sepia Optional<number> Yes

Intensity of the sepia filter. A value of 1 results in a completely sepia image, values less than or equal to 0 leave the image unchanged, and values greater than 1 increase the color shift, making the image brighter and more yellow or red, though this is not a standard sepia effect.

Value range: [0, +∞). Recommended value range: (0, 1].

If sepia is undefined, the component reverts to its original effect.

Return value

Type Description
T Returns the current component for chained calls.

hueRotate

hueRotate(value: number | string): T

Rotates the hue of the component. If this parameter is not set, the image remains unchanged by default.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number | string Yes

Hue rotation angle of the component.

Unit: degree (°)

Value range: (-∞, +∞)

NOTE

The original color will be displayed after the hue is rotated by 360 degrees. The original color will be displayed after the hue is rotated by 180 degrees and then by –180 degrees. When the data type is number, the value 90 is equivalent to '90deg'.

Return value

Type Description
T Returns the current component for chained calls.

hueRotate18+

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

Rotates the hue of the component. If this parameter is not set, the default value is used. Compared to hueRotate, the rotation parameter supports the undefined type.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
rotation Optional<number | string> Yes

Hue rotation angle of the component. The unit is degree (°).

Value range: (-∞, +∞)

For the string type, the value must be a numeric string.

NOTE

The original color will be displayed after the hue is rotated by 360 degrees. The original color will be displayed after the hue is rotated by 180 degrees and then by –180 degrees. When the data type is number, the value 90 is equivalent to '90deg'.

If rotation is undefined, the component reverts to its original effect with no hue rotation.

Return value

Type Description
T Returns the current component for chaining calls.

colorBlend

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

Applies a color blend effect to the component.

System capability: SystemCapability.ArkUI.ArkUI.Full

Atomic service API: This API can be used in atomic services since API version 11.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Parameters

Name Type Mandatory Description
value Color | string | Resource Yes Color to blend with the component. The value can be of the Color, string, or Resource type, for example, Color.Green or '0x000000' and 'rgba(0,0,0,1)'.

Return value

Type Description
T Returns the current component for chaining calls.

colorBlend18+

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

Applies a color blend effect to the component. Compared with colorBlend, this API supports the undefined type for the color parameter.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Atomic service API: This API can be used in atomic services since API version 18.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Parameters

Name Type Mandatory Description
color Optional<Color | string | Resource> Yes

Color to blend with the component. The value can be an enumerated value of the Color type, a string (for example, '0x000000' or 'rgba(0,0,0,1)'), or a resource reference.

If color is undefined, the component reverts to its original effect with no color blending.

Return value

Type Description
T Returns the current component for chained calls.

linearGradientBlur12+

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

Applies a linear gradient foreground blur effect to the component. If BlendApplyType.OFFSCREEN is set to blendMode for the component, this API may fail to capture the correct image.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Blur radius. Larger values produce stronger blur. If the value is 0, the content is not blurred.

Unit: px

Value range: [0, 1000]
options LinearGradientBlurOptions Yes

Linear gradient blur effect.

Linear gradient blur parameters, including blur intensity, the fractionStops array for blur positions, and the direction of gradient blur.

Return value

Type Description
T Returns the current component for chained calls.

linearGradientBlur18+

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

Applies a linear gradient foreground blur effect to the component. Compared with linearGradientBlur12+, this API supports the undefined type.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
blurRadius Optional<number> Yes

Blur radius. Larger values produce stronger blur. If the value is 0, the content is not blurred.

Unit: px

Value range: [0, 1000]

If blurRadius is undefined, the gradient blur effect reverts to 0.
options Optional<LinearGradientBlurOptions> Yes

Linear gradient blur effect.

Linear gradient blur parameters, including blur intensity, the fractionStops array for blur positions, and the direction of gradient blur.

When the value of options is undefined, the linear gradient blur effect is restored to the effect when the value is undefined.

Return value

Type Description
T Returns the current component for chain calling.

renderGroup10+

renderGroup(value: boolean): T

Sets whether to form a render group. A render group means that the subtree composed of the current component and its child components is first rendered on an offscreen canvas and then composited with the parent component. Setting a render group allows the system to cache the rendering result, improving performance. Compared with the freeze method, renderGroup allows component attributes to continue to be updated (but frequent updates will invalidate the cache), which is suitable for scenarios where dynamic updates are required and cache optimization is desired. freeze completely stops internal attribute updates, which is suitable for scenarios where static content is stable and cache optimization is required. However, if components within the render group are frequently updated, cache invalidation may lead to performance degradation. Additionally, when a render group is set and the current component's opacity is not 1, the rendering effect may differ.

If this attribute is not set, no render group is formed by default.

Atomic service API: This API can be used in atomic services since API version 11.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Widget capability: This API can be used in ArkTS widgets since API version 12.

Parameters

Name Type Mandatory Description
value boolean Yes

Whether the current component and its child components form a render group.

false: no. Rendering is performed directly without offscreen rendering.

true: yes. The current component and its child components are rendered offscreen first and then composited with the parent component.

Return value

Type Description
T Returns the current component for chain calls.

renderGroup18+

renderGroup(isGroup: Optional<boolean>): T

Sets whether to form a render group. A render group means that the subtree composed of the current component and its child components is first rendered on an offscreen canvas and then composited with the parent component. Setting a render group allows the system to cache the rendering result, improving performance. However, if components within the render group are frequently updated, cache invalidation may lead to performance degradation. Additionally, when a render group is set and the current component's opacity is not 1, the rendering effect may differ.

Different from freeze, renderGroup allows internal attribute updates after the drawing result is cached (the cache becomes invalid during updates), which is applicable to scenarios where dynamic updates are required. freeze completely stops internal attribute updates, which is applicable to scenarios where the component content is stable and does not need to be updated.

Compared with renderGroup10+, this API supports the undefined type for the isGroup parameter.

If this attribute is not set, no render group is formed by default.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Widget capability: This API can be used in ArkTS widgets since API version 18.

Parameters

Name Type Mandatory Description
isGroup Optional<boolean> Yes

Whether the current component and its child components form a render group.

false: no. Rendering is performed directly without offscreen rendering.

true: yes. The current component and its child components are rendered offscreen first and then composited with the parent component.

If isGroup is set to undefined, no render group is formed.

Return value

Type Description
T Returns the current component for chained calls.

blendMode11+

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

Defines how the component's content (including the content of it child components) is blended with the existing content on the canvas (possibly offscreen canvas) below.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value BlendMode Yes

Blend mode.

Default value: BlendMode.NONE

NOTE

When BlendMode.NONE is used, the blend effect is BlendMode.SRC_OVER by default, and BlendApplyType does not take effect.
type BlendApplyType No

Whether the blend mode is implemented offscreen.

Default value: BlendApplyType.FAST

NOTE

1. BlendApplyType.FAST: The blend mode is not implemented offscreen.

2. BlendApplyType.OFFSCREEN: An offscreen canvas of the size of the current component is created. The content of the current component (including child components) is then drawn onto the offscreen canvas, and blended with the existing content on the canvas below using the specified blend mode. This approach may cause issues with screen capture for APIs such as linearGradientBlur12+, backgroundEffect, brightness, and blur.

3. When the blending mode is set to BlendMode.NONE, BlendApplyType does not take effect.

Return value

Type Description
T Returns the current component for chained calls.

blendMode18+

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

Defines how the component's content (including the content of it child components) is blended with the existing content on the canvas (possibly offscreen canvas) below. Compared to blendMode11+, the mode parameter supports the undefined type.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
mode Optional<BlendMode> Yes

Blend mode.

Default value: BlendMode.NONE

If mode is undefined, the component reverts to its original effect of not enabling offscreen rendering as a whole before blending with the parent component.

NOTE

When BlendMode.NONE is used, the blend effect is BlendMode.SRC_OVER by default, and BlendApplyType does not take effect.
type BlendApplyType No

Whether the blend mode is implemented offscreen.

Default value: BlendApplyType.FAST

NOTE

1. BlendApplyType.FAST: The blend mode is not implemented offscreen.

2. BlendApplyType.OFFSCREEN: An offscreen canvas of the size of the current component is created. The content of the current component (including child components) is then drawn onto the offscreen canvas, and blended with the existing content on the canvas below using the specified blend mode. This approach may cause issues with screen capture for APIs such as linearGradientBlur12+, backgroundEffect, brightness, and blur.

3. When the blend mode is set to BlendMode.NONE, BlendApplyType does not take effect.

Return value

Type Description
T Returns the current component for chained calls.

BlendApplyType11+

Defines how to apply the specified blend mode to the content of a view.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Value Description
FAST 0 The content of the view is blended in sequence on the target image.
OFFSCREEN 1 The content of the component and its child components are drawn on the offscreen canvas, and then blended with the existing content on the canvas.

useShadowBatching11+

useShadowBatching(value: boolean): T

Determines whether to draw the shadows of child nodes at the same layer, which controls the overlapping effect of shadows of elements at the same layer. This method must be used together with the shadow method. When the shadow effect has been set for child nodes using the shadow() method, useShadowBatching can be used to determine whether to draw the shadows of these child nodes at the same layer.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Widget capability: This API can be used in ArkTS widgets since API version 11.

Parameters

Name Type Mandatory Description
value boolean Yes

Whether to render child node shadows at the same layer.

Default value: false

true: Child node shadows are rendered at the same layer without overlapping.

false: Child node shadows are rendered separately, with later shadows overlapping earlier ones.

NOTE

1. This feature is disabled by default. When child nodes have large shadow radius and overlapping areas, later-rendered shadows cover earlier ones. Enabling this feature renders all child shadows simultaneously without overlap.

2. Avoid nesting useShadowBatching. When used in nested mode, useShadowBatching takes effect for the current child node only and cannot be recursively used.

Return value

Type Description
T Returns the current component for chained calls.

useShadowBatching18+

useShadowBatching(use: Optional<boolean>): T

Sets whether to draw the shadows of child nodes at the same layer. When the shadows are drawn at the same layer, the shadows of child nodes do not overlap. This method must be used together with the shadow method. When the shadow effect is set for child nodes, useShadowBatching can be used to draw the shadows of child nodes at the same layer, preventing the shadows from overlapping. The calling sequence is as follows: Set the shadow attribute on the child node, and then set useShadowBatching(true) on the parent container. Compared with useShadowBatching11+, this API supports the undefined type for the use parameter.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Widget capability: This API can be used in ArkTS widgets since API version 18.

Parameters

Name Type Mandatory Description
use Optional<boolean> Yes

Whether to render child node shadows at the same layer.

Default value: false

true: Child node shadows are rendered at the same layer without overlapping.

false: Child node shadows are rendered separately, with later shadows overlapping earlier ones.

NOTE

1. This feature is disabled by default. When child nodes have large shadow radius and overlapping areas, later-rendered shadows cover earlier ones. Enabling this feature renders all child shadows simultaneously without overlap.

2. Avoid nesting useShadowBatching. When used in nested mode, useShadowBatching takes effect for the current child node only and cannot be recursively used.

If use is undefined, the component reverts to its original effect of not using shadow overlapping.

Return value

Type Description
T Returns the current component for method chaining.

sphericalEffect12+

sphericalEffect(value: number): T

Applies a spherical effect to the component. The sphericalization effect maps the component content to the surface of a sphere, making the image look like a three-dimensional sphere. A larger value indicates a higher sphericalization degree and stronger three-dimensional effect.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Spherical degree of the component. The sphericalization effect maps the component content to the spherical surface, making the image look like a sphere. A larger value indicates a higher spherical radian and a stronger three-dimensional effect.

The value ranges from 0 to 1.

NOTE

1. If the value is 0, the component remains unchanged. If the value is 1, the component is completely spherical. Between 0 and 1, a larger value indicates a higher spherical degree.

A value less than 0 is handled as the value 0. A value greater than 1 is handled as the value 1.

2. The component's shadow and outer stroke do not support spherical effects.

3. If the value is greater than 0, the component is frozen, and its content is drawn to the transparent offscreen buffer. To update the component attributes, set the value to 0.

Return value

Type Description
T Returns the current component for chaining calls.

sphericalEffect18+

sphericalEffect(effect: Optional<number>): T

Applies a spherical effect to the component. The sphericalization effect maps the component content to the spherical surface, making the image look like a sphere. A larger value indicates a higher spherical radian and a stronger three-dimensional effect. Compared to sphericalEffect12+, the effect parameter supports the undefined type.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
effect Optional<number> Yes

Spherical degree of the component. The spherical effect maps the component content to a spherical surface, giving the image a three-dimensional effect similar to that of a sphere. A larger value indicates a higher spherical curvature and stronger three-dimensional effect.

The value ranges from 0 to 1.

NOTE

1. If the value is 0, the component remains unchanged. If the value is 1, the component is completely spherical. Between 0 and 1, a larger value indicates a higher spherical degree.

A value less than 0 is handled as the value 0. A value greater than 1 is handled as the value 1.

2. The component's shadow and outer stroke do not support spherical effects.

3. If effect is set to a positive number, the component is frozen, and its content is drawn to the transparent offscreen buffer. To update the component attributes, set effect to 0.

If effect is undefined, the spherical degree reverts to 0.

Return value

Type Description
T Returns the current component for chaining calls.

lightUpEffect12+

lightUpEffect(value: number): T

Applies a light up effect to the component.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value number Yes

Light up degree of the component.

The value ranges from 0 to 1.

If the value is 0, the component is dark. If the value is 1, the component is fully illuminated. Between 0 and 1, a larger value indicates higher luminance. A value less than 0 is handled as the value 0. A value greater than 1 is handled as the value 1.

Return value

Type Description
T Returns the current component for chained calls.

lightUpEffect18+

lightUpEffect(degree: Optional<number>): T

Applies a light up effect to the component. Compared to lightUpEffect12+, the degree parameter supports the undefined type.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
degree Optional<number> Yes

Light up degree of the component.

The value ranges from 0 to 1.

If the value of degree is 0, the image is completely black. If the value of degree is 1, the image is completely bright. Between 0 and 1, a larger value indicates higher luminance. A value less than 0 is handled as the value 0. A value greater than 1 is handled as the value 1.

If degree is undefined, the light up degree reverts to 1.

Return value

Type Description
T Returns the current component for chained calls.

pixelStretchEffect12+

pixelStretchEffect(options: PixelStretchEffectOptions): T

Applies a pixel stretch effect to the component.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
options PixelStretchEffectOptions Yes

Pixel stretch effect options.

The value includes the length by which a pixel is stretched toward the four edges.

NOTE

1. If the length is a positive value, the original image is stretched, and the image size increases. The edge pixels grow by the set length toward the top, bottom, left, and right edges.

2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:

Shrinking mode:

- The image shrinks from the four edges by the absolute value of length set through options.

- The image is stretched back to the original size with edge pixels.

3. Constraints on options:

- The length values for the four edges must be all positive or all negative. That is, the four edges are stretched or shrink at the same time in the same direction.

- The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.

If the input value is invalid, the image is displayed as {0, 0, 0, 0}, that is, the image remains unchanged.

Return value

Type Description
T Returns the current component for chained calls.

pixelStretchEffect18+

pixelStretchEffect(options: Optional<PixelStretchEffectOptions>): T

Applies a pixel stretch effect to the component. Compared to pixelStretchEffect12+, the options parameter supports the undefined type.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
options Optional<PixelStretchEffectOptions> Yes

Pixel stretch effect options.

The value includes the length by which a pixel is stretched toward the four edges.

NOTE

1. If the length is a positive value, the original image is stretched, and the image size increases. The edge pixels grow by the set length toward the top, bottom, left, and right edges.

2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:

Shrinking mode:

- The image shrinks from the four edges by the absolute value of length set through options.

- The image is stretched back to the original size with edge pixels.

3. Constraints on options:

- The length values for the four edges must be all positive or all negative. That is, the four edges are stretched or shrink at the same time in the same direction.

- The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.

If the input value is invalid, the image is displayed as {0, 0, 0, 0}, that is, the image remains unchanged.

If options is undefined, the component reverts to its original effect with no pixel stretch.

Return value

Type Description
T Returns the current component for chained calls.

PixelStretchEffectOptions10+

Describes the pixel stretch effect options.

Atomic service API: This API can be used in atomic services since API version 11.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
left Length No Yes

Length by which a pixel is stretched towards the left edge of the image. The value must be consistent with that in the right, top, and bottom directions. That is, the extension in the four directions must be all positive or all negative values. Percentages and specific values cannot be mixed.

Default value: 0vp
right Length No Yes

Length by which a pixel is stretched towards the right edge of the image. The value must be consistent with that in the left, top, and bottom directions. The extension in the four directions must be either all positive or all negative values. Percentage and specific values cannot be mixed.

Default value: 0vp
top Length No Yes

Length by which a pixel is stretched towards the top edge of the image. The value must be consistent with that in the left, right, and bottom directions. The extension in the four directions must be either all positive or all negative values. Percentage and specific values cannot be mixed.

Default value: 0vp
bottom Length No Yes

Length by which a pixel is stretched towards the right edge of the image. The value must be consistent with that in the left, right, and top directions. The extension in the four directions must be either all positive or all negative values. Percentage and specific values cannot be mixed.

Default value: 0vp

systemBarEffect12+

systemBarEffect(): T

Automatically determines the color inversion area and degree based on the background color and adds a blur effect. The smart color inversion feature automatically determines the color inversion policy based on the color and brightness of the background content, ensuring that the component content is visible in different backgrounds. The blur effect blurs the background content, enhancing the visual integration of the system bar with the background.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
T Returns the current component for chaining calls.

ShadowType10+

Shadow type.

Atomic service API: This API can be used in atomic services since API version 11.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Value Description
COLOR 0 Color shadow, which is drawn based on the specified color value.
BLUR 1 Blur shadow, which is drawn based on the blurred component content.

ShadowOptions

Provides the shadow attributes, including the blur radius, color, and offset along the x-axis and y-axis.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
radius number | Resource No No

Blur radius of the shadow.

Value range: [0, +∞). Since API version 26.0.0, the value range is updated to (-∞, +∞).

Unit: px

NOTE

In versions earlier than API version 26.0.0, if this parameter is set to a value less than 0, the value 0 is used, and the shadow is not drawn. In API version 26.0.0 and later, the specified value is used. When the value is 0, the shadow is still drawn. When the value is a negative number, the shadow is not drawn.

To use a value in the unit of vp, you can use vp2px to convert the value.

If radius is of the Resource type, its value must be of the number type.

Atomic service API: This API can be used in atomic services since API version 11.

Widget capability: This API can be used in ArkTS widgets since API version 9.
type10+ ShadowType No Yes

Shadow type.

Default value: COLOR

Atomic service API: This API can be used in atomic services since API version 11.

Model restriction: This API can be used only in the stage model.
color Color | string | Resource | ColoringStrategy11+ No Yes

Color of the shadow.

The default color is black.

NOTE

Since API version 11, this API supports ColoringStrategy, which cannot be used with ArkTS widgets or the textShadow attribute.

With ColoringStrategy, the average color or primary color can be obtained, and the obtained color is applied to the shadow drawing area.

The 'average' string can be used to trigger the mode for obtaining the average color, and the 'primary' string for obtaining the primary color.

Atomic service API: This API can be used in atomic services since API version 11.

Widget capability: This API can be used in ArkTS widgets since API version 9.
offsetX number | Resource No Yes

Offset of the shadow along the x-axis.

Default value: 0

Unit: px

NOTE

To use a value in the unit of vp, you can use vp2px to convert the value.

If offsetX is of the Resource type, its value must be of the number type.

Atomic service API: This API can be used in atomic services since API version 11.

Widget capability: This API can be used in ArkTS widgets since API version 9.
offsetY number | Resource No Yes

Offset of the shadow along the y-axis.

Default value: 0

Unit: px

NOTE

To use a value in the unit of vp, you can use vp2px to convert the value.

If offsetY is of the Resource type, its value must be of the number type.

Atomic service API: This API can be used in atomic services since API version 11.

Widget capability: This API can be used in ArkTS widgets since API version 9.
fill11+ boolean No Yes

Whether to fill the inside of the component with shadow. true: Fill the inside of the component with shadow.

false: Do not fill the inside of the component with shadow.

Default value: false.

NOTE

This attribute does not take effect in textShadow.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

ShadowStyle10+

Defines the shadow effect of the component.

Atomic service API: This API can be used in atomic services since API version 11.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Value Description
OUTER_DEFAULT_XS 0 Mini shadow.
OUTER_DEFAULT_SM 1 Small shadow.
OUTER_DEFAULT_MD 2 Medium shadow.
OUTER_DEFAULT_LG 3 Large shadow.
OUTER_FLOATING_SM 4 Floating small shadow.
OUTER_FLOATING_MD 5 Floating medium shadow.

BlendMode11+

Blend mode.

In the blendMode enums, s indicates the source pixel, d indicates the target pixel, sa indicates the opacity of the source pixel, da indicates the opacity of the target pixel, r indicates the pixel after blending, and ra indicates the opacity of the pixel after blending.

Widget capability: This API can be used in ArkTS widgets since API version 11.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Value Description
NONE 0 The top image is superimposed on the bottom image without any blending.
CLEAR 1 The target pixels covered by the source pixels are erased by being turned to completely transparent.
SRC 2 r = s: Only the source pixels are displayed.
DST 3 r = d: Only the target pixels are displayed.
SRC_OVER 4 r = s + (1 - sa) * d: The source pixels are blended based on opacity and cover the target pixels.
DST_OVER 5 r = d + (1 - da) * s: The target pixels are blended based on opacity and cover the source pixels.
SRC_IN 6 r = s * da: Only the part of the source pixels that overlap with the target pixels is displayed.
DST_IN 7 r = d * sa: Only the part of the target pixels that overlap with the source pixels is displayed.
SRC_OUT 8 r = s * (1 - da): Only the part of the source pixels that do not overlap with the target pixels is displayed.
DST_OUT 9 r = d * (1 - sa): Only the part of the target pixels that do not overlap with the source pixels is displayed.
SRC_ATOP 10 r = s * da + d * (1 - sa): The part of the source pixels that overlap with the target pixels is displayed and the part of the target pixels that do not overlap with the source pixels are displayed.
DST_ATOP 11 r = d * sa + s * (1 - da): The part of the target pixels that overlap with the source pixels and the part of the source pixels that do not overlap with the target pixels are displayed.
XOR 12 r = s * (1 - da) + d * (1 - sa). The pixel is not displayed where the source pixel overlaps the target pixel, and the source pixel and target pixel are displayed where the source pixel does not overlap the target pixel.
PLUS 13 r = min(s + d, 1): New pixels resulting from adding the source pixels to the target pixels are displayed.
MODULATE 14 r = s * d: New pixels resulting from multiplying the source pixels with the target pixels are displayed.
SCREEN 15 r = s + d - s * d: Pixels are blended by adding the source pixels to the target pixels and subtracting the product of their multiplication.
OVERLAY 16 The MULTIPLY or SCREEN mode is used based on the target pixels.
DARKEN 17 rc = s + d - max(s * da, d * sa), ra = kSrcOver: When two colors overlap, whichever is darker is used.
LIGHTEN 18 rc = s + d - min(s * da, d * sa), ra = kSrcOver: The darker of the pixels (source and target) is used.
COLOR_DODGE 19 The colors of the target pixels are lightened to reflect the source pixels.
COLOR_BURN 20 The colors of the target pixels are darkened to reflect the source pixels.
HARD_LIGHT 21 The MULTIPLY or SCREEN mode is used, depending on the source pixels.
SOFT_LIGHT 22 The LIGHTEN or DARKEN mode is used, depending on the source pixels.
DIFFERENCE 23 rc = s + d - 2 * (min(s * da, d * sa)), ra = kSrcOver: The final pixel is the result of subtracting the darker of the two pixels (source and target) from the lighter one.
EXCLUSION 24 rc = s + d - 2 * (s * d), ra = kSrcOver: The final pixel is the result of subtracting the darker of the two pixels (source and target) from the lighter one, producing a low-contrast visual effect.
MULTIPLY 25 r = s * (1 - da) + d * (1 - sa) + s * d: The final pixel is the result of multiplying the source pixel by the target pixel.
HUE 26 The resultant image is created with the luminance and saturation of the source image and the hue of the target image.
SATURATION 27 The resultant image is created with the luminance and hue of the target image and the saturation of the source image.
COLOR 28 The resultant image is created with the saturation and hue of the source image and the luminance of the target image.
LUMINOSITY 29 The resultant image is created with the saturation and hue of the target image and the luminance of the source image.

LinearGradientBlurOptions12+

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
fractionStops FractionStop[] No No Gradient blur stops. The value is a set of binary arrays, each of which indicates [blur score, blur position] and consists of numbers ranging from 0 to 1 (those less than 0 are treated as 0, and those greater than 1 are treated as 1). The blur positions in the arrays must be in strict ascending order. Noncompliance will be logged. For the blur settings to take effect, the number of binary arrays must be greater than or equal to 2.
direction GradientDirection No No

Gradient blur direction.

Default value:

GradientDirection.Bottom

FractionStop12+

type FractionStop = [ number, number ]

Defines a gradient blur stop.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type Description
[ number, number ]

The first number indicates the opacity value. The value 1 indicates fully opaque, and 0 indicates fully transparent.

Value range: [0, 1].

The second number indicates the position in gradient . The value 1 indicates the end position, and 0 indicates the start position.

Value range: [0, 1].

InvertOptions11+

Describes the options for inverting the foreground color. The color inversion value is determined based on the grayscale threshold range. For details, see the detailed mechanism description in invert.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
low number No No

Value when the background color is greater than the grayscale threshold.

Value range: [0, 1]. A value less than 0 evaluates to the value 0. A value larger than 1 is treated as 1.
high number No No

Value when the background color is less than the grayscale threshold.

Value range: [0, 1]. A value less than 0 evaluates to the value 0. A value larger than 1 is treated as 1.
threshold number No No

Grayscale threshold. This parameter is used together with thresholdRange. The grayscale threshold plus or minus thresholdRange forms the threshold range.

Value range: [0, 1].
thresholdRange number No No

Threshold value range.

Value range: [0, 1]. If the value is less than 0, it is treated as 0. If the value is greater than 1, it is treated as 1.

NOTE

This range defines the upper and lower bounds of the grayscale threshold. The grayscale value changes linearly from high to low within the range.

BackgroundImageOptions18+

Defines the background image options.

Synchronously loading background images can lead to potential performance issues. For details, see Image.

Widget capability: This API can be used in ArkTS widgets since API version 18.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
syncLoad boolean No Yes

Whether to load the image synchronously. By default, the image is loaded asynchronously. During synchronous loading, the UI thread is blocked and the placeholder image is not displayed.

Default value: false

false: Asynchronously load the image.

true: Synchronously load the image.
repeat ImageRepeat No Yes Repeat pattern of the background image. Default value: ImageRepeat.NoRepeat.

freeze12+

freeze(value: boolean): T

Sets whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. When this parameter is set to true, the component property update is frozen. To resume the property update, set this parameter to false.

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 12.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value boolean Yes

Whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. If the opacity of the component is not 1, the drawing effect may vary depending on the value.

Default value: false

true: Freeze the component.

false: Do not freeze the component.

Return value

Type Description
T Returns the current component for chained calls.

freeze18+

freeze(freeze: Optional<boolean>): T

Sets whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. When freeze is set to true, the component attribute update is frozen. To resume the attribute update, set freeze to false. Compared with freeze, this API supports the undefined type for the freeze parameter.

This API can be called within attributeModifier since API version 20.

Atomic service API: This API can be used in atomic services since API version 18.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
freeze Optional<boolean> Yes

Whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. If the opacity of the component is not 1, the drawing effect may vary depending on the value.

Default value: false

true: Freeze the component.

false: Do not freeze the component.

If freeze is set to undefined, the previous value is retained.

Return value

Type Description
T Returns the current component for chaining calls.

systemMaterial

systemMaterial(material: SystemUiMaterial | undefined): T

Sets the system material for a component. The attributes vary depending on the system material. This API can be used to set the background color (backgroundColor), border color (borderColor), border width (borderWidth), shadow, and material layer (filtermaterialFilter) effect. The affected attributes are related to the device material level. For details, see ImmersiveMaterial. ImmersiveMaterial is only effective on devices that support immersive materials. On devices that do not support immersive materials, the immersive material can be set but has no effect. You can use isImmersiveMaterialSupported to determine whether a device supports immersive materials. For details, see Example 1: Configuring the Immersive System Material.

  • ImmersiveMaterial is only effective on devices that support immersive materials. On devices that do not support immersive materials, the immersive material can be set but has no effect. You can use isImmersiveMaterialSupported to determine whether a device supports immersive materials. On devices that do not support immersive materials, after an ImmersiveMaterial is set, the style of the component is still determined by the configured general attributes, and the ImmersiveMaterial will not overwrite any general attributes.
  • When conflicting values are assigned to universal attributes affected by materials, attributes set later take precedence for all attributes except shadows. Shadow behavior is governed by the applyShadow parameter of ImmersiveMaterial.
    • When backgroundColor is set before systemMaterial, the predefined backgroundColor setting gets overridden. On high- and medium-computing devices that support immersive materials, the background color is cleared to transparent. On low-computing devices that support immersive materials, the background color of the material overwrites the previously set backgroundColor attribute.
    • When systemMaterial is set before backgroundColor, the background color effect affected by systemMaterial is overridden, and the backgroundColor value takes effect.
  • For use cases requiring the material color across all device computing tiers, use the materialColor parameter of ImmersiveMaterial instead of defining backgroundColor.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Widget capability: This API can be used in ArkTS widgets since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
material SystemUiMaterial | undefined Yes

System material object of the component. Setting this parameter to undefined removes the material effect entirely, and any universal attributes previously overridden by the material revert back to their manually configured values. When a valid material object is applied, resolution rules for conflicting attributes are governed by the material. For details, see ImmersiveMaterial.

NOTE

The attribute impact of the material effect varies depending on the computing power level of the device. For details, see the preceding description.

Return value

Type Description
T Returns the current component for method chaining.

SystemUiMaterial

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

Sets the base class of a system material object.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Widget capability: This API can be used in ArkTS widgets since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type Description
import('../api/@ohos.arkui.uiMaterial').default.Material Base class of a system material object.

doubleSided

doubleSided(value: Optional<boolean>): T

Sets whether to enable double-sided rendering for the component.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Widget capability: This API can be used in ArkTS widgets since API version 26.0.0.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value Optional<boolean> Yes

Whether to enable double-sided rendering for the component.

true: Both the front and back sides of the component are visible.

false: The front side of the component is visible; the back side of the component is invisible when the component is rotated.

When this parameter is set to undefined, the behavior matches true, and double-sided rendering is enabled by default.

Return value

Type Description
T Returns the current component instance to support method chaining.

Example

[h2]Example 1: Setting Different Image Attributes

This example applies different image effects.

// xxx.ets
@Entry
@Component
struct ImageEffectsExample {
  build() {
    Column({ space: 5 }) {
      // Apply the shadow effect.
      Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image'))
        .width('90%')
        .height(30)
        .shadow({
          radius: 10,
          color: Color.Green,
          offsetX: 20,
          offsetY: 20
        })

      // Add the internal shadow effect.
      Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image'))
        .width('90%')
        .height(30)
        .shadow({
          radius: 5,
          color: Color.Green,
          offsetX: 20,
          offsetY: 20,
          fill: true
        }).opacity(0.5)

      // Apply the grayscale effect. The grayscale value ranges from 0 to 1. The closer the grayscale value is to 1, the more obvious the grayscale effect is.
      Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).grayscale(0.3)
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).grayscale(0.8)

      // Apply the brightness effect. The value 1 indicates no effects. If the value is less than 1, the brightness decreases. If the value is greater than 1, the brightness increases.
      Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).brightness(1.2)

      // Apply the saturation effect. If the value is 1, the source image is displayed.
      Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).saturate(2.0)
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).saturate(0.7)

      // Apply the contrast effect. If the value is 1, the source image is displayed. If the value is greater than 1, a larger value indicates a higher contrast and a clearer image. If the value is less than 1, a smaller value indicates a lower contrast is.
      Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).contrast(2.0)
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).contrast(0.8)

      // Invert the image.
      Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).invert(0.2)
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).invert(0.8)

      // Apply the color blend effect.
      Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Green)
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Blue)

      // Convert the image color to sepia.
      Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).sepia(0.8)

      // Apply the hue rotation effect.
      Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%')
      // Replace $r("app.media.image") with the image resource file you use.
      Image($r('app.media.image')).width('90%').height(30).hueRotate(90)
    }.width('100%').margin({ top: 5 })
  }
}

[h2]Example 2: Applying a Linear Gradient Blur Effect

This example demonstrates how to apply a linear gradient blur effect on a component using linearGradientBlur.

// xxx.ets
@Entry
@Component
struct LinearGradientBlurExample {
  // Replace $r('app.media.testlinearGradientBlurOrigin') with the resource file you use.
  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) // Set the blur effect of the image to none (no blur applied).
            .linearGradientBlur(60,
              { fractionStops: [[0, 0], [0, 0.33], [1, 0.66], [1, 1]], direction: GradientDirection.Bottom })
        }
      }
    }
  }
}

[h2]Example 3: Setting Offscreen Rendering Effect

This example demonstrates how to use renderGroup to set whether the component is rendered entirely offscreen and then composited with its parent component.

// 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)
  }
}

[h2]Example 4: Blending the Current Component Content with Canvas Content

This example demonstrates how to blend the current component content with the canvas content below using blendMode.

// 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%')
    // Replace $r("app.media.image") with the image resource file you use.
    .backgroundImage($r('app.media.image'))
    .backgroundImageSize(ImageSize.Cover)
  }
}

[h2]Example 5: Inverting the Foreground Color

This example demonstrates how to achieve intelligent foreground color inversion using InvertOptions.

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column()
      Stack() {
        // Replace $r("app.media.r") with the image resource file you use.
        // In this example, the images are arranged from left to right, and the color is from light to dark.
        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%')
    }
  }
}

[h2]Example 6: Setting Non-Overlapping Same-Layer Shadows

This example demonstrates how to implement non-overlapping shadow effect within the same layer using useShadowBatching in combination with shadow.

// 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 })
  }
}

[h2]Example 7: Applying a Spherical Effect to a Component

This example demonstrates how to apply a spherical effect to a component using sphericalEffect.

// xxx.ets
@Entry
@Component
struct SphericalEffectExample {
  build() {
    Stack() {
      TextInput({ placeholder: "Enter a percentage ([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%")
  }
}

Below is how the component looks with the spherical effect applied.

Below is how the component looks without the spherical effect applied.

[h2]Example 8: Applying a Light Up Effect to a Component

This example demonstrates how to apply a light up effect to a component using lightUpEffect.

// 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%")
  }
}

Below is how the component looks with the light up effect applied.

Below is how the component looks with lightUpEffect set to 0.2:

Below is how the component looks without the light up effect applied.

[h2]Example 9: Applying a Pixel Stretch Effect to a Component

This example demonstrates how to apply a pixel stretch effect to a component using pixelStretchEffect.

// 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%")
  }
}

Below is how the component looks with the pixel stretch effect applied.

Below is how the component looks without the pixel stretch effect applied.

[h2]Example 10: Applying a System Bar Effect to a Component

This example demonstrates how to apply a system bar effect to a component using systemBarEffect.

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Stack() {
        // Replace $r("app.media.testImage") with the image resource file you use.
        Image($r('app.media.testImage')).width('100%').height('100%')
        Column()
          .width(150)
          .height(10)
          .systemBarEffect()
          .border({ radius: 5 })
          .margin({ bottom: 80 })
      }.alignContent(Alignment.Center)
    }
  }
}

Below is how the component looks with the system bar effect applied.

[h2]Example 11: Setting Whether to Enable Double-Sided Rendering

This example demonstrates how to enable/disable double-sided rendering using doubleSided.

Since API version 26.0.0, the doubleSided method is added.

// xxx.ets
@Entry
@Component
struct DoubleSided {
  @State angleY: number = 0;
  @State isAnimating: boolean = false;
  @State isDoubleSided: boolean = true;
  build() {
    Column({space: 30}) {
      Text('Double-Sided Rendering Verification (Back-Face Culling)')
        .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-axis rotation: ${Math.round(this.angleY)}°`)
        .fontSize(16)
        .fontColor(Color.White)
      Button(this.isAnimating ? 'Reset' : 'Flip')
        .onClick(() => {
          if (this.isAnimating) {
            this.angleY = 0
            this.isAnimating = false
          } else {
            this.isAnimating = true
            this.angleY = 180
          }
        })
      Button(`doubleSided: ${this.isDoubleSided ? 'true (double-sided)' : 'false (single-sided)'}`)
        .backgroundColor(this.isDoubleSided ? '#4CAF50' : '#F44336')
        .onClick(() => {
          this.isDoubleSided = !this.isDoubleSided
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#1a1a1a')
  }
}