js-apis-wallpaper.md 21.5 KB
Newer Older
Z
zengyawen 已提交
1 2 3 4 5 6 7 8
# 壁纸

> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:**
> 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。


## 导入模块

Z
zengyawen 已提交
9

Z
zengyawen 已提交
10 11 12 13 14 15 16 17 18
```
import wallpaper from '@ohos.wallpaper';
```


## WallpaperType

定义壁纸类型。

19
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Wallpaper。
Z
zengyawen 已提交
20

21
| 名称 | 说明 |
Z
zengyawen 已提交
22
| -------- | -------- |
23 24
| WALLPAPER_LOCKSCREEN | 锁屏壁纸标识。 |
| WALLPAPER_SYSTEM | 主屏幕壁纸标识。 |
Z
zengyawen 已提交
25 26 27 28 29 30 31 32


## wallpaper.getColors

getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void

获取指定类型壁纸的主要颜色信息。

33
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
34

35 36 37
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
38
  | -------- | -------- | -------- | -------- |
39 40
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
  | callback | AsyncCallback<Array<[RgbaColor](#rgbacolor)>> | 是 | 回调函数,返回壁纸的主要颜色信息。 |
Z
zengyawen 已提交
41

42
**示例:**
Z
zengyawen 已提交
43
  
44
  ```js
Z
zengyawen 已提交
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
  wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
      if (error) {
          console.error(`failed to getColors because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to getColors.`);
  });
  ```


## wallpaper.getColors

getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>>

获取指定类型壁纸的主要颜色信息。

61
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
62

63 64 65
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
66
  | -------- | -------- | -------- | -------- |
67
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
Z
zengyawen 已提交
68

69 70 71
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
72
  | -------- | -------- |
73
  | Promise<Array<[RgbaColor](#rgbacolor)>> | 返回壁纸的主要颜色信息。 |
Z
zengyawen 已提交
74

75
**示例:**
Z
zengyawen 已提交
76
  
77
  ```js
Z
zengyawen 已提交
78 79 80 81 82 83 84 85 86 87 88 89 90 91
  wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
      console.log(`success to getColors.`);
  }).catch((error) => {
      console.error(`failed to getColors because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.getId

getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void

获取指定类型壁纸的ID。

92
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
93

94 95 96
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
97
  | -------- | -------- | -------- | -------- |
98 99
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
  | callback | AsyncCallback<number> | 是 | 回调函数,返回壁纸的ID。如果配置了指定类型的壁纸就返回一个大于等于0的数,否则返回-1。取值范围是-1~2^31-1。 |
Z
zengyawen 已提交
100

101
**示例:**
Z
zengyawen 已提交
102
  
103
  ```js
Z
zengyawen 已提交
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
  wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
      if (error) {
          console.error(`failed to getId because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to getId: ` + JSON.stringify(data));
  });
  ```


## wallpaper.getId

getId(wallpaperType: WallpaperType): Promise<number>

获取指定类型壁纸的ID。

120
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
121 122


123 124 125
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
126
  | -------- | -------- | -------- | -------- |
127
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
Z
zengyawen 已提交
128

129 130 131
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
132
  | -------- | -------- |
133
  | Promise<number> | 壁纸的ID。如果配置了这种壁纸类型的壁纸就返回一个大于等于0的数,否则返回-1。取值范围是-1~2^31-1。 |
Z
zengyawen 已提交
134

135
**示例:**
Z
zengyawen 已提交
136
  
137
  ```js
Z
zengyawen 已提交
138 139 140 141 142 143 144 145 146 147 148 149 150 151
  wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
      console.log(`success to getId: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to getId because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.getMinHeight

getMinHeight(callback: AsyncCallback<number>): void

获取壁纸的最小高度值。

152
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
153

154 155 156
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
157
  | -------- | -------- | -------- | -------- |
158
  | callback | AsyncCallback<number> | 是 | 回调函数,返回壁纸的最小高度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的高度值代替。 |
Z
zengyawen 已提交
159

160
**示例:**
Z
zengyawen 已提交
161
  
162
  ```js
Z
zengyawen 已提交
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
  wallpaper.getMinHeight((error, data) => {
      if (error) {
          console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to getMinHeight: ` + JSON.stringify(data));
  });
  ```


## wallpaper.getMinHeight

getMinHeight(): Promise<number>

获取壁纸的最小高度值。

179
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
180 181


182 183 184
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
185
  | -------- | -------- |
186
  | Promise<number> | 返回壁纸的最小高度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的高度值代替。 |
Z
zengyawen 已提交
187

188
**示例:**
Z
zengyawen 已提交
189
  
190
  ```js
Z
zengyawen 已提交
191 192 193 194 195 196 197 198 199 200 201 202 203 204
  wallpaper.getMinHeight().then((data) => {
      console.log(`success to getMinHeight: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.getMinWidth

getMinWidth(callback: AsyncCallback<number>): void

获取壁纸的最小宽度值。

205
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
206 207


208 209 210
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
211
  | -------- | -------- | -------- | -------- |
212
  | callback | AsyncCallback<number> | 是 | 回调函数,壁纸的最小宽度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的宽度值代替。 |
Z
zengyawen 已提交
213

214
**示例:**
Z
zengyawen 已提交
215
  
216
  ```js
Z
zengyawen 已提交
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
  wallpaper.getMinWidth((error, data) => {
      if (error) {
          console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to getMinWidth: ` + JSON.stringify(data));
  });
  ```


## wallpaper.getMinWidth

getMinWidth(): Promise<number>

获取壁纸的最小宽度值。

233
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
234

235 236 237
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
238
  | -------- | -------- |
239
  | Promise<number> | 壁纸的最小宽度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的宽度值代替。 |
Z
zengyawen 已提交
240

241
**示例:**
Z
zengyawen 已提交
242
  
243
  ```js
Z
zengyawen 已提交
244 245 246 247 248 249 250 251 252 253 254 255 256 257
  wallpaper.getMinWidth().then((data) => {
      console.log(`success to getMinWidth: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.isChangePermitted

isChangePermitted(callback: AsyncCallback<boolean>): void

是否允许应用改变当前用户的壁纸。

258
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
259

260 261 262
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
263
  | -------- | -------- | -------- | -------- |
264
  | callback | AsyncCallback<boolean> | 是 | 回调函数,返回是否允许应用改变当前用户的壁纸。如果允许返回true,否则返回false。 |
Z
zengyawen 已提交
265

266
**示例:**
Z
zengyawen 已提交
267
  
268
  ```js
Z
zengyawen 已提交
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
  wallpaper.isChangePermitted((error, data) => {
      if (error) {
          console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to isChangePermitted: ` + JSON.stringify(data));
  });
  ```


## wallpaper.isChangePermitted

isChangePermitted(): Promise<boolean>

是否允许应用改变当前用户的壁纸。

285
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
286

287 288 289
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
290
  | -------- | -------- |
291
  | Promise<boolean> | 返回是否允许应用改变当前用户的壁纸。如果允许返回true,否则返回false。 |
Z
zengyawen 已提交
292

293
**示例:**
Z
zengyawen 已提交
294
  
295
  ```js
Z
zengyawen 已提交
296 297 298 299 300 301 302 303 304 305 306 307 308 309
  wallpaper.isChangePermitted().then((data) => {
      console.log(`success to isChangePermitted: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.isOperationAllowed

isOperationAllowed(callback: AsyncCallback<boolean>): void

是否允许用户设置壁纸。

310
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
311

312 313 314
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
315
  | -------- | -------- | -------- | -------- |
316
  | callback | AsyncCallback<boolean> | 是 | 回调函数,返回是否允许用户设置壁纸。如果允许返回true,否则返回false。 |
Z
zengyawen 已提交
317

318
**示例:**
Z
zengyawen 已提交
319
  
320
  ```js
Z
zengyawen 已提交
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
  wallpaper.isOperationAllowed((error, data) => {
      if (error) {
          console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
  });
  ```


## wallpaper.isOperationAllowed

isOperationAllowed(): Promise<boolean>

是否允许用户设置壁纸。

337
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
338

339 340 341
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
342
  | -------- | -------- |
343
  | Promise<boolean> | 异步回调函数,返回是否允许用户设置壁纸。如果允许返回true,否则返回false。 |
Z
zengyawen 已提交
344

345
**示例:**
Z
zengyawen 已提交
346
  
347
  ```js
Z
zengyawen 已提交
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
  wallpaper.isOperationAllowed().then((data) => {
      console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.reset

reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void

移除指定类型的壁纸,恢复为默认显示的壁纸。

**需要权限**:ohos.permission.SET_WALLPAPER

364
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
365

366 367 368
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
369
  | -------- | -------- | -------- | -------- |
370 371
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
  | callback | AsyncCallback<void> | 是 | 回调函数,调用成功则返回是否移除成功的结果,调用失败则返回error信息。 |
Z
zengyawen 已提交
372

373
**示例:**
Z
zengyawen 已提交
374
  
375
  ```js
376
  wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
Z
zengyawen 已提交
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393
      if (error) {
          console.error(`failed to reset because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to reset.`);
  });
  ```


## wallpaper.reset

reset(wallpaperType: WallpaperType): Promise<void>

移除指定类型的壁纸,恢复为默认显示的壁纸。

**需要权限:**ohos.permission.SET_WALLPAPER

394
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
395

396 397 398
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
399
  | -------- | -------- | -------- | -------- |
400
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
Z
zengyawen 已提交
401

402 403 404
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
405
  | -------- | -------- |
406
  | Promise<void> | 调用成功则返回是否移除成功的结果,调用失败则返回error信息。 |
Z
zengyawen 已提交
407

408
**示例:**
Z
zengyawen 已提交
409
  
410
  ```js
411
  wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
Z
zengyawen 已提交
412 413 414 415 416 417 418 419 420
      console.log(`success to reset.`);
  }).catch((error) => {
      console.error(`failed to reset because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.setWallpaper

421
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
Z
zengyawen 已提交
422 423 424 425 426

将指定资源设置为指定类型的壁纸。

**需要权限:** ohos.permission.SET_WALLPAPER

427
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
428

429 430 431
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
432
  | -------- | -------- | -------- | -------- |
433
  | source | string \|[PixelMap](js-apis-image.md#pixelmap7) |  | JPEG或PNG文件的Uri路径,或者PNG格式文件的位图。 |
Z
zengyawen 已提交
434 435
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
  | callback | AsyncCallback<void> | 是 | 回调函数,调用成功则返回是返回设置的结果,调用失败则返回error信息。 |
Z
zengyawen 已提交
436

437
**示例:**
Z
zengyawen 已提交
438
  
439
  ```js
440
  // source类型为string
Z
zengyawen 已提交
441
  let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
442
  wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {    
Z
zengyawen 已提交
443 444 445 446 447 448 449
      if (error) {        
          console.error(`failed to setWallpaper because: ` + JSON.stringify(error));       
          return;   
      }    
      console.log(`success to setWallpaper.`);
  });
  
450
  // source类型为image.PixelMap
Z
zengyawen 已提交
451 452 453 454 455 456 457 458 459
  import image from '@ohos.multimedia.image';
  let imageSource = image.createImageSource("file://" + wallpaperPath);
  let opts = {
      "desiredSize": {
          "height": 3648,
          "width": 2736
      }
  };
  imageSource.createPixelMap(opts).then((pixelMap) => {      
460
      wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {    
Z
zengyawen 已提交
461 462 463 464 465 466 467 468 469 470 471 472 473 474
          if (error) {       
              console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
              return;
          }    
          console.log(`success to setWallpaper.`);
      });
  }).catch((error) => {       
      console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
  });
  ```


## wallpaper.setWallpaper

475
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>
Z
zengyawen 已提交
476 477 478 479 480

将指定资源设置为指定类型的壁纸。

**需要权限**:ohos.permission.SET_WALLPAPER

481
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
482

483 484 485
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
486
  | -------- | -------- | -------- | -------- |
487
  | source | string \|[PixelMap](js-apis-image.md#pixelmap7) | 是 | JPEG或PNG文件的Uri路径,或者PNG格式文件的位图。 |
Z
zengyawen 已提交
488
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
Z
zengyawen 已提交
489

490 491 492
**返回值:**

  | 类型 | 说明 |
Z
zengyawen 已提交
493
  | -------- | -------- |
494
  | Promise<void> | 调用成功则返回是返回设置的结果,调用失败则返回error信息。 |
Z
zengyawen 已提交
495

496
**示例:**
Z
zengyawen 已提交
497
  
498
  ```js
499
  // source类型为string
Z
zengyawen 已提交
500
  let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
501
  wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
Z
zengyawen 已提交
502 503 504 505 506
      console.log(`success to setWallpaper.`);
  }).catch((error) => {
      console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
  });
  
507
  // source类型为image.PixelMap
Z
zengyawen 已提交
508 509 510 511 512 513 514 515 516
  import image from '@ohos.multimedia.image';
  let imageSource = image.createImageSource("file://" + wallpaperPath);
  let opts = {
      "desiredSize": {
          "height": 3648,
          "width": 2736
      }
  };
  imageSource.createPixelMap(opts).then((pixelMap) => {      
517
      wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
Z
zengyawen 已提交
518 519 520 521 522 523 524 525
          console.log(`success to setWallpaper.`);
      }).catch((error) => {
          console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
      });
  }).catch((error) => {       
      console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
  });
  ```
526

527 528 529 530 531 532 533 534
## wallpaper.getFile<sup>8+</sup>

getFile(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): void

获取指定类型的壁纸文件。

**需要权限**:ohos.permission.SET_WALLPAPER、ohos.permission.READ_USER_STORAGE

535
**系统能力**: SystemCapability.MiscServices.Wallpaper
536

537 538 539
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
540
  | -------- | -------- | -------- | -------- |
541 542
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
  | callback | AsyncCallback&lt;number&gt; | 是 | 回调函数,调用成功则返回壁纸文件描述符ID,调用失败则返回error信息。 |
543

544
**示例:**
545
  
546
  ```js
547 548 549 550 551 552 553 554
  wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
      if (error) {
          console.error(`failed to getFile because: ` + JSON.stringify(error));
          return;
      }
      console.log(`success to getFile: ` + JSON.stringify(data));
  });
  ```
555

556 557 558 559 560 561 562 563
## wallpaper.getFile<sup>8+</sup>

getFile(wallpaperType: WallpaperType): Promise&lt;number&gt;

获取指定类型的壁纸文件。

**需要权限:** ohos.permission.SET_WALLPAPER、ohos.permission.READ_USER_STORAGE

564
**系统能力**: SystemCapability.MiscServices.Wallpaper
565

566 567 568
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
569
  | -------- | -------- | -------- | -------- |
570
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
571

572 573 574
**返回值:**

  | 类型 | 说明 |
575
  | -------- | -------- |
576
  | Promise&lt;number&gt; | 调用成功则返回壁纸文件描述符ID,调用失败则返回error信息。 |
577

578
**示例:**
579
  
580
  ```js
581 582 583 584 585 586
  wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
      console.log(`success to getFile: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to getFile because: ` + JSON.stringify(error));
  });
  ```
Z
zengyawen 已提交
587 588


589 590 591 592 593 594 595 596 597 598 599 600 601 602 603
## wallpaper.getPixelMap

getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback&lt;image.PixelMap&gt;): void;

获取壁纸图片的像素图。

**需要权限**:ohos.permission.GET_WALLPAPER、ohos.permission.READ_USER_STORAGE

**系统能力**: SystemCapability.MiscServices.Wallpaper

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |
604
  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数,调用成功则返回是否获取成功的结果,调用失败则返回error信息。 |
605 606 607 608

**示例:**
  
  ```js
609
  wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (err, data) {
610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635
      console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem err : ' + JSON.stringify(err));
      console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem data : ' + JSON.stringify(data));
  });
  ```


## wallpaper.getPixelMap

getPixelMap(wallpaperType: WallpaperType): Promise&lt;image.PixelMap&gt;

获取壁纸图片的像素图。

**需要权限**:ohos.permission.GET_WALLPAPER、ohos.permission.READ_USER_STORAGE

**系统能力**: SystemCapability.MiscServices.Wallpaper

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | wallpaperType | [WallpaperType](#wallpapertype) | 是 | 壁纸类型。 |

**返回值:**

  | 类型 | 说明 |
  | -------- | -------- |
636
  | Promise&lt;void&gt; | 调用成功则返回是否获取成功的结果,调用失败则返回error信息。 |
637 638 639 640 641 642 643 644 645 646 647 648 649 650

**示例:**
  
  ```js
  wallpaper.getPixelMap(WALLPAPER_SYSTEM).then((data) => {
      console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem data : ' + data);
      console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem data : ' + JSON.stringify(data));
  }).catch((err) => {
      console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem err : ' + err);
      console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem err : ' + JSON.stringify(err));
  });
  ```


Z
zengyawen 已提交
651 652 653 654 655 656
## wallpaper.on('colorChange')

on(type: 'colorChange', callback: (colors: Array&lt;RgbaColor&gt;, wallpaperType: WallpaperType) =&gt; void): void

订阅壁纸颜色变化结果上报事件。

657
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
658

659 660 661
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
662
  | -------- | -------- | -------- | -------- |
Z
zengyawen 已提交
663 664
  | type | string | 是 | 取值为'colorChange',表示壁纸颜色变化结果上报事件。 |
  | callback | function | 是 | 壁纸颜色变化触发该回调方法,返回壁纸类型和壁纸的主要颜色信息。<br/>-&nbsp;colors<br/>&nbsp;&nbsp;壁纸的主要颜色信息,其类型见[RgbaColor](#rgbacolor)。<br/>-&nbsp;wallpaperType<br/>&nbsp;&nbsp;壁纸类型。 |
Z
zengyawen 已提交
665

666
**示例:**
Z
zengyawen 已提交
667
  
668
  ```js
Z
zengyawen 已提交
669 670 671 672 673 674 675 676 677 678 679 680 681
  let listener = (colors, wallpaperType) => {
      console.log(`wallpaper color changed.`);
  };
  wallpaper.on('colorChange', listener);
  ```


## wallpaper.off('colorChange')

off(type: 'colorChange', callback?: (colors: Array&lt;RgbaColor&gt;, wallpaperType: WallpaperType) =&gt; void): void

取消订阅壁纸颜色变化结果上报事件。

682
**系统能力**: SystemCapability.MiscServices.Wallpaper
Z
zengyawen 已提交
683

684 685 686
**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
Z
zengyawen 已提交
687
  | -------- | -------- | -------- | -------- |
688 689
  | type | string | 是 | 取值为'colorChange',表示取消订阅壁纸颜色变化结果上报事件。 |
  | callback | function | 否 | &nbsp;&nbsp;表示取消壁纸颜色变化结果上报,不填写该参数则取消订阅该type对应的所有回调。<br/>-&nbsp;colors<br/>&nbsp;&nbsp;壁纸的主要颜色信息,其类型见[RgbaColor](#rgbacolor)。<br/>-&nbsp;wallpaperType<br/>&nbsp;&nbsp;壁纸类型。 |
Z
zengyawen 已提交
690

691
**示例:**
Z
zengyawen 已提交
692
  
693
  ```js
Z
zengyawen 已提交
694 695 696 697 698 699 700 701 702 703 704 705 706
  let listener = (colors, wallpaperType) => {
      console.log(`wallpaper color changed.`);
  };
  wallpaper.on('colorChange', listener);
  // 取消订阅listener
  wallpaper.off('colorChange', listener);
  // 取消所有'colorChange'类型的订阅
  wallpaper.off('colorChange');
  ```


## RgbaColor

707
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Wallpaper。
Z
zengyawen 已提交
708

709
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
Z
zengyawen 已提交
710
| -------- | -------- | -------- | -------- | -------- |
711 712 713 714
| red | number | 是 | 是 | 表示红色值,范围为&nbsp;0&nbsp;&nbsp;255。 |
| green | number | 是 | 是 | 表示绿色值,范围为&nbsp;0&nbsp;&nbsp;255。 |
| blue | number | 是 | 是 | 表示蓝色值,范围为&nbsp;0&nbsp;&nbsp;255。 |
| alpha | number | 是 | 是 | 表示&nbsp;alpha&nbsp;值,范围为&nbsp;0&nbsp;&nbsp;255。 |