1# @ohos.wallpaper (Wallpaper) 2 3The **wallpaper** module is a system service module in OpenHarmony that provides the wallpaper management service. You can use the APIs of this module to show, set, and switch between wallpapers. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12 13```js 14import wallpaper from '@ohos.wallpaper'; 15``` 16 17## WallpaperType<sup>7+</sup> 18 19Enumerates the wallpaper types. 20 21**System capability**: SystemCapability.MiscServices.Wallpaper 22 23| Name| Value|Description| 24| -------- | -------- |-------- | 25| WALLPAPER_SYSTEM | 0 |Home screen wallpaper.| 26| WALLPAPER_LOCKSCREEN | 1 |Lock screen wallpaper.| 27 28 29## RgbaColor<sup>9+</sup> 30 31Defines the RGBA color space for the wallpaper. 32 33**System capability**: SystemCapability.MiscServices.Wallpaper 34 35**System API**: This is a system API. 36 37| Name| Type| Readable| Writable| Description| 38| -------- | -------- | -------- | -------- | -------- | 39| red | number | Yes| Yes| Red color. The value ranges from 0 to 255.| 40| green | number | Yes| Yes| Green color. The value ranges from 0 to 255.| 41| blue | number | Yes| Yes| Blue color. The value ranges from 0 to 255.| 42| alpha | number | Yes| Yes| Alpha value. The value ranges from 0 to 255.| 43 44 45## wallpaper.getColorsSync<sup>9+</sup> 46 47getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor> 48 49Obtains the main color information of the wallpaper of the specified type. 50 51**System capability**: SystemCapability.MiscServices.Wallpaper 52 53**System API**: This is a system API. 54 55**Parameters** 56 57| Name| Type| Mandatory| Description| 58| -------- | -------- | -------- | -------- | 59| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 60 61**Return value** 62 63| Type| Description| 64| -------- | -------- | 65| Array<[RgbaColor](#rgbacolor)> | Promise used to return the main color information of the wallpaper.| 66 67**Example** 68 69```js 70try { 71 let colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM); 72 console.log(`success to getColorsSync: ${JSON.stringify(colors)}`); 73} catch (error) { 74 console.error(`failed to getColorsSync because: ${JSON.stringify(error)}`); 75} 76``` 77 78## wallpaper.getMinHeightSync<sup>9+</sup> 79 80getMinHeightSync(): number 81 82Obtains the minimum height of this wallpaper. 83 84**System capability**: SystemCapability.MiscServices.Wallpaper 85 86**System API**: This is a system API. 87 88**Return value** 89 90| Type| Description| 91| -------- | -------- | 92| number | Promise used to return the minimum wallpaper height, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default height should be used instead.| 93 94**Example** 95 96```js 97let minHeight = wallpaper.getMinHeightSync(); 98``` 99 100## wallpaper.getMinWidthSync<sup>9+</sup> 101 102getMinWidthSync(): number 103 104Obtains the minimum width of this wallpaper. 105 106**System capability**: SystemCapability.MiscServices.Wallpaper 107 108**System API**: This is a system API. 109 110**Return value** 111 112| Type| Description| 113| -------- | -------- | 114| number | Promise used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead.| 115 116**Example** 117 118```js 119let minWidth = wallpaper.getMinWidthSync(); 120``` 121 122## wallpaper.restore<sup>9+</sup> 123 124restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 125 126Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result. 127 128**Required permissions**: ohos.permission.SET_WALLPAPER 129 130**System capability**: SystemCapability.MiscServices.Wallpaper 131 132**System API**: This is a system API. 133 134**Parameters** 135 136| Name| Type| Mandatory| Description| 137| -------- | -------- | -------- | -------- | 138| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 139| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the wallpaper is reset, **err** is **undefined**. Otherwise, **err** is an error object.| 140 141**Example** 142 143```js 144wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => { 145 if (error) { 146 console.error(`failed to restore because: ${JSON.stringify(error)}`); 147 return; 148 } 149 console.log(`success to restore.`); 150}); 151``` 152 153## wallpaper.restore<sup>9+</sup> 154 155restore(wallpaperType: WallpaperType): Promise<void> 156 157Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result. 158 159**Required permissions**: ohos.permission.SET_WALLPAPER 160 161**System capability**: SystemCapability.MiscServices.Wallpaper 162 163**System API**: This is a system API. 164 165**Parameters** 166 167| Name| Type| Mandatory| Description| 168| -------- | -------- | -------- | -------- | 169| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 170 171**Return value** 172 173| Type| Description| 174| -------- | -------- | 175| Promise<void> | Promise that returns no value.| 176 177**Example** 178 179```js 180wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 181 console.log(`success to restore.`); 182 }).catch((error) => { 183 console.error(`failed to restore because: ${JSON.stringify(error)}`); 184}); 185``` 186 187## wallpaper.setImage<sup>9+</sup> 188 189setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 190 191Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result. 192 193**Required permissions**: ohos.permission.SET_WALLPAPER 194 195**System capability**: SystemCapability.MiscServices.Wallpaper 196 197**System API**: This is a system API. 198 199**Parameters** 200 201| Name| Type| Mandatory| Description| 202| -------- | -------- | -------- | -------- | 203| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or pixel map of a PNG file.| 204| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 205| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the wallpaper is set, **err** is **undefined**. Otherwise, **err** is an error object.| 206 207**Example** 208 209```js 210// The source type is string. 211let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; 212wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => { 213 if (error) { 214 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 215 return; 216 } 217 console.log(`success to setImage.`); 218}); 219 220// The source type is image.PixelMap. 221import image from '@ohos.multimedia.image'; 222let imageSource = image.createImageSource("file://" + wallpaperPath); 223let opts = { 224 "desiredSize": { 225 "height": 3648, 226 "width": 2736 227 } 228}; 229imageSource.createPixelMap(opts).then((pixelMap) => { 230 wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => { 231 if (error) { 232 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 233 return; 234 } 235 console.log(`success to setImage.`); 236 }); 237}).catch((error) => { 238 console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`); 239}); 240``` 241 242## wallpaper.setImage<sup>9+</sup> 243 244setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void> 245 246Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result. 247 248**Required permissions**: ohos.permission.SET_WALLPAPER 249 250**System capability**: SystemCapability.MiscServices.Wallpaper 251 252**System API**: This is a system API. 253 254**Parameters** 255 256| Name| Type| Mandatory| Description| 257| -------- | -------- | -------- | -------- | 258| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or pixel map of a PNG file.| 259| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 260 261**Return value** 262 263| Type| Description| 264| -------- | -------- | 265| Promise<void> | Promise that returns no value.| 266 267**Example** 268 269```js 270// The source type is string. 271let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; 272wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 273 console.log(`success to setImage.`); 274}).catch((error) => { 275 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 276}); 277 278// The source type is image.PixelMap. 279import image from '@ohos.multimedia.image'; 280let imageSource = image.createImageSource("file://" + wallpaperPath); 281let opts = { 282 "desiredSize": { 283 "height": 3648, 284 "width": 2736 285 } 286}; 287imageSource.createPixelMap(opts).then((pixelMap) => { 288 wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 289 console.log(`success to setImage.`); 290 }).catch((error) => { 291 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 292 }); 293}).catch((error) => { 294 console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`); 295}); 296``` 297 298## wallpaper.getImage<sup>9+</sup> 299 300getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void; 301 302Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result. 303 304**Required permissions**: ohos.permission.GET_WALLPAPER 305 306**System capability**: SystemCapability.MiscServices.Wallpaper 307 308**System API**: This is a system API. 309 310**Parameters** 311 312| Name| Type| Mandatory| Description| 313| -------- | -------- | -------- | -------- | 314| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 315| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes| Callback used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.| 316 317**Example** 318 319```js 320wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (error, data) { 321 if (error) { 322 console.error(`failed to getImage because: ${JSON.stringify(error)}`); 323 return; 324 } 325 console.log(`success to getImage: ${JSON.stringify(data)}`); 326}); 327``` 328 329 330## wallpaper.getImage<sup>9+</sup> 331 332getImage(wallpaperType: WallpaperType): Promise<image.PixelMap> 333 334Obtains the pixel map for the wallpaper of the specified type. This API uses a promise to return the result. 335 336**Required permissions**: ohos.permission.GET_WALLPAPER 337 338**System capability**: SystemCapability.MiscServices.Wallpaper 339 340**System API**: This is a system API. 341 342**Parameters** 343 344| Name| Type| Mandatory| Description| 345| -------- | -------- | -------- | -------- | 346| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 347 348**Return value** 349 350| Type| Description| 351| -------- | -------- | 352| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.| 353 354**Example** 355 356```js 357wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { 358 console.log(`success to getImage: ${JSON.stringify(data)}`); 359 }).catch((error) => { 360 console.error(`failed to getImage because: ${JSON.stringify(error)}`); 361}); 362``` 363 364## wallpaper.on('colorChange')<sup>(deprecated)</sup> 365 366on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void 367 368Subscribes to the wallpaper color change event. 369 370> **NOTE** 371> 372> This API is supported since API version 7 and deprecated since API version 9. 373 374**System capability**: SystemCapability.MiscServices.Wallpaper 375 376**Parameters** 377 378| Name| Type| Mandatory| Description| 379| -------- | -------- | -------- | -------- | 380| type | string | Yes| Type of the event to subscribe to. The value **'colorChange'** indicates subscribing to the wallpaper color change event.| 381| callback | function | Yes| Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned.<br>- colors<br> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br> Wallpaper type.| 382 383**Example** 384 385```js 386try { 387 let listener = (colors, wallpaperType) => { 388 console.log(`wallpaper color changed.`); 389 }; 390 wallpaper.on('colorChange', listener); 391} catch (error) { 392 console.error(`failed to on because: ${JSON.stringify(error)}`); 393} 394``` 395 396## wallpaper.off('colorChange')<sup>(deprecated)</sup> 397 398off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void 399 400Unsubscribes from the wallpaper color change event. 401 402> **NOTE** 403> 404> This API is supported since API version 7 and deprecated since API version 9. 405 406**System capability**: SystemCapability.MiscServices.Wallpaper 407 408**Parameters** 409 410| Name| Type| Mandatory| Description| 411| -------- | -------- | -------- | -------- | 412| type | string | Yes| Type of the event to unsubscribe from. The value **'colorChange'** indicates unsubscribing from the wallpaper color change event.| 413| callback | function | No| Callback for the wallpaper color change event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to **type**.<br>- colors<br> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br> Wallpaper type.| 414 415**Example** 416 417```js 418let listener = (colors, wallpaperType) => { 419 console.log(`wallpaper color changed.`); 420}; 421try { 422 wallpaper.on('colorChange', listener); 423} catch (error) { 424 console.error(`failed to on because: ${JSON.stringify(error)}`); 425} 426 427try { 428 // Unsubscribe from the listener. 429 wallpaper.off('colorChange', listener); 430} catch (error) { 431 console.error(`failed to off because: ${JSON.stringify(error)}`); 432} 433 434try { 435 // Unsubscribe from all subscriptions of the colorChange type. 436 wallpaper.off('colorChange'); 437} catch (error) { 438 console.error(`failed to off because: ${JSON.stringify(error)}`); 439} 440``` 441 442## wallpaper.getColors<sup>(deprecated)</sup> 443 444getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void 445 446Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result. 447 448> **NOTE** 449> 450> This API is supported since API version 7 and deprecated since API version 9. 451 452**System capability**: SystemCapability.MiscServices.Wallpaper 453 454**Parameters** 455 456| Name| Type| Mandatory| Description| 457| -------- | -------- | -------- | -------- | 458| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 459| callback | AsyncCallback<Array<[RgbaColor](#rgbacolor)>> | Yes| Callback used to return the main color information of the wallpaper.| 460 461**Example** 462 463```js 464wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { 465 if (error) { 466 console.error(`failed to getColors because: ${JSON.stringify(error)}`); 467 return; 468 } 469 console.log(`success to getColors: ${JSON.stringify(data)}`); 470}); 471``` 472 473## wallpaper.getColors<sup>(deprecated)</sup> 474 475getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>> 476 477Obtains the main color information of the wallpaper of the specified type. This API uses a promise to return the result. 478 479> **NOTE** 480> 481> This API is supported since API version 7 and deprecated since API version 9. 482 483**System capability**: SystemCapability.MiscServices.Wallpaper 484 485**Parameters** 486 487| Name| Type| Mandatory| Description| 488| -------- | -------- | -------- | -------- | 489| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 490 491**Return value** 492 493| Type| Description| 494| -------- | -------- | 495| Promise<Array<[RgbaColor](#rgbacolor)>> | Promise used to return the main color information of the wallpaper.| 496 497**Example** 498 499```js 500wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { 501 console.log(`success to getColors: ${JSON.stringify(data)}`); 502 }).catch((error) => { 503 console.error(`failed to getColors because: ${JSON.stringify(error)}`); 504}); 505``` 506 507## wallpaper.getId<sup>(deprecated)</sup> 508 509getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void 510 511Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result. 512 513> **NOTE** 514> 515> This API is supported since API version 7 and deprecated since API version 9. 516 517**System capability**: SystemCapability.MiscServices.Wallpaper 518 519**Parameters** 520 521| Name| Type| Mandatory| Description| 522| -------- | -------- | -------- | -------- | 523| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 524| callback | AsyncCallback<number> | Yes| Callback used to return the wallpaper ID. If the wallpaper of the specified type is configured, a number greater than or equal to **0** is returned. Otherwise, **-1** is returned. The value ranges from -1 to (2^31-1).| 525 526**Example** 527 528```js 529wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { 530 if (error) { 531 console.error(`failed to getId because: ${JSON.stringify(error)}`); 532 return; 533 } 534 console.log(`success to getId: ${JSON.stringify(data)}`); 535}); 536``` 537 538## wallpaper.getId<sup>(deprecated)</sup> 539 540getId(wallpaperType: WallpaperType): Promise<number> 541 542Obtains the ID of the wallpaper of the specified type. This API uses a promise to return the result. 543 544> **NOTE** 545> 546> This API is supported since API version 7 and deprecated since API version 9. 547 548**System capability**: SystemCapability.MiscServices.Wallpaper 549 550**Parameters** 551 552| Name| Type| Mandatory| Description| 553| -------- | -------- | -------- | -------- | 554| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 555 556**Return value** 557 558| Type| Description| 559| -------- | -------- | 560| Promise<number> | Promise used to return the wallpaper ID. If this type of wallpaper is configured, a number greater than or equal to **0** is returned. Otherwise, **-1** is returned. The value ranges from -1 to (2^31-1).| 561 562**Example** 563 564```js 565wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { 566 console.log(`success to getId: ${JSON.stringify(data)}`); 567 }).catch((error) => { 568 console.error(`failed to getId because: ${JSON.stringify(error)}`); 569}); 570``` 571 572## wallpaper.getMinHeight<sup>(deprecated)</sup> 573 574getMinHeight(callback: AsyncCallback<number>): void 575 576Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result. 577 578> **NOTE** 579> 580> This API is supported since API version 7 and deprecated since API version 9. 581 582**System capability**: SystemCapability.MiscServices.Wallpaper 583 584**Parameters** 585 586| Name| Type| Mandatory| Description| 587| -------- | -------- | -------- | -------- | 588| callback | AsyncCallback<number> | Yes| Callback used to return the minimum wallpaper height, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default height should be used instead.| 589 590**Example** 591 592```js 593wallpaper.getMinHeight((error, data) => { 594 if (error) { 595 console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`); 596 return; 597 } 598 console.log(`success to getMinHeight: ${JSON.stringify(data)}`); 599}); 600``` 601 602## wallpaper.getMinHeight<sup>(deprecated)</sup> 603 604getMinHeight(): Promise<number> 605 606Obtains the minimum height of this wallpaper. This API uses a promise to return the result. 607 608> **NOTE** 609> 610> This API is supported since API version 7 and deprecated since API version 9. 611 612**System capability**: SystemCapability.MiscServices.Wallpaper 613 614**Return value** 615 616| Type| Description| 617| -------- | -------- | 618| Promise<number> | Promise used to return the minimum wallpaper height, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default height should be used instead.| 619 620**Example** 621 622```js 623wallpaper.getMinHeight().then((data) => { 624 console.log(`success to getMinHeight: ${JSON.stringify(data)}`); 625}).catch((error) => { 626 console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`); 627}); 628``` 629 630## wallpaper.getMinWidth<sup>(deprecated)</sup> 631 632getMinWidth(callback: AsyncCallback<number>): void 633 634Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result. 635 636> **NOTE** 637> 638> This API is supported since API version 7 and deprecated since API version 9. 639 640**System capability**: SystemCapability.MiscServices.Wallpaper 641 642**Parameters** 643 644| Name| Type| Mandatory| Description| 645| -------- | -------- | -------- | -------- | 646| callback | AsyncCallback<number> | Yes| Callback used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead.| 647 648**Example** 649 650```js 651wallpaper.getMinWidth((error, data) => { 652 if (error) { 653 console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`); 654 return; 655 } 656 console.log(`success to getMinWidth: ${JSON.stringify(data)}`); 657}); 658``` 659 660## wallpaper.getMinWidth<sup>(deprecated)</sup> 661 662getMinWidth(): Promise<number> 663 664Obtains the minimum width of this wallpaper. This API uses a promise to return the result. 665 666> **NOTE** 667> 668> This API is supported since API version 7 and deprecated since API version 9. 669 670**System capability**: SystemCapability.MiscServices.Wallpaper 671 672**Return value** 673 674| Type| Description| 675| -------- | -------- | 676| Promise<number> | Promise used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead.| 677 678**Example** 679 680```js 681wallpaper.getMinWidth().then((data) => { 682 console.log(`success to getMinWidth: ${JSON.stringify(data)}`); 683 }).catch((error) => { 684 console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`); 685}); 686``` 687 688## wallpaper.isChangePermitted<sup>(deprecated)</sup> 689 690isChangePermitted(callback: AsyncCallback<boolean>): void 691 692Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result. 693 694> **NOTE** 695> 696> This API is supported since API version 7 and deprecated since API version 9. 697 698**System capability**: SystemCapability.MiscServices.Wallpaper 699 700**Parameters** 701 702| Name| Type| Mandatory| Description| 703| -------- | -------- | -------- | -------- | 704| callback | AsyncCallback<boolean> | Yes| Callback used to return whether to allow the application to change the wallpaper for the current user. The value **true** means that the operation is allowed, and **false** means the opposite.| 705 706**Example** 707 708```js 709wallpaper.isChangePermitted((error, data) => { 710 if (error) { 711 console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`); 712 return; 713 } 714 console.log(`success to isChangePermitted: ${JSON.stringify(data)}`); 715}); 716``` 717 718## wallpaper.isChangePermitted<sup>(deprecated)</sup> 719 720isChangePermitted(): Promise<boolean> 721 722Checks whether to allow the application to change the wallpaper for the current user. This API uses a promise to return the result. 723 724> **NOTE** 725> 726> This API is supported since API version 7 and deprecated since API version 9. 727 728**System capability**: SystemCapability.MiscServices.Wallpaper 729 730**Return value** 731 732| Type| Description| 733| -------- | -------- | 734| Promise<boolean> | Promise used to return whether to allow the application to change the wallpaper for the current user. The value **true** means that the operation is allowed, and **false** means the opposite.| 735 736**Example** 737 738```js 739wallpaper.isChangePermitted().then((data) => { 740 console.log(`success to isChangePermitted: ${JSON.stringify(data)}`); 741}).catch((error) => { 742 console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`); 743}); 744``` 745 746## wallpaper.isOperationAllowed<sup>(deprecated)</sup> 747 748isOperationAllowed(callback: AsyncCallback<boolean>): void 749 750Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result. 751 752> **NOTE** 753> 754> This API is supported since API version 7 and deprecated since API version 9. 755 756**System capability**: SystemCapability.MiscServices.Wallpaper 757 758**Parameters** 759 760| Name| Type| Mandatory| Description| 761| -------- | -------- | -------- | -------- | 762| callback | AsyncCallback<boolean> | Yes| Callback used to return whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.| 763 764**Example** 765 766```js 767wallpaper.isOperationAllowed((error, data) => { 768 if (error) { 769 console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`); 770 return; 771 } 772 console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`); 773}); 774``` 775 776## wallpaper.isOperationAllowed<sup>(deprecated)</sup> 777 778isOperationAllowed(): Promise<boolean> 779 780Checks whether the user is allowed to set wallpapers. This API uses a promise to return the result. 781 782> **NOTE** 783> 784> This API is supported since API version 7 and deprecated since API version 9. 785 786**System capability**: SystemCapability.MiscServices.Wallpaper 787 788**Return value** 789 790| Type| Description| 791| -------- | -------- | 792| Promise<boolean> | Promise used to return whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.| 793 794**Example** 795 796```js 797wallpaper.isOperationAllowed().then((data) => { 798 console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`); 799 }).catch((error) => { 800 console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`); 801}); 802``` 803 804## wallpaper.reset<sup>(deprecated)</sup> 805 806reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 807 808Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result. 809 810> **NOTE** 811> 812> This API is supported since API version 7 and deprecated since API version 9. 813 814**Required permissions**: ohos.permission.SET_WALLPAPER 815 816**System capability**: SystemCapability.MiscServices.Wallpaper 817 818**Parameters** 819 820| Name| Type| Mandatory| Description| 821| -------- | -------- | -------- | -------- | 822| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 823| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the wallpaper is reset, **err** is **undefined**. Otherwise, **err** is an error object.| 824 825**Example** 826 827```js 828wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => { 829 if (error) { 830 console.error(`failed to reset because: ${JSON.stringify(error)}`); 831 return; 832 } 833 console.log(`success to reset.`); 834}); 835``` 836 837## wallpaper.reset<sup>(deprecated)</sup> 838 839reset(wallpaperType: WallpaperType): Promise<void> 840 841Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result. 842 843> **NOTE** 844> 845> This API is supported since API version 7 and deprecated since API version 9. 846 847**Required permissions**: ohos.permission.SET_WALLPAPER 848 849**System capability**: SystemCapability.MiscServices.Wallpaper 850 851**Parameters** 852 853| Name| Type| Mandatory| Description| 854| -------- | -------- | -------- | -------- | 855| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 856 857**Return value** 858 859| Type| Description| 860| -------- | -------- | 861| Promise<void> | Promise that returns no value.| 862 863**Example** 864 865```js 866wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 867 console.log(`success to reset.`); 868}).catch((error) => { 869 console.error(`failed to reset because: ${JSON.stringify(error)}`); 870}); 871``` 872 873## wallpaper.setWallpaper<sup>(deprecated)</sup> 874 875setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 876 877Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result. 878 879> **NOTE** 880> 881> This API is supported since API version 7 and deprecated since API version 9. 882 883**Required permissions**: ohos.permission.SET_WALLPAPER 884 885**System capability**: SystemCapability.MiscServices.Wallpaper 886 887**Parameters** 888 889| Name| Type| Mandatory| Description| 890| -------- | -------- | -------- | -------- | 891| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or pixel map of a PNG file.| 892| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 893| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the wallpaper is set, **err** is **undefined**. Otherwise, **err** is an error object.| 894 895**Example** 896 897```js 898// The source type is string. 899let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; 900wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => { 901 if (error) { 902 console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`); 903 return; 904 } 905 console.log(`success to setWallpaper.`); 906}); 907 908// The source type is image.PixelMap. 909import image from '@ohos.multimedia.image'; 910let imageSource = image.createImageSource("file://" + wallpaperPath); 911let opts = { 912 "desiredSize": { 913 "height": 3648, 914 "width": 2736 915 } 916}; 917imageSource.createPixelMap(opts).then((pixelMap) => { 918 wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => { 919 if (error) { 920 console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`); 921 return; 922 } 923 console.log(`success to setWallpaper.`); 924 }); 925}).catch((error) => { 926 console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`); 927}); 928``` 929 930## wallpaper.setWallpaper<sup>(deprecated)</sup> 931 932setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void> 933 934Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result. 935 936> **NOTE** 937> 938> This API is supported since API version 7 and deprecated since API version 9. 939 940**Required permissions**: ohos.permission.SET_WALLPAPER 941 942**System capability**: SystemCapability.MiscServices.Wallpaper 943 944**Parameters** 945 946| Name| Type| Mandatory| Description| 947| -------- | -------- | -------- | -------- | 948| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or pixel map of a PNG file.| 949| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 950 951**Return value** 952 953| Type| Description| 954| -------- | -------- | 955| Promise<void> | Promise that returns no value.| 956 957**Example** 958 959```js 960// The source type is string. 961let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; 962wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 963 console.log(`success to setWallpaper.`); 964 }).catch((error) => { 965 console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`); 966}); 967 968// The source type is image.PixelMap. 969import image from '@ohos.multimedia.image'; 970let imageSource = image.createImageSource("file://" + wallpaperPath); 971let opts = { 972 "desiredSize": { 973 "height": 3648, 974 "width": 2736 975 } 976}; 977imageSource.createPixelMap(opts).then((pixelMap) => { 978 wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 979 console.log(`success to setWallpaper.`); 980 }).catch((error) => { 981 console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`); 982 }); 983 }).catch((error) => { 984 console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`); 985}); 986``` 987 988 989## wallpaper.getFile<sup>(deprecated)</sup> 990 991getFile(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void 992 993Obtains the wallpaper of the specified type. This API uses an asynchronous callback to return the result. 994 995> **NOTE** 996> 997> This API is supported since API version 8 and deprecated since API version 9. 998 999**Required permissions**: ohos.permission.GET_WALLPAPER 1000 1001**System capability**: SystemCapability.MiscServices.Wallpaper 1002 1003**Parameters** 1004 1005| Name| Type| Mandatory| Description| 1006| -------- | -------- | -------- | -------- | 1007| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 1008| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned.| 1009 1010**Example** 1011 1012```js 1013wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { 1014 if (error) { 1015 console.error(`failed to getFile because: ${JSON.stringify(error)}`); 1016 return; 1017 } 1018 console.log(`success to getFile: ${JSON.stringify(data)}`); 1019}); 1020``` 1021 1022## wallpaper.getFile<sup>(deprecated)</sup> 1023 1024getFile(wallpaperType: WallpaperType): Promise<number> 1025 1026Obtains the wallpaper of the specified type. This API uses a promise to return the result. 1027 1028> **NOTE** 1029> 1030> This API is supported since API version 8 and deprecated since API version 9. 1031 1032**Required permissions**: ohos.permission.GET_WALLPAPER 1033 1034**System capability**: SystemCapability.MiscServices.Wallpaper 1035 1036**Parameters** 1037 1038| Name| Type| Mandatory| Description| 1039| -------- | -------- | -------- | -------- | 1040| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 1041 1042**Return value** 1043 1044| Type| Description| 1045| -------- | -------- | 1046| Promise<number> | Promise used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned.| 1047 1048**Example** 1049 1050```js 1051wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { 1052 console.log(`success to getFile: ${JSON.stringify(data)}`); 1053 }).catch((error) => { 1054 console.error(`failed to getFile because: ${JSON.stringify(error)}`); 1055}); 1056``` 1057 1058## wallpaper.getPixelMap<sup>(deprecated)</sup> 1059 1060getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void; 1061 1062Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result. 1063 1064> **NOTE** 1065> 1066> This API is supported since API version 7 and deprecated since API version 9. 1067 1068**Required permissions**: ohos.permission.GET_WALLPAPER 1069 1070**System capability**: SystemCapability.MiscServices.Wallpaper 1071 1072**System API**: This is a system API. 1073 1074**Parameters** 1075 1076| Name| Type| Mandatory| Description| 1077| -------- | -------- | -------- | -------- | 1078| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 1079| callback | AsyncCallback<image.PixelMap> | Yes| Callback used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.| 1080 1081**Example** 1082 1083```js 1084wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (error, data) { 1085 if (error) { 1086 console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`); 1087 return; 1088 } 1089 console.log(`success to getPixelMap : ${JSON.stringify(data)}`); 1090 }); 1091``` 1092 1093## wallpaper.getPixelMap<sup>(deprecated)</sup> 1094 1095getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap> 1096 1097Obtains the pixel map for the wallpaper of the specified type. This API uses a promise to return the result. 1098 1099> **NOTE** 1100> 1101> This API is supported since API version 7 and deprecated since API version 9. 1102 1103**Required permissions**: ohos.permission.GET_WALLPAPER 1104 1105**System capability**: SystemCapability.MiscServices.Wallpaper 1106 1107**System API**: This is a system API. 1108 1109**Parameters** 1110 1111| Name| Type| Mandatory| Description| 1112| -------- | -------- | -------- | -------- | 1113| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.| 1114 1115**Return value** 1116 1117| Type| Description| 1118| -------- | -------- | 1119| Promise<image.PixelMap> | Promise used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.| 1120 1121**Example** 1122 1123```js 1124wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { 1125 console.log(`success to getPixelMap : ${JSON.stringify(data)}`); 1126 }).catch((error) => { 1127 console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`); 1128}); 1129``` 1130
