1# @ohos.effectKit (图像效果) 2 3图像效果提供处理图像的一些基础能力，包括对当前图像的亮度调节、模糊化、灰度调节、智能取色等。 4 5该模块提供以下图像效果相关的常用功能： 6 7- [Filter](#filter)：效果类，用于添加指定效果到图像源。 8- [Color](#color)：颜色类，用于保存取色的结果。 9- [ColorPicker](#colorpicker)：智能取色器。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import effectKit from '@ohos.effectKit'; 19``` 20 21## effectKit.createEffect 22createEffect(source: image.PixelMap): Filter 23 24通过传入的PixelMap创建Filter实例。 25 26**系统能力：** SystemCapability.Multimedia.Image.Core 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| ------- | ----------------- | ---- | -------- | 32| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 33 34**返回值：** 35 36| 类型 | 说明 | 37| -------------------------------- | -------------- | 38| [Filter](#filter) | 返回不带任何效果的Filter链表的头节点，失败时返回null。 | 39 40**示例：** 41 42```ts 43import image from "@ohos.multimedia.image"; 44import effectKit from "@ohos.effectKit"; 45 46const color = new ArrayBuffer(96); 47let opts : image.InitializationOptions = { 48 editable: true, 49 pixelFormat: 3, 50 size: { 51 height: 4, 52 width: 6 53 } 54} 55image.createPixelMap(color, opts).then((pixelMap) => { 56 let headFilter = effectKit.createEffect(pixelMap); 57}) 58``` 59 60## effectKit.createColorPicker 61 62createColorPicker(source: image.PixelMap): Promise\<ColorPicker> 63 64通过传入的PixelMap创建ColorPicker实例，使用Promise异步回调。 65 66**系统能力：** SystemCapability.Multimedia.Image.Core 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| -------- | ----------- | ---- | -------------------------- | 72| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 73 74**返回值：** 75 76| 类型 | 说明 | 77| ---------------------- | -------------- | 78| Promise\<[ColorPicker](#colorpicker)> | Promise对象。返回创建的ColorPicker实例。 | 79 80**示例：** 81 82```ts 83import image from "@ohos.multimedia.image"; 84import effectKit from "@ohos.effectKit"; 85 86const color = new ArrayBuffer(96); 87let opts : image.InitializationOptions = { 88 editable: true, 89 pixelFormat: 3, 90 size: { 91 height: 4, 92 width: 6 93 } 94} 95 96image.createPixelMap(color, opts).then((pixelMap) => { 97 effectKit.createColorPicker(pixelMap).then(colorPicker => { 98 console.info("color picker=" + colorPicker); 99 }).catch( (reason : BusinessError) => { 100 console.error("error=" + reason.message); 101 }) 102}) 103``` 104 105## effectKit.createColorPicker<sup>10+</sup> 106 107createColorPicker(source: image.PixelMap, region: Array\<number>): Promise\<ColorPicker> 108 109通过传入的PixelMap创建选定取色区域的ColorPicker实例，使用Promise异步回调。 110 111**系统能力：** SystemCapability.Multimedia.Image.Core 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| -------- | ----------- | ---- | -------------------------- | 117| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 118| region | Array\<number> | 是 | 指定图片的取色区域。<br>数组元素个数为4，取值范围为[0, 1]，数组元素分别表示图片区域的左、上、右、下位置，图片最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。数组第三个元素需大于第一个元素，第四个元素需大于第二个元素。<br>此参数不填时，默认值为[0, 0, 1, 1]，表示取色区域为全图。 | 119 120**返回值：** 121 122| 类型 | 说明 | 123| ---------------------- | -------------- | 124| Promise\<[ColorPicker](#colorpicker)> | Promise对象。返回创建的ColorPicker实例。 | 125 126**示例：** 127 128```ts 129import image from "@ohos.multimedia.image"; 130import effectKit from "@ohos.effectKit"; 131 132const color = new ArrayBuffer(96); 133let opts : image.InitializationOptions = { 134 editable: true, 135 pixelFormat: 3, 136 size: { 137 height: 4, 138 width: 6 139 } 140} 141 142image.createPixelMap(color, opts).then((pixelMap) => { 143 effectKit.createColorPicker(pixelMap).then(colorPicker => { 144 console.info("color picker=" + colorPicker); 145 }).catch( (reason : BusinessError) => { 146 console.error("error=" + reason.message); 147 }) 148}) 149``` 150 151## effectKit.createColorPicker 152 153createColorPicker(source: image.PixelMap, callback: AsyncCallback\<ColorPicker>): void 154 155通过传入的PixelMap创建ColorPicker实例，使用callback异步回调。 156 157**系统能力：** SystemCapability.Multimedia.Image.Core 158 159**参数：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| -------- | ------------------ | ---- | -------------------------- | 163| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 |image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 164| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | 是 | 回调函数。返回创建的ColorPicker实例。 | 165 166**示例：** 167 168```ts 169import image from "@ohos.multimedia.image"; 170import effectKit from "@ohos.effectKit"; 171 172const color = new ArrayBuffer(96); 173let opts : image.InitializationOptions = { 174 editable: true, 175 pixelFormat: 3, 176 size: { 177 height: 4, 178 width: 6 179 } 180} 181image.createPixelMap(color, opts).then((pixelMap) => { 182 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 183 if (error) { 184 console.log('Failed to create color picker.'); 185 } else { 186 console.log('Succeeded in creating color picker.'); 187 } 188 }) 189}) 190``` 191 192## effectKit.createColorPicker<sup>10+</sup> 193 194createColorPicker(source: image.PixelMap, region:Array\<number>, callback: AsyncCallback\<ColorPicker>): void 195 196通过传入的PixelMap创建选定取色区域的ColorPicker实例，使用callback异步回调。 197 198**系统能力：** SystemCapability.Multimedia.Image.Core 199 200**参数：** 201 202| 参数名 | 类型 | 必填 | 说明 | 203| -------- | ------------------ | ---- | -------------------------- | 204| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 |image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 205| region | Array\<number> | 是 | 指定图片的取色区域。<br>数组元素个数为4，取值范围为[0, 1]，数组元素分别表示图片区域的左、上、右、下位置，图片最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。数组第三个元素需大于第一个元素，第四个元素需大于第二个元素。<br>此参数不填时，默认值为[0, 0, 1, 1]，表示取色区域为全图。 | 206| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | 是 | 回调函数。返回创建的ColorPicker实例。 | 207 208**示例：** 209 210```ts 211import image from "@ohos.multimedia.image"; 212import effectKit from "@ohos.effectKit"; 213 214const color = new ArrayBuffer(96); 215let opts : image.InitializationOptions = { 216 editable: true, 217 pixelFormat: 3, 218 size: { 219 height: 4, 220 width: 6 221 } 222} 223image.createPixelMap(color, opts).then((pixelMap) => { 224 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 225 if (error) { 226 console.log('Failed to create color picker.'); 227 } else { 228 console.log('Succeeded in creating color picker.'); 229 } 230 }) 231}) 232``` 233 234## Color 235 236颜色类，用于保存取色的结果。 237 238**系统能力：** SystemCapability.Multimedia.Image.Core 239 240| 名称 | 类型 | 可读 | 可写 | 说明 | 241| ------ | ----- | ---- | ---- | ---------------- | 242| red | number | 是 | 否 | 红色分量值，取值范围[0x0, 0xFF]。 | 243| green | number | 是 | 否 | 绿色分量值，取值范围[0x0, 0xFF]。 | 244| blue | number | 是 | 否 | 蓝色分量值，取值范围[0x0, 0xFF]。 | 245| alpha | number | 是 | 否 | 透明通道分量值，取值范围[0x0, 0xFF]。 | 246 247## ColorPicker 248 249取色类，用于从一张图像数据中获取它的主要颜色。在调用ColorPicker的方法前，需要先通过[createColorPicker](#effectkitcreatecolorpicker)创建一个ColorPicker实例。 250 251### getMainColor 252 253getMainColor(): Promise\<Color> 254 255读取图像主色的颜色值，结果写入[Color](#color)里，使用Promise异步回调。 256 257**系统能力：** SystemCapability.Multimedia.Image.Core 258 259**返回值：** 260 261| 类型 | 说明 | 262| :------------- | :---------------------------------------------- | 263| Promise\<[Color](#color)> | Promise对象。返回图像主色对应的颜色值，失败时返回错误信息。 | 264 265**示例：** 266 267```ts 268import image from "@ohos.multimedia.image"; 269import effectKit from "@ohos.effectKit"; 270 271export function test06(): void { 272 const color = new ArrayBuffer(96); 273 let opts: image.InitializationOptions = { 274 editable: true, 275 pixelFormat: 3, 276 size: { 277 height: 4, 278 width: 6 279 } 280 } 281 image.createPixelMap(color, opts).then((pixelMap) => { 282 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 283 if (error) { 284 console.log('Failed to create color picker.'); 285 } else { 286 console.log('Succeeded in creating color picker.'); 287 colorPicker.getMainColor().then(color => { 288 console.log('Succeeded in getting main color.'); 289 console.info(`color[ARGB]=${color.alpha},${color.red},${color.green},${color.blue}`); 290 }) 291 } 292 }) 293 }) 294} 295``` 296 297### getMainColorSync 298 299getMainColorSync(): Color 300 301读取图像主色的颜色值，结果写入[Color](#color)里，使用同步方式返回。 302 303**系统能力：** SystemCapability.Multimedia.Image.Core 304 305**返回值：** 306 307| 类型 | 说明 | 308| :------- | :----------------------------------- | 309| [Color](#color) | Color实例，即图像主色对应的颜色值，失败时返回null。 | 310 311**示例：** 312 313```ts 314import image from "@ohos.multimedia.image"; 315import effectKit from "@ohos.effectKit"; 316 317const color = new ArrayBuffer(96); 318let opts : image.InitializationOptions = { 319 editable: true, 320 pixelFormat: 3, 321 size: { 322 height: 4, 323 width: 6 324 } 325} 326image.createPixelMap(color, opts).then((pixelMap) => { 327 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 328 if (error) { 329 console.log('Failed to create color picker.'); 330 } else { 331 console.log('Succeeded in creating color picker.'); 332 let color = colorPicker.getMainColorSync(); 333 console.log('get main color =' + color); 334 } 335 }) 336}) 337``` 338 339 340### getLargestProportionColor<sup>10+</sup> 341 342getLargestProportionColor(): Color 343 344读取图像占比最多的颜色值，结果写入[Color](#color)里，使用同步方式返回。 345 346**系统能力：** SystemCapability.Multimedia.Image.Core 347 348**返回值：** 349 350| 类型 | 说明 | 351| :------------- | :---------------------------------------------- | 352| [Color](#color) | Color实例，即图像占比最多的颜色值，失败时返回null。 | 353 354**示例：** 355 356```ts 357import image from "@ohos.multimedia.image"; 358import effectKit from "@ohos.effectKit"; 359 360const color = new ArrayBuffer(96); 361let opts : image.InitializationOptions = { 362 editable: true, 363 pixelFormat: 3, 364 size: { 365 height: 4, 366 width: 6 367 } 368} 369image.createPixelMap(color, opts).then((pixelMap) => { 370 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 371 if (error) { 372 console.log('Failed to create color picker.'); 373 } else { 374 console.log('Succeeded in creating color picker.'); 375 let color = colorPicker.getLargestProportionColor(); 376 console.log('get largest proportion color =' + color); 377 } 378 }) 379}) 380``` 381 382 383### getHighestSaturationColor<sup>10+</sup> 384 385getHighestSaturationColor(): Color 386 387读取图像饱和度最高的颜色值，结果写入[Color](#color)里，使用同步方式返回。 388 389**系统能力：** SystemCapability.Multimedia.Image.Core 390 391**返回值：** 392 393| 类型 | 说明 | 394| :------------- | :---------------------------------------------- | 395| [Color](#color) | Color实例，即图像饱和度最高的颜色值，失败时返回null。 | 396 397**示例：** 398 399```ts 400import image from "@ohos.multimedia.image"; 401import effectKit from "@ohos.effectKit"; 402 403const color = new ArrayBuffer(96); 404let opts: image.InitializationOptions = { 405 editable: true, 406 pixelFormat: 3, 407 size: { 408 height: 4, 409 width: 6 410 } 411} 412image.createPixelMap(color, opts).then((pixelMap) => { 413 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 414 if (error) { 415 console.log('Failed to create color picker.'); 416 } else { 417 console.log('Succeeded in creating color picker.'); 418 let color = colorPicker.getHighestSaturationColor(); 419 console.log('get highest saturation color =' + color); 420 } 421 }) 422}) 423``` 424 425 426### getAverageColor<sup>10+</sup> 427 428getAverageColor(): Color 429 430读取图像平均的颜色值，结果写入[Color](#color)里，使用同步方式返回。 431 432**系统能力：** SystemCapability.Multimedia.Image.Core 433 434**返回值：** 435 436| 类型 | 说明 | 437| :------------- | :---------------------------------------------- | 438| [Color](#color) | Color实例，即图像平均的颜色值，失败时返回null。 | 439 440**示例：** 441 442```ts 443import image from "@ohos.multimedia.image"; 444import effectKit from "@ohos.effectKit"; 445 446const color = new ArrayBuffer(96); 447let opts: image.InitializationOptions = { 448 editable: true, 449 pixelFormat: 3, 450 size: { 451 height: 4, 452 width: 6 453 } 454} 455image.createPixelMap(color, opts).then((pixelMap) => { 456 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 457 if (error) { 458 console.log('Failed to create color picker.'); 459 } else { 460 console.log('Succeeded in creating color picker.'); 461 let color = colorPicker.getAverageColor(); 462 console.log('get average color =' + color); 463 } 464 }) 465}) 466``` 467 468 469### isBlackOrWhiteOrGrayColor<sup>10+</sup> 470 471isBlackOrWhiteOrGrayColor(color: number): boolean 472 473判断图像是否为黑白灰颜色，返回true或false。 474 475**系统能力：** SystemCapability.Multimedia.Image.Core 476 477**参数：** 478 479| 参数名 | 类型 | 必填 | 说明 | 480| -------- | ----------- | ---- | -------------------------- | 481| color| number | 是 | 需要判断是否黑白灰色的颜色值，取值范围[0x0, 0xFFFFFFFF]。 | 482 483**返回值：** 484 485| 类型 | 说明 | 486| :------------- | :---------------------------------------------- | 487| boolean | 如果此图像为黑白灰颜色，则返回true；否则返回false。 | 488 489**示例：** 490 491```ts 492import image from "@ohos.multimedia.image"; 493import effectKit from "@ohos.effectKit"; 494 495const color = new ArrayBuffer(96); 496let opts: image.InitializationOptions = { 497 editable: true, 498 pixelFormat: 3, 499 size: { 500 height: 4, 501 width: 6 502 } 503} 504image.createPixelMap(color, opts).then((pixelMap) => { 505 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 506 if (error) { 507 console.log('Failed to create color picker.'); 508 } else { 509 console.log('Succeeded in creating color picker.'); 510 let bJudge = colorPicker.isBlackOrWhiteOrGrayColor(0xFFFFFFFF); 511 console.log('is black or white or gray color[bool](white) =' + bJudge); 512 } 513 }) 514}) 515``` 516 517## Filter 518 519图像效果类，用于将指定的效果添加到输入图像中。在调用Filter的方法前，需要先通过[createEffect](#effectkitcreateeffect)创建一个Filter实例。 520 521### blur 522 523blur(radius: number): Filter 524 525将模糊效果添加到效果链表中，结果返回效果链表的头节点。 526 527**系统能力：** SystemCapability.Multimedia.Image.Core 528 529**参数：** 530 531| 参数名 | 类型 | 必填 | 说明 | 532| ------ | ----------- | ---- | ------------------------------------------------------------ | 533| radius | number | 是 | 模糊半径，单位是像素。模糊效果与所设置的值成正比，值越大效果越明显。 | 534 535**返回值：** 536 537| 类型 | 说明 | 538| :------------- | :---------------------------------------------- | 539| [Filter](#filter) | 返回已添加的图像效果。 | 540 541**示例：** 542 543```ts 544import image from "@ohos.multimedia.image"; 545import effectKit from "@ohos.effectKit"; 546 547const color = new ArrayBuffer(96); 548let opts : image.InitializationOptions = { 549 editable: true, 550 pixelFormat: 3, 551 size: { 552 height: 4, 553 width: 6 554 } 555}; 556image.createPixelMap(color, opts).then((pixelMap) => { 557 let radius = 5; 558 let headFilter = effectKit.createEffect(pixelMap); 559 if (headFilter != null) { 560 headFilter.blur(radius); 561 } 562}) 563``` 564 565 566### brightness 567 568brightness(bright: number): Filter 569 570将高亮效果添加到效果链表中，结果返回效果链表的头节点。 571 572**系统能力：** SystemCapability.Multimedia.Image.Core 573 574**参数：** 575 576| 参数名 | 类型 | 必填 | 说明 | 577| ------ | ----------- | ---- | ------------------------------------------------------------ | 578| bright | number | 是 | 高亮程度，取值范围在0-1之间，取值为0时图像保持不变。 | 579 580**返回值：** 581 582| 类型 | 说明 | 583| :------------- | :---------------------------------------------- | 584| [Filter](#filter) | 返回已添加的图像效果。 | 585 586**示例：** 587 588```ts 589import image from "@ohos.multimedia.image"; 590import effectKit from "@ohos.effectKit"; 591 592const color = new ArrayBuffer(96); 593let opts : image.InitializationOptions = { 594 editable: true, 595 pixelFormat: 3, 596 size: { 597 height: 4, 598 width: 6 599 } 600}; 601image.createPixelMap(color, opts).then((pixelMap) => { 602 let bright = 0.5; 603 let headFilter = effectKit.createEffect(pixelMap); 604 if (headFilter != null) { 605 headFilter.brightness(bright); 606 } 607}) 608``` 609 610 611### grayscale 612 613grayscale(): Filter 614 615将灰度效果添加到效果链表中，结果返回效果链表的头节点。 616 617**系统能力：** SystemCapability.Multimedia.Image.Core 618 619**返回值：** 620 621| 类型 | 说明 | 622| :------------- | :---------------------------------------------- | 623| [Filter](#filter) | 返回已添加的图像效果。 | 624 625**示例：** 626 627```ts 628import image from "@ohos.multimedia.image"; 629import effectKit from "@ohos.effectKit"; 630 631const color = new ArrayBuffer(96); 632let opts : image.InitializationOptions = { 633 editable: true, 634 pixelFormat: 3, 635 size: { 636 height: 4, 637 width: 6 638 } 639}; 640image.createPixelMap(color, opts).then((pixelMap) => { 641 let headFilter = effectKit.createEffect(pixelMap); 642 if (headFilter != null) { 643 headFilter.grayscale(); 644 } 645}) 646``` 647 648 649### getPixelMap 650 651getPixelMap(): [image.PixelMap](js-apis-image.md#pixelmap7) 652 653获取已添加链表效果的源图像的image.PixelMap。 654 655**系统能力：** SystemCapability.Multimedia.Image.Core 656 657**返回值：** 658 659| 类型 | 说明 | 660| :------------- | :---------------------------------------------- | 661| [image.PixelMap](js-apis-image.md#pixelmap7) | 已添加效果的源图像的image.PixelMap。 | 662 663**示例：** 664 665```ts 666import image from "@ohos.multimedia.image"; 667import effectKit from "@ohos.effectKit"; 668 669const color = new ArrayBuffer(96); 670let opts : image.InitializationOptions = { 671 editable: true, 672 pixelFormat: 3, 673 size: { 674 height: 4, 675 width: 6 676 } 677}; 678image.createPixelMap(color, opts).then((pixelMap) => { 679 let pixel = effectKit.createEffect(pixelMap).grayscale().getPixelMap(); 680 console.log('getPixelBytesNumber = ', pixel.getPixelBytesNumber()); 681}) 682``` 683 684
