1# 图像效果 2 3设置组件的模糊、阴影、球面效果以及设置图片的图像效果。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 属性 11 12 13| 名称 | 参数类型 | 默认值 | 描述 | 14| -------------------------------- | ---------------------------------------- | ------ | ---------------------------------------- | 15| blur | number | - | 为当前组件添加内容模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>取值范围：[0, +∞)<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 16| backdropBlur | number | - | 为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>取值范围：[0, +∞)<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 17| shadow | [ShadowOptions](#shadowoptions对象说明) \| [ShadowStyle](#shadowstyle10枚举说明)<sup>10+</sup> | - | 为当前组件添加阴影效果。<br/>入参类型为ShadowOptions时，可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。<br/>入参类型为ShadowStyle时，可指定不同阴影样式。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用，ArkTS卡片上不支持参数为 [ShadowStyle](#shadowstyle10枚举说明)类型。 | 18| grayscale | number | 0.0 | 为当前组件添加灰度效果。值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参则0.0图像无变化，入参在0.0和1.0之间时，效果呈线性变化。（百分比)<br/>取值范围：[0, 1]<br/>**说明：** <br/>设置小于0的值时，按值为0处理，设置大于1的值时，按值为1处理。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 19| brightness | number | 1.0 | 为当前组件添加高光效果，入参为高光比例，值为1时没有效果，小于1时亮度变暗，0为全黑，大于1时亮度增加，数值越大亮度越大。<br/>取值范围：[0, +∞)<br/>**说明：** <br/>设置小于0的值时，按值为0处理。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 20| saturate | number | 1.0 | 为当前组件添加饱和度效果，饱和度为颜色中的含色成分和消色成分(灰)的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大，小于1时消色成分越大，饱和度越小。（百分比）<br/>取值范围：[0, +∞)<br/>**说明：** <br/>设置小于0的值时，按值为0处理。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 21| contrast | number | 1.0 | 为当前组件添加对比度效果，入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。（百分比）<br/>取值范围：[0, +∞)<br/>**说明：** <br/>设置小于0的值时，按值为0处理。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 22| invert | number | 0 | 反转输入的图像。入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。（百分比）<br/>取值范围：[0, 1]<br/>**说明：** <br/>设置小于0的值时，按值为0处理。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 23| sepia | number | 0 | 将图像转换为深褐色。入参为图像反转的比例，值为1则完全是深褐色的，值为0图像无变化。 （百分比）<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 24| hueRotate | number \| string | '0deg' | 色相旋转效果，输入参数为旋转角度。<br/>取值范围：(-∞, +∞)<br/>**说明：** <br/>色调旋转360度会显示原始颜色。先将色调旋转180 度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和'90deg'效果一致。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 25| colorBlend <sup>8+</sup> | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | - | 为当前组件添加颜色叠加效果，入参为叠加的颜色。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 26| sphericalEffect<sup>10+</sup> | number | - | 设置组件的图像球面化程度。<br/>取值范围：[0,1]。<br/>**说明：**<br/>1. 如果value等于0则图像保持原样，如果value等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。<br/>`value < 0 `或者` value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。<br/> 2. 如果组件的图像使用异步加载，则不支持球面效果。例如Image组件默认使用异步加载，如果要使用球面效果，就要设置`syncLoad`为`true`，但是这种做法不推荐。`backgroundImage`也是使用异步加载，所以如果设置了`backgroundImage`，不支持球面效果。<br/>3. 如果组件设置了阴影，不支持球面效果。<br>**系统接口：** 此接口为系统接口。 | 27| lightUpEffect<sup>10+</sup> | number | - | 设置组件图像亮起程度。<br/>取值范围：[0,1]。<br/>如果value等于0则图像为全黑，如果value等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。`value < 0` 或者 `value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。 <br>**系统接口：** 此接口为系统接口。 | 28| pixelStretchEffect<sup>10+</sup> | [PixelStretchEffectOptions](ts-types.md#pixelstretcheffectoptions10) | - | 设置组件的图像边缘像素扩展距离。<br/>参数`options`包括上下左右四个方向的边缘像素扩展距离。<br/>**说明：**<br/>1. 如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。<br/>2. 如果距离为负值，表示内缩，但是最终图像大小不变。<br/>内缩方式：<br/>图像根据`options`的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。<br/>图像用边缘像素扩展到原来大小。<br/>3. 对`options`的输入约束：<br/>上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。<br/>所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。<br/>所有异常情况下，显示为{0，0，0，0}效果，即跟原图保持一致。<br>**系统接口：** 此接口为系统接口。 | 29| linearGradientBlur<sup>10+</sup> | <br/>value: number,<br/>{<br/>fractionStops:Array<FractionStop>,<br/>direction:[GradientDirection](ts-appendix-enums.md#gradientdirection)<br/>} <br/> | - | 为当前组件添加内容线性渐变模糊效果，<br/>-value为模糊半径，模糊半径越大越模糊，为0时不模糊。取值范围：[0, 60]<br/>线性梯度模糊包含两个部分fractionStops和direction<br/>-fractionStops数组中保存的每一个二元数组（取值0-1，小于0则为0，大于0则为1）表示[模糊程度, 模糊位置]；模糊位置需严格递增，开发者传入的数据不符合规范会记录日志，渐变模糊数组中二元数组个数必须大于等于2，否则渐变模糊不生效 <br/> -direction为渐变模糊方向，默认值为[GradientDirection](ts-appendix-enums.md#gradientdirection).Bottom <br/>从API version 10开始，该接口支持在ArkTS卡片中使用。 | 30 31## ShadowOptions对象说明 32 33阴影属性集合，用于设置阴影的模糊半径、阴影的颜色、X轴和Y轴的偏移量。 34 35从API version 9开始，该接口支持在ArkTS卡片中使用。 36 37| 名称 | 类型 | 必填 | 说明 | 38| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 39| radius | number \| [Resource](ts-types.md#resource) | 是 | 阴影模糊半径。<br/>取值范围：[0, +∞)<br/>**说明：** <br/>设置小于0的值时，按值为0处理。 | 40| color | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | 否 | 阴影的颜色。<br/>默认为黑色。 | 41| offsetX | number \| [Resource](ts-types.md#resource) | 否 | 阴影的X轴偏移量。<br/>默认为0。 | 42| offsetY | number \| [Resource](ts-types.md#resource) | 否 | 阴影的Y轴偏移量。<br/>默认为0。 | 43 44## ShadowStyle<sup>10+</sup>枚举说明 45 46| 名称 | 描述 | 47| ----------------- | ------ | 48| OUTER_DEFAULT_XS | 超小阴影。 | 49| OUTER_DEFAULT_SM | 小阴影。 | 50| OUTER_DEFAULT_MD | 中阴影。 | 51| OUTER_DEFAULT_LG | 大阴影。 | 52| OUTER_FLOATING_SM | 浮动小阴影。 | 53| OUTER_FLOATING_MD | 浮动中阴影。 | 54 55## 示例 56 57### 示例1 58模糊属性的用法，blur内容模糊，backdropBlur背景模糊。 59```ts 60// xxx.ets 61@Entry 62@Component 63struct BlurEffectsExample { 64 build() { 65 Column({ space: 10 }) { 66 // 对字体进行模糊 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 // 对背景进行模糊 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### 示例2 97设置图片的效果，包括阴影，灰度，高光，饱和度，对比度，图像反转，叠色，色相旋转等。 98```ts 99// xxx.ets 100@Entry 101@Component 102struct ImageEffectsExample { 103 build() { 104 Column({ space: 10 }) { 105 // 添加阴影效果，图片效果不变 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 // 灰度效果0~1，越接近1，灰度越明显 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 // 高光效果，1为正常图片，<1变暗，>1亮度增大 118 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 119 Image($r('app.media.image')).width('90%').height(40).brightness(1.2) 120 121 // 饱和度，原图为1 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 // 对比度，1为原图，>1值越大越清晰，<1值越小越模糊 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 // 图像反转比例 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 // 叠色添加 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 // 深褐色 142 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 143 Image($r('app.media.image')).width('90%').height(40).sepia(0.8) 144 145 // 色相旋转 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### 示例3 156 157设置组件的图像球面效果。 158 159```ts 160// xxx.ets 161@Entry 162@Component 163struct SphericalEffectExample { 164 build() { 165 Stack() { 166 TextInput({ placeholder: "请输入变化范围百分比（[0%,100%]）"}) 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 185效果图如下： 186 187 188 189去掉sphericalEffect的设置，效果如下： 190 191 192 193### 示例4 194 195设置组件的图像渐亮效果。 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 217效果图如下： 218 219 220 221修改lightUpEffect参数值为0.2： 222 223 224 225去掉lightUpEffect的设置，效果如下： 226 227 228 229### 示例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 259去掉lightUpEffect的设置，效果如下： 260 261 262 263### 示例6 264 265设置组件的图像边缘像素扩展效果。 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 287效果图如下： 288 289 290 291去掉pixelStretchEffect的设置，原图效果如下： 292 293 294 295### 示例7 296 297基于示例6，现在把边缘扩展距离改为非正值。 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 318效果图如下: 319 320 321 322跟原图对比发现，效果图分两步实现：<br>1、原图大小缩小，缩小后的大小为原图大小减去像素 323收缩的距离。例如，原图大小为`100*100`，设置了`pixelStretchEffect({top:-10,left:-10, 324right:-10,bottom:-10 })`，则缩小后的大小为`(100-10-10)*(100-10-10)`，即`80*80`。<br>2、使用边缘像素扩展，将图像扩展为原图大小。 325 326### 示例8 327 328设置组件的内容线性渐变模糊效果。 329 330```ts 331// xxx.ets 332@Entry 333@Component 334struct ImageExample1 { 335 private_resource1:Resource = $r('app.media.1') 336 @State image_src: Resource = this.private_resource1 337 build() { 338 Column() { 339 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 340 Row({ space: 5 }) { 341 Image(this.image_src) 342 .linearGradientBlur(60, { fractionStops: [[0,0],[0,0.33],[1,0.66],[1,1]], direction: GradientDirection.Bottom }) 343 } 344 } 345 } 346 } 347} 348 349``` 350 351 352
