1# @ohos.wallpaper (壁纸)(系统接口) 2 3壁纸管理服务为OpenHarmony系统服务，提供壁纸切换功能。从API 9开始壁纸管理的接口调整为系统API，壁纸的切换只能通过系统应用来完成。壁纸管理提供壁纸切换通道，使用壁纸的应用（如：桌面）需订阅壁纸变化通知并刷新壁纸显示。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.wallpaper (壁纸)](js-apis-wallpaper.md) 9 10 11## 导入模块 12 13 14```ts 15import { wallpaper } from '@kit.BasicServicesKit'; 16``` 17## WallpaperResourceType<sup>10+</sup> 18 19定义壁纸资源的枚举类型。 20 21**系统能力**: SystemCapability.MiscServices.Wallpaper 22 23**系统接口**：此接口为系统接口。 24 25| 名称 | 值 |说明 | 26| -------- | -------- |-------- | 27| DEFAULT | 0 |默认为图片资源。 | 28| PICTURE | 1 |图片资源。 | 29| VIDEO | 2 |视频资源。 | 30| PACKAGE | 3 |包资源。 | 31 32## FoldState<sup>14+</sup> 33 34定义设备的折展状态枚举类型。 35 36**系统能力**: SystemCapability.MiscServices.Wallpaper 37 38**系统接口**：此接口为系统接口。 39 40| 名称 | 值 |说明 | 41| -------- | -------- |-------- | 42| NORMAL | 0 |设备默认状态。 | 43| UNFOLD_ONCE_STATE | 1 |一次展开态。 | 44| UNFOLD_TWICE_STATE | 2 |二次展开态。 | 45 46## RotateState<sup>14+</sup> 47 48定义设备的横竖屏状态枚举类型。 49 50**系统能力**: SystemCapability.MiscServices.Wallpaper 51 52**系统接口**：此接口为系统接口。 53 54| 名称 | 值 |说明 | 55| -------- | -------- |-------- | 56| PORTRAIT | 0 |设备默认为竖屏状态。 | 57| LANDSCAPE | 1 |横屏状态。 | 58 59## WallpaperInfo<sup>14+</sup> 60 61定义壁纸的信息结构。 62 63**系统能力**: SystemCapability.MiscServices.Wallpaper 64 65**系统接口**：此接口为系统接口。 66 67| 名称 | 类型 | 说明 | 68| -------- | -------- | -------- | 69| [FoldState](#foldstate14) | enum | 表示设备的折展状态。 | 70| [RotateState](#rotatestate14) | enum | 表示设备的横竖屏状态。 | 71| source | string | 表示壁纸资源uri，只支持应用沙箱目录。 | 72 73## wallpaper.setVideo<sup>10+</sup> 74 75setVideo(source: string, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 76 77将视频资源设置为桌面或锁屏的动态壁纸。使用callback异步回调。 78 79**需要权限**：ohos.permission.SET_WALLPAPER 80 81**系统能力**: SystemCapability.MiscServices.Wallpaper 82 83**系统接口**：此接口为系统接口。 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| -------- | -------- | -------- | -------- | 89| source | string | 是 | mp4文件的Uri路径。 | 90| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 91| callback | AsyncCallback<void> | 是 | 回调函数，设置壁纸成功，error为undefined，否则返回error信息。 | 92 93**错误码：** 94 95以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 96 97| **错误码ID** | **错误信息** | 98| ------------ | ------------------------------------------- | 99| 201 | permission denied. | 100| 202 | permission verification failed, application which is not a system application uses system API. | 101| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 102 103**示例：** 104 105```ts 106import { BusinessError } from '@kit.BasicServicesKit'; 107 108let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.mp4"; 109try { 110 wallpaper.setVideo(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => { 111 if (error) { 112 console.error(`failed to setVideo because: ${JSON.stringify(error)}`); 113 return; 114 } 115 console.info(`success to setVideo.`); 116 }); 117} catch (error) { 118 console.error(`failed to setVideo because: ${JSON.stringify(error)}`); 119} 120 121``` 122 123## wallpaper.setVideo<sup>10+</sup> 124 125setVideo(source: string, wallpaperType: WallpaperType): Promise<void> 126 127将视频资源设置为桌面或锁屏的动态壁纸。使用promise异步回调。 128 129**需要权限**：ohos.permission.SET_WALLPAPER 130 131**系统能力**: SystemCapability.MiscServices.Wallpaper 132 133**系统接口**：此接口为系统接口。 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| -------- | -------- | -------- | -------- | 139| source | string | 是 | mp4文件的Uri路径。 | 140| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 141 142**错误码：** 143 144以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 145 146| **错误码ID** | **错误信息** | 147| ------------ | ------------------------------------------- | 148| 201 | permission denied. | 149| 202 | permission verification failed, application which is not a system application uses system API. | 150| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 151 152**返回值：** 153 154| 类型 | 说明 | 155| -------- | -------- | 156| Promise<void> | 无返回结果的Promise对象。 | 157 158**示例：** 159 160```ts 161import { BusinessError } from '@kit.BasicServicesKit'; 162 163let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.mp4"; 164try { 165 wallpaper.setVideo(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 166 console.info(`success to setVideo.`); 167 }).catch((error: BusinessError) => { 168 console.error(`failed to setVideo because: ${JSON.stringify(error)}`); 169 }); 170} catch (error) { 171 console.error(`failed to setVideo because: ${JSON.stringify(error)}`); 172} 173``` 174 175## wallpaper.setCustomWallpaper<sup>10+</sup> 176 177setCustomWallpaper(source: string, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 178 179将指定的zip资源包设置为桌面或锁屏的壁纸资源，仅当com.ohos.sceneboard存在时，支持使用该接口。且具有ohos.permission.GET_WALLPAPER权限的应用可以访问/data/wallpaper/目录获取设置的资源。使用callback异步回调。 180 181**需要权限**：ohos.permission.SET_WALLPAPER 182 183**系统能力**: SystemCapability.MiscServices.Wallpaper 184 185**系统接口**：此接口为系统接口。 186 187**参数：** 188 189| 参数名 | 类型 | 必填 | 说明 | 190| -------- | -------- | -------- | -------- | 191| source | string | 是 | 指定的zip资源包。 | 192| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 193| callback | AsyncCallback<void> | 是 | 回调函数，设置壁纸成功，error为undefined，否则返回error信息。 | 194 195**错误码：** 196 197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 198 199| **错误码ID** | **错误信息** | 200| ------------ | ------------------------------------------- | 201| 201 | permission denied. | 202| 202 | permission verification failed, application which is not a system application uses system API. | 203| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 204 205**示例：** 206 207```ts 208import { BusinessError } from '@kit.BasicServicesKit'; 209 210let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.zip"; 211try { 212 wallpaper.setCustomWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => { 213 if (error) { 214 console.error(`failed to setCustomWallpaper because: ${JSON.stringify(error)}`); 215 return; 216 } 217 console.info(`success to setCustomWallpaper.`); 218 }); 219} catch (error) { 220 console.error(`failed to setCustomWallpaper because: ${JSON.stringify(error)}`); 221} 222 223``` 224 225## wallpaper.setCustomWallpaper<sup>10+</sup> 226 227setCustomWallpaper(source: string, wallpaperType: WallpaperType): Promise<void> 228 229将指定的zip资源包设置为桌面或锁屏的壁纸资源，仅当com.ohos.sceneboard存在时，支持使用该接口。且具有ohos.permission.GET_WALLPAPER权限的应用可以访问/data/wallpaper/目录获取设置的资源。使用Promise异步回调。 230 231**需要权限**：ohos.permission.SET_WALLPAPER 232 233**系统能力**: SystemCapability.MiscServices.Wallpaper 234 235**系统接口**：此接口为系统接口。 236 237**参数：** 238 239| 参数名 | 类型 | 必填 | 说明 | 240| -------- | -------- | -------- | -------- | 241| source | string | 是 | 指定的zip资源包。 | 242| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 243 244**返回值：** 245 246| 类型 | 说明 | 247| -------- | -------- | 248| Promise<void> | 无返回结果的Promise对象。 | 249 250**错误码：** 251 252以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 253 254| **错误码ID** | **错误信息** | 255| ------------ | ------------------------------------------- | 256| 201 | permission denied. | 257| 202 | permission verification failed, application which is not a system application uses system API. | 258| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 259 260**示例：** 261 262```ts 263import { BusinessError } from '@kit.BasicServicesKit'; 264 265let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.zip"; 266try { 267 wallpaper.setCustomWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 268 console.info(`success to setCustomWallpaper.`); 269 }).catch((error: BusinessError) => { 270 console.error(`failed to setCustomWallpaper because: ${JSON.stringify(error)}`); 271 }); 272} catch (error) { 273 console.error(`failed to setCustomWallpaper because: ${JSON.stringify(error)}`); 274} 275``` 276 277## wallpaper.on('wallpaperChange')<sup>10+</sup> 278 279on(type: 'wallpaperChange', callback: (wallpaperType: WallpaperType, resourceType: WallpaperResourceType, uri?: string) => void): void 280 281订阅壁纸变化通知事件。不支持多线程并发调用。 282 283**系统能力**: SystemCapability.MiscServices.Wallpaper 284 285**系统接口**：此接口为系统接口。 286 287**参数：** 288 289| 参数名 | 类型 | 必填 | 说明 | 290| -------- | -------- | -------- | -------- | 291| type | string | 是 | 事件回调类型。支持的事件为'wallpaperChange'，完成壁纸切换后触发该事件。 | 292| callback | function | 是 | 壁纸变化触发该回调方法，返回壁纸类型和壁纸资源类型。<br/>- wallpaperType：壁纸类型。<br/>- resourceType：壁纸资源类型。<br/>- uri：壁纸资源地址。 | 293 294**错误码：** 295 296以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 297 298| **错误码ID** | **错误信息** | 299| ------------ | ------------------------------------------- | 300| 202 | permission verification failed, application which is not a system application uses system API. | 301| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 302 303**示例：** 304 305```ts 306try { 307 let listener = (wallpaperType: wallpaper.WallpaperType, resourceType: wallpaper.WallpaperResourceType): void => { 308 console.info(`wallpaper color changed.`); 309 }; 310 wallpaper.on('wallpaperChange', listener); 311} catch (error) { 312 console.error(`failed to on because: ${JSON.stringify(error)}`); 313} 314``` 315 316## wallpaper.off('wallpaperChange')<sup>10+</sup> 317 318off(type: 'wallpaperChange', callback?: (wallpaperType: WallpaperType, resourceType: WallpaperResourceType, uri?: string) => void): void 319 320取消订阅壁纸变化通知事件。不支持多线程并发调用。 321 322**系统能力**: SystemCapability.MiscServices.Wallpaper 323 324**系统接口**：此接口为系统接口。 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| -------- | -------- | -------- | -------- | 330| type | string | 是 | 事件回调类型。支持的事件为'wallpaperChange'，完成壁纸切换后触发该事件。 | 331| callback | function | 否 | 表示要取消的壁纸变化回调，不填写该参数则取消订阅该type对应的所有回调。<br/>- wallpaperType：壁纸类型。<br/>- resourceType：壁纸资源类型。<br/>- uri：壁纸资源地址。 | 332 333**错误码：** 334 335以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 336 337| **错误码ID** | **错误信息** | 338| ------------ | ------------------------------------------- | 339| 202 | permission verification failed, application which is not a system application uses system API. | 340| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 341 342**示例：** 343 344```ts 345let listener = (wallpaperType: wallpaper.WallpaperType, resourceType: wallpaper.WallpaperResourceType): void => { 346 console.info(`wallpaper color changed.`); 347}; 348try { 349 wallpaper.on('wallpaperChange', listener); 350} catch (error) { 351 console.error(`failed to on because: ${JSON.stringify(error)}`); 352} 353 354try { 355 // 取消订阅listener 356 wallpaper.off('wallpaperChange', listener); 357} catch (error) { 358 console.error(`failed to off because: ${JSON.stringify(error)}`); 359} 360 361try { 362 // 取消所有'wallpaperChange'类型的订阅 363 wallpaper.off('wallpaperChange'); 364} catch (error) { 365 console.error(`failed to off because: ${JSON.stringify(error)}`); 366} 367``` 368 369## wallpaper.getColorsSync<sup>9+</sup> 370 371getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor> 372 373获取指定类型壁纸的主要颜色信息。 374 375**系统能力**: SystemCapability.MiscServices.Wallpaper 376 377**系统接口**：此接口为系统接口。 378 379**参数：** 380 381| 参数名 | 类型 | 必填 | 说明 | 382| -------- | -------- | -------- | -------- | 383| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 384 385**返回值**： 386 387| 类型 | 说明 | 388| -------- | -------- | 389| Array<[RgbaColor](js-apis-wallpaper.md#rgbacolordeprecated)> | 返回壁纸的主要颜色信息。 | 390 391**错误码：** 392 393以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 394 395| **错误码ID** | **错误信息** | 396| ------------ | ------------------------------------------- | 397| 202 | permission verification failed, application which is not a system application uses system API. | 398| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 399 400**示例**： 401 402```ts 403try { 404 let colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM); 405 console.info(`success to getColorsSync: ${JSON.stringify(colors)}`); 406} catch (error) { 407 console.error(`failed to getColorsSync because: ${JSON.stringify(error)}`); 408} 409``` 410 411## wallpaper.getMinHeightSync<sup>9+</sup> 412 413getMinHeightSync(): number 414 415获取壁纸的最小高度值。 416 417**系统能力**: SystemCapability.MiscServices.Wallpaper 418 419**系统接口**：此接口为系统接口。 420 421**返回值：** 422 423| 类型 | 说明 | 424| -------- | -------- | 425| number | 返回壁纸的最小高度值，单位是像素。如果返回值等于0，说明没有设置壁纸，调用者应该使用默认显示的高度值代替。 | 426 427**错误码：** 428 429以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 430 431| **错误码ID** | **错误信息** | 432| ------------ | ------------------------------------------- | 433| 202 | permission verification failed, application which is not a system application uses system API. | 434 435**示例：** 436 437```ts 438let minHeight = wallpaper.getMinHeightSync(); 439``` 440 441## wallpaper.getMinWidthSync<sup>9+</sup> 442 443getMinWidthSync(): number 444 445获取壁纸的最小宽度值。 446 447**系统能力**: SystemCapability.MiscServices.Wallpaper 448 449**系统接口**：此接口为系统接口。 450 451**返回值：** 452 453| 类型 | 说明 | 454| -------- | -------- | 455| number | 壁纸的最小宽度值，单位是像素。如果返回值等于0，说明没有设置壁纸，调用者应该使用默认显示的宽度值代替。 | 456 457**错误码：** 458 459以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 460 461| **错误码ID** | **错误信息** | 462| ------------ | ------------------------------------------- | 463| 202 | permission verification failed, application which is not a system application uses system API. | 464 465**示例：** 466 467```ts 468let minWidth = wallpaper.getMinWidthSync(); 469``` 470 471## wallpaper.restore<sup>9+</sup> 472 473restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 474 475移除指定类型的壁纸，恢复为默认显示的壁纸。使用callback异步回调。 476 477**需要权限**：ohos.permission.SET_WALLPAPER 478 479**系统能力**: SystemCapability.MiscServices.Wallpaper 480 481**系统接口**：此接口为系统接口。 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| -------- | -------- | -------- | -------- | 487| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 488| callback | AsyncCallback<void> | 是 | 回调函数，移除壁纸成功，error为undefined，否则返回error信息。 | 489 490**错误码：** 491 492以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 493 494| **错误码ID** | **错误信息** | 495| ------------ | ------------------------------------------- | 496| 201 | permission denied. | 497| 202 | permission verification failed, application which is not a system application uses system API. | 498| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 499 500**示例：** 501 502```ts 503import { BusinessError } from '@kit.BasicServicesKit'; 504 505wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => { 506 if (error) { 507 console.error(`failed to restore because: ${JSON.stringify(error)}`); 508 return; 509 } 510 console.info(`success to restore.`); 511}); 512``` 513 514## wallpaper.restore<sup>9+</sup> 515 516restore(wallpaperType: WallpaperType): Promise<void> 517 518移除指定类型的壁纸，恢复为默认显示的壁纸。使用promise异步回调。 519 520**需要权限**：ohos.permission.SET_WALLPAPER 521 522**系统能力**: SystemCapability.MiscServices.Wallpaper 523 524**系统接口**：此接口为系统接口。 525 526**参数：** 527 528| 参数名 | 类型 | 必填 | 说明 | 529| -------- | -------- | -------- | -------- | 530| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 531 532**返回值：** 533 534| 类型 | 说明 | 535| -------- | -------- | 536| Promise<void> | 无返回结果的Promise对象。 | 537 538**错误码：** 539 540以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 541 542| **错误码ID** | **错误信息** | 543| ------------ | ------------------------------------------- | 544| 201 | permission denied. | 545| 202 | permission verification failed, application which is not a system application uses system API. | 546| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 547 548**示例：** 549 550```ts 551import { BusinessError } from '@kit.BasicServicesKit'; 552 553wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 554 console.info(`success to restore.`); 555 }).catch((error: BusinessError) => { 556 console.error(`failed to restore because: ${JSON.stringify(error)}`); 557}); 558``` 559 560## wallpaper.setImage<sup>9+</sup> 561 562setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void 563 564将指定资源设置为指定类型的壁纸。使用callback异步回调。 565 566**需要权限**：ohos.permission.SET_WALLPAPER 567 568**系统能力**: SystemCapability.MiscServices.Wallpaper 569 570**系统接口**：此接口为系统接口。 571 572**参数：** 573 574| 参数名 | 类型 | 必填 | 说明 | 575| -------- | -------- | -------- | -------- | 576| source | string \| [image.PixelMap](../apis-image-kit/js-apis-image.md) | 是 | JPEG或PNG文件的Uri路径，或者PNG格式文件的位图。 | 577| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 578| callback | AsyncCallback<void> | 是 | 回调函数，设置壁纸成功，error为undefined，否则返回error信息。 | 579 580**错误码：** 581 582以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 583 584| **错误码ID** | **错误信息** | 585| ------------ | ------------------------------------------- | 586| 201 | permission denied. | 587| 202 | permission verification failed, application which is not a system application uses system API. | 588| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 589 590**示例：** 591 592```ts 593import { BusinessError } from '@kit.BasicServicesKit'; 594import { image } from '@kit.ImageKit'; 595 596// source类型为string 597let wallpaperPath = "/data/storage/el2/base/haps/entry/files/js.jpeg"; 598wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => { 599 if (error) { 600 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 601 return; 602 } 603 console.info(`success to setImage.`); 604}); 605 606// source类型为image.PixelMap 607let imageSource = image.createImageSource("file://" + wallpaperPath); 608let opts: image.DecodingOptions = { 609 desiredSize: { 610 height: 3648, 611 width: 2736 612 } 613}; 614imageSource.createPixelMap(opts).then((pixelMap: image.PixelMap) => { 615 wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => { 616 if (error) { 617 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 618 return; 619 } 620 console.info(`success to setImage.`); 621 }); 622}).catch((error: BusinessError) => { 623 console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`); 624}); 625``` 626 627## wallpaper.setImage<sup>9+</sup> 628 629setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void> 630 631将指定资源设置为指定类型的壁纸。使用promise异步回调。 632 633**需要权限**：ohos.permission.SET_WALLPAPER 634 635**系统能力**: SystemCapability.MiscServices.Wallpaper 636 637**系统接口**：此接口为系统接口。 638 639**参数：** 640 641| 参数名 | 类型 | 必填 | 说明 | 642| -------- | -------- | -------- | -------- | 643| source | string \| [image.PixelMap](../apis-image-kit/js-apis-image.md) | 是 | JPEG或PNG文件的Uri路径，或者PNG格式文件的位图。 | 644| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 645 646**返回值：** 647 648| 类型 | 说明 | 649| -------- | -------- | 650| Promise<void> | 无返回结果的Promise对象。 | 651 652**错误码：** 653 654以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 655 656| **错误码ID** | **错误信息** | 657| ------------ | ------------------------------------------- | 658| 201 | permission denied. | 659| 202 | permission verification failed, application which is not a system application uses system API. | 660| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 661 662**示例：** 663 664```ts 665import { BusinessError } from '@kit.BasicServicesKit'; 666import { image } from '@kit.ImageKit'; 667 668// source类型为string 669let wallpaperPath = "/data/storage/el2/base/haps/entry/files/js.jpeg"; 670wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 671 console.info(`success to setImage.`); 672}).catch((error: BusinessError) => { 673 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 674}); 675 676// source类型为image.PixelMap 677let imageSource = image.createImageSource("file://" + wallpaperPath); 678let opts: image.DecodingOptions = { 679 desiredSize: { 680 height: 3648, 681 width: 2736 682 } 683}; 684imageSource.createPixelMap(opts).then((pixelMap: image.PixelMap) => { 685 wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 686 console.info(`success to setImage.`); 687 }).catch((error: BusinessError) => { 688 console.error(`failed to setImage because: ${JSON.stringify(error)}`); 689 }); 690}).catch((error: BusinessError) => { 691 console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`); 692}); 693``` 694 695## wallpaper.getImage<sup>9+</sup> 696 697getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void; 698 699获取壁纸图片的像素图，且只能获取使用setImage设置的静态壁纸。使用callback异步回调。 700 701**需要权限**：ohos.permission.GET_WALLPAPER 702 703**系统能力**: SystemCapability.MiscServices.Wallpaper 704 705**系统接口**：此接口为系统接口。 706 707**参数：** 708 709| 参数名 | 类型 | 必填 | 说明 | 710| -------- | -------- | -------- | -------- | 711| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 712| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md)> | 是 | 回调函数，调用成功则返回壁纸图片的像素图对象，调用失败则返回error信息。 | 713 714**错误码：** 715 716以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 717 718| **错误码ID** | **错误信息** | 719| ------------ | ------------------------------------------- | 720| 201 | permission denied. | 721| 202 | permission verification failed, application which is not a system application uses system API. | 722| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 723 724**示例：** 725 726```ts 727import { BusinessError } from '@kit.BasicServicesKit'; 728import { image } from '@kit.ImageKit'; 729 730wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: image.PixelMap) => { 731 if (error) { 732 console.error(`failed to getImage because: ${JSON.stringify(error)}`); 733 return; 734 } 735 console.info(`success to getImage: ${JSON.stringify(data)}`); 736}); 737``` 738 739## wallpaper.getImage<sup>9+</sup> 740 741getImage(wallpaperType: WallpaperType): Promise<image.PixelMap> 742 743获取壁纸图片的像素图，且只能获取使用setImage设置的静态壁纸。使用promise异步回调。 744 745**需要权限**：ohos.permission.GET_WALLPAPER 746 747**系统能力**: SystemCapability.MiscServices.Wallpaper 748 749**系统接口**：此接口为系统接口。 750 751**参数：** 752 753| 参数名 | 类型 | 必填 | 说明 | 754| -------- | -------- | -------- | -------- | 755| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 756 757**返回值：** 758 759| 类型 | 说明 | 760| -------- | -------- | 761| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md)> | 调用成功则返回壁纸图片的像素图对象，调用失败则返回error信息。 | 762 763**错误码：** 764 765以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 766 767| **错误码ID** | **错误信息** | 768| ------------ | ------------------------------------------- | 769| 201 | permission denied. | 770| 202 | permission verification failed, application which is not a system application uses system API. | 771| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 772 773**示例：** 774 775```ts 776import { BusinessError } from '@kit.BasicServicesKit'; 777import { image } from '@kit.ImageKit'; 778 779wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: image.PixelMap) => { 780 console.info(`success to getImage: ${JSON.stringify(data)}`); 781 }).catch((error: BusinessError) => { 782 console.error(`failed to getImage because: ${JSON.stringify(error)}`); 783}); 784``` 785## wallpaper.getWallpaperByState<sup>14+</sup> 786 787getWallpaperByState(wallpaperType:WallpaperType, foldState:FoldState, rotateState:RotateState): Promise<image.PixelMap> 788 789获取指定壁纸类型、折展态、横竖屏的壁纸图片的像素图，如果指定的壁纸不存在，会逐步降级匹配，unfolded-land -> unfolded-port ->normal-port。使用promise异步回调。 790 791**需要权限**：ohos.permission.GET_WALLPAPER 792 793**系统能力**: SystemCapability.MiscServices.Wallpaper 794 795**系统接口**：此接口为系统接口。 796 797**参数：** 798 799| 参数名 | 类型 | 必填 | 说明 | 800| -------- | -------- | -------- | -------- | 801| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 802| foldState | [FoldState](#foldstate14) | 是 | 折展状态类型。 | 803| rotateState | [RotateState](#rotatestate14) | 是 | 横竖屏状态类型。 | 804 805**返回值：** 806 807| 类型 | 说明 | 808| -------- | -------- | 809| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md)> | 调用成功则返回壁纸图片的像素图对象，调用失败则返回error信息。 | 810 811**错误码：** 812 813以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 814 815| **错误码ID** | **错误信息** | 816| ------------ | ------------------------------------------- | 817| 201 | permission denied. | 818| 202 | permission verification failed, application which is not a system application uses system API. | 819| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 820 821**示例：** 822 823```ts 824import { BusinessError } from '@kit.BasicServicesKit'; 825import { wallpaper } from '@kit.BasicServicesKit'; 826import { image } from '@kit.ImageKit'; 827 828wallpaper.getWallpaperByState(wallpaper.WallpaperType.WALLPAPER_SYSTEM,wallpaper.FoldState.NORMAL,wallpaper.RotateState.PORTRAIT).then((data:image.PixelMap) => { 829 console.info(`success to getWallpaperByState: ${JSON.stringify(data)}`); 830}).catch((error: BusinessError) => { 831 console.error(`failed to getWallpaperByState because: ${JSON.stringify(error)}`); 832}); 833``` 834 835## wallpaper.setAllWallpapers<sup>14+</sup> 836 837setAllWallpapers(wallpaperInfos: Array\<WallpaperInfo>\, wallpaperType: WallpaperType): Promise<void> 838 839设置设备所有形态的壁纸。使用promise异步回调。（包括折展状态、横竖屏状态、资源路径，其中NORMAL-PORT为必选） 840 841**需要权限**：ohos.permission.SET_WALLPAPER 842 843**系统能力**: SystemCapability.MiscServices.Wallpaper 844 845**系统接口**：此接口为系统接口。 846 847**参数：** 848 849| 参数名 | 类型 | 必填 | 说明 | 850| -------- | -------- | -------- | -------- | 851| wallpaperInfos | Array<[WallpaperInfo](#wallpaperinfo14)> | 是 | 所有壁纸的信息结构。 | 852| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 853 854**返回值：** 855 856| 类型 | 说明 | 857| -------- | -------- | 858| Promise<void> | 无返回结果的Promise对象。 | 859 860**错误码：** 861 862以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 863 864| **错误码ID** | **错误信息** | 865| ------------ | ------------------------------------------- | 866| 201 | permission denied. | 867| 202 | permission verification failed, application which is not a system application uses system API. | 868| 401 | 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.| 869 870**示例：** 871 872```ts 873import { BusinessError } from '@kit.BasicServicesKit'; 874import { wallpaper } from '@kit.BasicServicesKit'; 875 876let wallpaperInfos: Array<wallpaper.WallpaperInfo> 877wallpaperInfos = [ 878 { 879 foldState: wallpaper.FoldState.NORMAL, 880 rotateState: wallpaper.RotateState.PORTRAIT, 881 source: '/data/storage/el2/base/haps/entry/files/normal.jpeg' 882 }, 883 { 884 foldState: wallpaper.FoldState.UNFOLD_ONCE_STATE, 885 rotateState: wallpaper.RotateState.LANDSCAPE, 886 source: '/data/storage/el2/base/haps/entry/files/unfold_once_state.jpeg' 887 }, 888 { 889 foldState: wallpaper.FoldState.UNFOLD_TWICE_STATE, 890 rotateState: wallpaper.RotateState.PORTRAIT, 891 source: '/data/storage/el2/base/haps/entry/files/unfold_twice_state.jpeg' 892 } 893]; 894wallpaper.setAllWallpapers(wallpaperInfos, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => { 895 console.info(`success to setAllWallpapers.`); 896}).catch((error: BusinessError) => { 897 console.error(`failed to setAllWallpapers because: ${JSON.stringify(error)}`); 898}); 899``` 900 901## wallpaper.getPixelMap<sup>(deprecated)</sup> 902 903getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void; 904 905获取壁纸图片的像素图。 906 907> **说明：** 908> 909> 从 API version 7开始支持，从API version 9开始废弃。 910 911**需要权限**：ohos.permission.GET_WALLPAPER 912 913**系统能力**: SystemCapability.MiscServices.Wallpaper 914 915**系统接口**：此接口为系统接口。 916 917**参数：** 918 919| 参数名 | 类型 | 必填 | 说明 | 920| -------- | -------- | -------- | -------- | 921| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 922| callback | AsyncCallback<image.PixelMap> | 是 | 回调函数，调用成功则返回壁纸图片的像素图对象，调用失败则返回error信息。 | 923 924**示例：** 925 926```ts 927import { BusinessError } from '@kit.BasicServicesKit'; 928import { image } from '@kit.ImageKit'; 929 930wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: image.PixelMap) => { 931 if (error) { 932 console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`); 933 return; 934 } 935 console.info(`success to getPixelMap : ${JSON.stringify(data)}`); 936 }); 937``` 938 939## wallpaper.getPixelMap<sup>(deprecated)</sup> 940 941getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap> 942 943获取壁纸图片的像素图。 944 945> **说明：** 946> 947> 从 API version 7开始支持，从API version 9开始废弃。 948 949**需要权限**：ohos.permission.GET_WALLPAPER 950 951**系统能力**: SystemCapability.MiscServices.Wallpaper 952 953**系统接口**：此接口为系统接口。 954 955**参数：** 956 957| 参数名 | 类型 | 必填 | 说明 | 958| -------- | -------- | -------- | -------- | 959| wallpaperType | [WallpaperType](js-apis-wallpaper.md#wallpapertype7) | 是 | 壁纸类型。 | 960 961**返回值：** 962 963| 类型 | 说明 | 964| -------- | -------- | 965| Promise<image.PixelMap> | 调用成功则返回壁纸图片的像素图对象，调用失败则返回error信息。 | 966 967**示例：** 968 969```ts 970import { BusinessError } from '@kit.BasicServicesKit'; 971import { image } from '@kit.ImageKit'; 972 973wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: image.PixelMap) => { 974 console.info(`success to getPixelMap : ${JSON.stringify(data)}`); 975 }).catch((error: BusinessError) => { 976 console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`); 977}); 978```
