Image Effects (System API)

Image effects include blur, shadow, spherical effect, and much more.

NOTE

The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

This topic describes only system APIs provided by the module. For details about its public APIs, see Image Effects.

sphericalEffect10+

sphericalEffect(value: number)

Spherical degree of the component.

System capability: SystemCapability.ArkUI.ArkUI.Full

System API: This is a system API.

Parameters

Name Type Mandatory Description
value number Yes Spherical degree of the component.
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 evaluates to the value 0. A value greater than 1 evaluates to the value 1.
2. If a component image is loaded asynchronously, the spherical effect is not supported. For example, the <Image> component uses asynchronous loading by default, which means that syncLoad must be set to true to apply the spherical effect. However, this setting is not recommended. Asynchronous loading is also used for backgroundImage. Therefore, if backgroundImage is set, the spherical effect is not supported.
3. If the shadow effect is set for a component, the spherical effect is not supported.

lightUpEffect10+

lightUpEffect(value: number)

Light up degree of the component.

System capability: SystemCapability.ArkUI.ArkUI.Full

System API: This is a system API.

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 evaluates to the value 0. A value greater than 1 evaluates to the value 1.

pixelStretchEffect10+

pixelStretchEffect(options: PixelStretchEffectOptions)

Pixel stretch effect options.

System capability: SystemCapability.ArkUI.ArkUI.Full

System API: This is a system API.

Parameters

Name Type Mandatory Description
options PixelStretchEffectOptions Yes Pixel stretch effect options.
The options parameter 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. 2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:

(1) The image shrinks from the four edges by the absolute value of length set through options.
(2) The image is stretched back to the original size with edge pixels.
\3. Constraints on options:
(1) 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.
(2) The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.
(3) If the input value is invalid, the image is displayed as {0, 0, 0, 0}, that is, the image is the same as the original image.

Example

Example 1

Apply a spherical effect to a component to make it appear spherized.

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

textInputSpherical1

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

textInputSpherical2

Example 2

Apply a light up effect to a component.

// 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 lightUpEffect set to 0.6:

textLightUp3

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

textLightUp2

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

textLightUp1

Example 3

// xxx.ets
@Entry
@Component
struct LightUpExample {
  @State isLunar: boolean = false
  private selectedDate: Date = new Date('2028-08-08')
  build() {
    Stack() {
      DatePicker({
        start: new Date('1970-1-1'),
        end: new Date('2100-1-1'),
        selected: this.selectedDate
      })
        .lunar(this.isLunar)
        .onDateChange((value: Date) => {
          this.selectedDate = value
          console.info('select current date is: ' + value.toString())
        })
        .lightUpEffect(0.6)

    }.alignContent(Alignment.Center).width("100%").height("100%")
  }
}

datePickerLightUp2

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

datePickerLightUp1

Example 4

You can apply a pixel stretch effect to a component.

// 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 lightUpEffect set to 0.6:

textPixelStretch1

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

textPixelStretch2

Example 5

Based on Example 4, change the length values of the pixel stretch effect to negative:

// 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)
        .width('50%')
        .pixelStretchEffect({top:-10,left:-10,right:-10,bottom:-10 })
    }.alignContent(Alignment.Center).width("100%").height("100%")
  }
}

Below is how the component looks:

textPixelStretch3

Compared with the original image, the effect drawing is implemented in two steps:
1. The image size is reduced. The resultant size is the original image size minus the lengths by which the pixels shrink. For example, if the original image size is 100 x 100 and pixelStretchEffect({top:-10,left:-10, right:-10,bottom:-10}) is set, the resultant size is (100-10-10) x (100-10-10), that is, 8080.
2. Edge pixels are stretched to restore the image to its original size.