1# Image Effects 2 3Image effects include blur, shadow, spherical effect, and much more. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Attributes 11 12 13| Name | Type | Default Value | Description | 14| -------------------------------- | ---------------------------------------- | ------ | ---------------------------------------- | 15| blur | number | - | Foreground blur radius of the component. A greater value indicates a higher blur degree. If the value is **0**, the content is not blurred.<br>Value range: [0, +∞)<br>Since API version 9, this API is supported in ArkTS widgets.| 16| backdropBlur | number | - | Background blur radius of the component. A greater value indicates a higher blur degree. If the value is **0**, the background is not blurred.<br>Value range: [0, +∞)<br>Since API version 9, this API is supported in ArkTS widgets.| 17| shadow | [ShadowOptions](#shadowoptions) \| [ShadowStyle](#shadowstyle10)<sup>10+</sup> | - | Shadow of the component.<br>When the value type is **ShadowOptions**, the blur radius, shadow color, and offset along the x-axis and y-axis can be specified.<br>When the value type is **ShadowStyle**, the shadow style can be specified.<br>Since API version 9, this API is supported in ArkTS widgets, except that the [ShadowStyle](#shadowstyle10) type is not supported.| 18| grayscale | number | 0.0 | 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. The unit is percentage.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.<br>Since API version 9, this API is supported in ArkTS widgets.| 19| brightness | number | 1.0 | Brightness of the component. The value **1** indicates no effects. The value **0** indicates the complete darkness. If the value is less than **1**, the brightness decreases. If the value is greater than **1**, the brightness increases. A greater value indicates a higher brightness.<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.<br>Since API version 9, this API is supported in ArkTS widgets.| 20| saturate | number | 1.0 | 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 source 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. The unit is percentage.<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.<br>Since API version 9, this API is supported in ArkTS widgets.| 21| contrast | number | 1.0 | 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 is. If the value is **0**, the image becomes all gray. The unit is percentage.<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.<br>Since API version 9, this API is supported in ArkTS widgets.| 22| invert | number | 0 | Inversion ratio of the component. If the value is **1**, the component is completely inverted. If the value is **0**, the component remains unchanged. The unit is percentage.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.<br>Since API version 9, this API is supported in ArkTS widgets.| 23| sepia | number | 0 | Sepia conversion ratio of the component. If the value is **1**, the image is completely sepia. If the value is **0**, the component remains unchanged. The unit is percentage.<br>Since API version 9, this API is supported in ArkTS widgets.| 24| hueRotate | number \| string | '0deg' | Hue rotation angle of the component.<br>Value range: (-∞, +∞)<br>**NOTE**<br>A rotation of 360 degrees leaves the color unchanged. A rotation of 180 degrees and then -180 degrees also leaves the color unchanged. When the data type is number, the value 90 is equivalent to **'90deg'**.<br>Since API version 9, this API is supported in ArkTS widgets.| 25| colorBlend <sup>8+</sup> | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | - | Color to blend with the component.<br>Since API version 9, this API is supported in ArkTS widgets.| 26| sphericalEffect<sup>10+</sup> | number | - | Spherical degree of the component.<br>The value ranges from 0 to 1.<br>**NOTE**<br>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 greater value indicates a higher spherical degree.<br>A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.<br> 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.<br>3. If the shadow effect is set for a component, the spherical effect is not supported.<br>This is a system API.| 27| lightUpEffect<sup>10+</sup> | number | - | Light up degree of the component.<br>The value ranges from 0 to 1.<br>If the value is **0**, the component is dark. If the value is **1**, the component is fully illuminated. Between 0 and 1, a greater value indicates higher luminance. A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.<br>This is a system API.| 28| pixelStretchEffect<sup>10+</sup> | [PixelStretchEffectOptions](ts-types.md#pixelstretcheffectoptions10) | - | Pixel stretch effect options.<br>The **options** parameter includes the length by which a pixel is stretched toward the four edges.<br>**NOTE**<br>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.<br>2. 2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:<br> <br>(1) The image shrinks from the four edges by the absolute value of length set through **options**.<br>(2) The image is stretched back to the original size with edge pixels.<br>3. Constraints on **options**:<br>(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.<br>(2) The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.<br>(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.<br>This is a system API.| 29| linearGradientBlur<sup>10+</sup> | <br>value: number,<br>{<br>fractionStops:Array\<FractionStop>,<br>direction:[GradientDirection](ts-appendix-enums.md#gradientdirection)<br>} <br> | - | Linear gradient blur for the component.<br>- **value**: blur radius. A greater value indicates a higher blur degree. If the value is 0, the content is not blurred. Value range: [0, 60]<br>Linear gradient blur consists of two parts: **fractionStops** and **direction**.<br>- **fractionStops**: gradient blur stops. The value is a set of binary arrays, each of which indicates [blur degree, blur position] and consists of numbers ranging from 0 to 1 (those less than 0 evaluate to **0**, and those greater than 1 evaluate to **1**). The blur positions in the arrays must be in 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.<br> - **direction**: gradient blur direction. The default value is **[GradientDirection](ts-appendix-enums.md#gradientdirection).Bottom**.<br>Since API version 10, this API is supported in ArkTS widgets.| 30 31## ShadowOptions 32 33Provides the shadow attributes, including the blur radius, color, and offset along the x-axis and y-axis. 34 35Since API version 9, this API is supported in ArkTS widgets. 36 37| Name | Type | Mandatory | Description | 38| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 39| radius | number \| [Resource](ts-types.md#resource) | Yes | Blur radius of the shadow.<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.| 40| color | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | No | Color of the shadow.<br>The default color is black. | 41| offsetX | number \| [Resource](ts-types.md#resource) | No | Offset of the shadow along the x-axis.<br>The default value is **0**. | 42| offsetY | number \| [Resource](ts-types.md#resource) | No | Offset of the shadow along the y-axis.<br>The default value is **0**. | 43 44## ShadowStyle<sup>10+</sup> 45 46| Name | Description | 47| ----------------- | ------ | 48| OUTER_DEFAULT_XS | Mini shadow. | 49| OUTER_DEFAULT_SM | Small shadow. | 50| OUTER_DEFAULT_MD | Medium shadow. | 51| OUTER_DEFAULT_LG | Large shadow. | 52| OUTER_FLOATING_SM | Floating small shadow.| 53| OUTER_FLOATING_MD | Floating medium shadow.| 54 55## Example 56 57### Example 1 58Use **blur** to apply a foreground blur effect and **backdropBlur** to apply a background blur effect. 59```ts 60// xxx.ets 61@Entry 62@Component 63struct BlurEffectsExample { 64 build() { 65 Column({ space: 10 }) { 66 // Blur the font. 67 Text('font blur').fontSize(15).fontColor(0xCCCCCC).width('90%') 68 Flex({ alignItems: ItemAlign.Center }) { 69 Text('original text').margin(10) 70 Text('blur text') 71 .blur(1).margin(10) 72 Text('blur text') 73 .blur(2).margin(10) 74 Text('blur text') 75 .blur(3).margin(10) 76 }.width('90%').height(40) 77 .backgroundColor(0xF9CF93) 78 79 80 // Blur the background. 81 Text('backdropBlur').fontSize(15).fontColor(0xCCCCCC).width('90%') 82 Text() 83 .width('90%') 84 .height(40) 85 .fontSize(16) 86 .backdropBlur(3) 87 .backgroundImage('/pages/attrs/image/image.jpg') 88 .backgroundImageSize({ width: 1200, height: 160 }) 89 }.width('100%').margin({ top: 5 }) 90 } 91} 92``` 93 94 95 96### Example 2 97Apply different image effects. 98```ts 99// xxx.ets 100@Entry 101@Component 102struct ImageEffectsExample { 103 build() { 104 Column({ space: 10 }) { 105 // Apply the shadow effect. 106 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 107 Image($r('app.media.image')) 108 .width('90%') 109 .height(40) 110 .shadow({ radius: 10, color: Color.Green, offsetX: 20, offsetY: 30 }) 111 112 // 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. 113 Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%') 114 Image($r('app.media.image')).width('90%').height(40).grayscale(0.3) 115 Image($r('app.media.image')).width('90%').height(40).grayscale(0.8) 116 117 // 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. 118 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 119 Image($r('app.media.image')).width('90%').height(40).brightness(1.2) 120 121 // Apply the saturation effect. If the value is 1, the source image is displayed. 122 Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%') 123 Image($r('app.media.image')).width('90%').height(40).saturate(2.0) 124 Image($r('app.media.image')).width('90%').height(40).saturate(0.7) 125 126 // 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. 127 Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%') 128 Image($r('app.media.image')).width('90%').height(40).contrast(2.0) 129 Image($r('app.media.image')).width('90%').height(40).contrast(0.8) 130 131 // Invert the image. 132 Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%') 133 Image($r('app.media.image')).width('90%').height(40).invert(0.2) 134 Image($r('app.media.image')).width('90%').height(40).invert(0.8) 135 136 // Apply the color blend effect. 137 Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%') 138 Image($r('app.media.image')).width('90%').height(40).colorBlend(Color.Green) 139 Image($r('app.media.image')).width('90%').height(40).colorBlend(Color.Blue) 140 141 // Convert the image color to sepia. 142 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 143 Image($r('app.media.image')).width('90%').height(40).sepia(0.8) 144 145 // Apply the hue rotation effect. 146 Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%') 147 Image($r('app.media.image')).width('90%').height(40).hueRotate(90) 148 }.width('100%').margin({ top: 5 }) 149 } 150} 151``` 152 153 154 155### Example 3 156 157Apply a spherical effect to a component to make it appear spherized. 158 159```ts 160// xxx.ets 161@Entry 162@Component 163struct SphericalEffectExample { 164 build() { 165 Stack() { 166 TextInput({placeholder: "Enter a percentage."}) 167 .width('50%') 168 .height(35) 169 .type(InputType.Number) 170 .enterKeyType(EnterKeyType.Done) 171 .caretColor(Color.Red) 172 .placeholderColor(Color.Blue) 173 .placeholderFont({ 174 size: 20, 175 style: FontStyle.Italic, 176 weight: FontWeight.Bold 177 }) 178 .sphericalEffect(0.5) 179 }.alignContent(Alignment.Center).width("100%").height("100%") 180 } 181} 182 183``` 184 185Below is how the component looks with the spherical effect applied: 186 187 188 189Below is how the component looks without the spherical effect applied: 190 191 192 193### Example 4 194 195Apply a light up effect to a component. 196 197```ts 198// xxx.ets 199@Entry 200@Component 201struct LightUpExample { 202 build() { 203 Stack() { 204 Text('This is the text content with letterSpacing 0.') 205 .letterSpacing(0) 206 .fontSize(12) 207 .border({ width: 1 }) 208 .padding(10) 209 .width('50%') 210 .lightUpEffect(0.6) 211 }.alignContent(Alignment.Center).width("100%").height("100%") 212 } 213} 214 215``` 216 217Below is how the component looks with **lightUpEffect** set to **0.6**: 218 219 220 221Below is how the component looks with **lightUpEffect** set to **0.2**: 222 223 224 225Below is how the component looks without the light up effect applied: 226 227 228 229### Example 5 230 231```ts 232// xxx.ets 233@Entry 234@Component 235struct LightUpExample { 236 @State isLunar: boolean = false 237 private selectedDate: Date = new Date('2028-08-08') 238 build() { 239 Stack() { 240 DatePicker({ 241 start: new Date('1970-1-1'), 242 end: new Date('2100-1-1'), 243 selected: this.selectedDate 244 }) 245 .lunar(this.isLunar) 246 .onChange((value: DatePickerResult) => { 247 this.selectedDate.setFullYear(value.year as number, value.month, value.day) 248 console.info('select current date is: ' + JSON.stringify(value)) 249 }) 250 .lightUpEffect(0.6) 251 252 }.alignContent(Alignment.Center).width("100%").height("100%") 253 } 254} 255``` 256 257 258 259Below is how the component looks without the light up effect applied: 260 261 262 263### Example 6 264 265Apply a pixel stretch effect to a component. 266 267```ts 268// xxx.ets 269@Entry 270@Component 271struct PixelStretchExample { 272 build() { 273 Stack() { 274 Text('This is the text content with letterSpacing 0.') 275 .letterSpacing(0) 276 .fontSize(12) 277 .border({ width: 1 }) 278 .padding(10) 279 .width('50%') 280 .pixelStretchEffect({top:10,left:10,right:10,bottom:10 }) 281 }.alignContent(Alignment.Center).width("100%").height("100%") 282 } 283} 284 285``` 286 287Below is how the component looks with **lightUpEffect** set to **0.6**: 288 289 290 291Below is how the component looks without the pixel stretch effect applied: 292 293 294 295### Example 7 296 297Based on Example 6, change the length values of the pixel stretch effect to negative: 298 299```ts 300// xxx.ets 301@Entry 302@Component 303struct PixelStretchExample { 304 build() { 305 Stack() { 306 Text('This is the text content with letterSpacing 0.') 307 .letterSpacing(0) 308 .fontSize(12) 309 .border({ width: 1 }) 310 .padding(10) 311 .width('50%') 312 .pixelStretchEffect({top:-10,left:-10,right:-10,bottom:-10 }) 313 }.alignContent(Alignment.Center).width("100%").height("100%") 314 } 315} 316``` 317 318Below is how the component looks: 319 320 321 322Compared with the original image, the effect drawing is implemented in two steps: 323 3241. The image size is reduced. The resultant size is the original image size minus 325the lengths by which the pixels shrink. For example, if the original image size is 100 x 100 and **pixelStretchEffect({top:-10,left:-10,** 326**right:-10,bottom:-10})** is set, the resultant size is (100-10-10) x (100-10-10), that is, 8080. 3272. Edge pixels are stretched to restore the image to its original size. 328 329### Example 8 330 331Apply a linear gradient blur effect to a component. 332 333```ts 334// xxx.ets 335@Entry 336@Component 337struct ImageExample1 { 338 private_resource1:Resource = $r('app.media.1') 339 @State image_src: Resource = this.private_resource1 340 build() { 341 Column() { 342 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 343 Row({ space: 5 }) { 344 Image(this.image_src) 345 .linearGradientBlur(60, { fractionStops: [[0,0],[0,0.33],[1,0.66],[1,1]], direction: GradientDirection.Bottom }) 346 } 347 } 348 } 349 } 350} 351 352``` 353 354 355
