diff --git a/en/application-dev/reference/apis/js-apis-wallpaper.md b/en/application-dev/reference/apis/js-apis-wallpaper.md
index b7a9bad454b15ce99e38ff407df3aa4dc5e7b653..371e69dd03b0e5886456a189f9aceeb4444610c0 100644
--- a/en/application-dev/reference/apis/js-apis-wallpaper.md
+++ b/en/application-dev/reference/apis/js-apis-wallpaper.md
@@ -1,20 +1,19 @@
-# Wallpaper
+# @ohos.wallpaper
The **wallpaper** module is part of the theme framework and provides the system-level wallpaper management service in OpenHarmony. You can use the APIs of this module to show, set, and switch between wallpapers.
> **NOTE**
->
+>
> 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.
## Modules to Import
-```
+```js
import wallpaper from '@ohos.wallpaper';
```
-
## WallpaperType
Enumerates the wallpaper types.
@@ -27,15 +26,25 @@ Enumerates the wallpaper types.
| WALLPAPER_LOCKSCREEN | 1 |Lock screen wallpaper.|
-## wallpaper.getColors
+## RgbaColor
-getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void
+Defines the RGBA color space for the wallpaper.
-Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
+**System capability**: SystemCapability.MiscServices.Wallpaper
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync9+](#wallpapergetcolorssync9) instead.
+| Name| Type| Readable| Writable| Description|
+| -------- | -------- | -------- | -------- | -------- |
+| red | number | Yes| Yes| Red color. The value ranges from 0 to 255.|
+| green | number | Yes| Yes| Green color. The value ranges from 0 to 255.|
+| blue | number | Yes| Yes| Blue color. The value ranges from 0 to 255.|
+| alpha | number | Yes| Yes| Alpha value. The value ranges from 0 to 255.|
+
+
+## wallpaper.getColorsSync9+
+
+getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>
+
+Obtains the main color information of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -44,30 +53,24 @@ Obtains the main color information of the wallpaper of the specified type. This
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| callback | AsyncCallback<Array<[RgbaColor](#rgbacolor)>> | Yes| Callback used to return the main color information of the wallpaper.|
-**Example**
+**Return value**
- ```js
- 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.`);
- });
- ```
+| Type| Description|
+| -------- | -------- |
+| Array<[RgbaColor](#rgbacolor)> | Promise used to return the main color information of the wallpaper.|
+**Example**
-## wallpaper.getColors
+```js
+let colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
+```
-getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>>
+## wallpaper.getIdSync9+
-Obtains the main color information of the wallpaper of the specified type. This API uses a promise to return the result.
+getIdSync(wallpaperType: WallpaperType): number
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync9+](#wallpapergetcolorssync9) instead.
+Obtains the ID of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -81,24 +84,130 @@ Obtains the main color information of the wallpaper of the specified type. This
| Type| Description|
| -------- | -------- |
-| Promise<Array<[RgbaColor](#rgbacolor)>> | Promise used to return the main color information of the wallpaper.|
+| number | ID of the wallpaper. 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.|
**Example**
- ```js
- wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to getColors.`);
- }).catch((error) => {
- console.error(`failed to getColors because: ` + JSON.stringify(error));
- });
- ```
+```js
+let id = wallpaper.getIdSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
+```
+## wallpaper.getMinHeightSync9+
-## wallpaper.getColorsSync9+
+getMinHeightSync(): number
-getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>
+Obtains the minimum height of this wallpaper.
-Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
+**System capability**: SystemCapability.MiscServices.Wallpaper
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| 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.|
+
+**Example**
+
+```js
+let minHeight = wallpaper.getMinHeightSync();
+```
+
+## wallpaper.getMinWidthSync9+
+
+getMinWidthSync(): number
+
+Obtains the minimum width of this wallpaper.
+
+**System capability**: SystemCapability.MiscServices.Wallpaper
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| 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.|
+
+**Example**
+
+```js
+let minWidth = wallpaper.getMinWidthSync();
+```
+
+## wallpaper.isChangeAllowed9+
+
+isChangeAllowed(): boolean
+
+Checks whether to allow the application to change the wallpaper for the current user.
+
+**System capability**: SystemCapability.MiscServices.Wallpaper
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| boolean | 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.|
+
+**Example**
+
+```js
+let isChangeAllowed = wallpaper.isChangeAllowed();
+```
+
+## wallpaper.isUserChangeAllowed9+
+
+isUserChangeAllowed(): boolean
+
+Checks whether the user is allowed to set wallpapers.
+
+**System capability**: SystemCapability.MiscServices.Wallpaper
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| boolean | Whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.|
+
+**Example**
+
+```js
+let isUserChangeAllowed = wallpaper.isUserChangeAllowed();
+```
+
+## wallpaper.restore9+
+
+restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
+
+Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result.
+
+**Required permissions**: ohos.permission.SET_WALLPAPER
+
+**System capability**: SystemCapability.MiscServices.Wallpaper
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is error information.|
+
+**Example**
+
+```js
+wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
+ if (error) {
+ console.error(`failed to restore because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to restore.`);
+});
+```
+
+## wallpaper.restore9+
+
+restore(wallpaperType: WallpaperType): Promise<void>
+
+Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result.
+
+**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -112,24 +221,25 @@ Obtains the main color information of the wallpaper of the specified type. This
| Type| Description|
| -------- | -------- |
-| Array<[RgbaColor](#rgbacolor)> | Promise used to return the main color information of the wallpaper.|
+| Promise<void> | Promise that returns no value.|
**Example**
- ```js
- var colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
- ```
-
+```js
+wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
+ console.log(`success to restore.`);
+ }).catch((error) => {
+ console.error(`failed to restore because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.getId
+## wallpaper.setImage9+
-getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void
+setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
-Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
+Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result.
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getIdSync9+](#wallpapergetidsync9) instead.
+**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -137,31 +247,52 @@ Obtains the ID of the wallpaper of the specified type. This API uses an asynchro
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
+| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| 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.|
+| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is error information.|
**Example**
- ```js
- 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));
- });
- ```
-
+```js
+//The source type is string.
+let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
+wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
+ if (error) {
+ console.error(`failed to setImage because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to setImage.`);
+});
+
+// The source type is image.PixelMap.
+import image from '@ohos.multimedia.image';
+let imageSource = image.createImageSource("file://" + wallpaperPath);
+let opts = {
+ "desiredSize": {
+ "height": 3648,
+ "width": 2736
+ }
+};
+imageSource.createPixelMap(opts).then((pixelMap) => {
+ wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
+ if (error) {
+ console.error(`failed to setImage because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to setImage.`);
+ });
+}).catch((error) => {
+ console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.getId
+## wallpaper.setImage9+
-getId(wallpaperType: WallpaperType): Promise<number>
+setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>
-Obtains the ID of the wallpaper of the specified type. This API uses a promise to return the result.
+Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result.
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getIdSync9+](#wallpapergetidsync9) instead.
+**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -169,30 +300,53 @@ Obtains the ID of the wallpaper of the specified type. This API uses a promise t
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
+| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
-| 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.|
+| Promise<void> | Promise that returns no value.|
**Example**
- ```js
- 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));
- });
- ```
+```js
+//The source type is string.
+let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
+wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
+ console.log(`success to setImage.`);
+}).catch((error) => {
+ console.error(`failed to setImage because: ${JSON.stringify(error)}`);
+});
+
+// The source type is image.PixelMap.
+import image from '@ohos.multimedia.image';
+let imageSource = image.createImageSource("file://" + wallpaperPath);
+let opts = {
+ "desiredSize": {
+ "height": 3648,
+ "width": 2736
+ }
+};
+imageSource.createPixelMap(opts).then((pixelMap) => {
+ wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
+ console.log(`success to setImage.`);
+ }).catch((error) => {
+ console.error(`failed to setImage because: ${JSON.stringify(error)}`);
+ });
+}).catch((error) => {
+ console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
+});
+```
+## wallpaper.getFileSync9+
-## wallpaper.getIdSync9+
+getFileSync(wallpaperType: WallpaperType): number;
-getIdSync(wallpaperType: WallpaperType): number
+Obtains the wallpaper of the specified type.
-Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
+**Required permissions**: ohos.permission.GET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -206,105 +360,109 @@ Obtains the ID of the wallpaper of the specified type. This API uses an asynchro
| Type| Description|
| -------- | -------- |
-| number | ID of the wallpaper. 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.|
+| 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.|
**Example**
- ```js
- var id = wallpaper.getIdSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
- ```
-
+```js
+let file = wallpaper.getFileSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
+```
-## wallpaper.getMinHeight
+## wallpaper.getImage9+
-getMinHeight(callback: AsyncCallback<number>): void
+getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void;
-Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result.
+Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync9+](#wallpapergetminheightsync9) instead.
+**Required permissions**: ohos.permission.GET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
+**System API**: This is a system API.
+
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| 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.|
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes| Callback used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.|
**Example**
- ```js
- wallpaper.getMinHeight((error, data) => {
- if (error) {
- console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to getMinHeight: ` + JSON.stringify(data));
- });
- ```
+```js
+wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (error, data) {
+ if (error) {
+ console.error(`failed to getImage because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to getImage: ${JSON.stringify(data)}`);
+});
+```
-## wallpaper.getMinHeight
+## wallpaper.getImage9+
-getMinHeight(): Promise<number>
+getImage(wallpaperType: WallpaperType): Promise<image.PixelMap>
-Obtains the minimum height of this wallpaper. This API uses a promise to return the result.
+Obtains the pixel map for the wallpaper of the specified type. This API uses a promise to return the result.
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync9+](#wallpapergetminheightsync9) instead.
+**Required permissions**: ohos.permission.GET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+
**Return value**
| Type| Description|
| -------- | -------- |
-| 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.|
+| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.|
**Example**
- ```js
- wallpaper.getMinHeight().then((data) => {
- console.log(`success to getMinHeight: ` + JSON.stringify(data));
+```js
+wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
+ console.log(`success to getImage: ${JSON.stringify(data)}`);
}).catch((error) => {
- console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
- });
- ```
-
+ console.error(`failed to getImage because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.getMinHeightSync9+
+## wallpaper.on('colorChange')9+
-getMinHeightSync(): number
+on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void
-Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result.
+Subscribes to the wallpaper color change event.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Return value**
+**Parameters**
-| Type| Description|
-| -------- | -------- |
-| 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.|
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| type | string | Yes| Type of the event to subscribe to. The value **'colorChange'** indicates subscribing to the wallpaper color change event.|
+| callback | function | Yes| Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned.
- colors
Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).
- wallpaperType
Wallpaper type.|
**Example**
- ```js
- var minHeight = wallpaper.getMinHeightSync();
- ```
-
-
-## wallpaper.getMinWidth
+```js
+let listener = (colors, wallpaperType) => {
+ console.log(`wallpaper color changed.`);
+};
+wallpaper.on('colorChange', listener);
+```
-getMinWidth(callback: AsyncCallback<number>): void
+## wallpaper.off('colorChange')9+
-Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result.
+off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void
-> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync9+](#wallpapergetminwidthsync9) instead.
+Unsubscribes from the wallpaper color change event.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -312,80 +470,96 @@ Obtains the minimum width of this wallpaper. This API uses an asynchronous callb
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| 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.|
+| type | string | Yes| Type of the event to unsubscribe from. The value **'colorChange'** indicates unsubscribing from the wallpaper color change event.|
+| 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**.
- colors
Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).
- wallpaperType
Wallpaper type.|
**Example**
- ```js
- wallpaper.getMinWidth((error, data) => {
- if (error) {
- console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to getMinWidth: ` + JSON.stringify(data));
- });
- ```
-
+```js
+let listener = (colors, wallpaperType) => {
+ console.log(`wallpaper color changed.`);
+};
+wallpaper.on('colorChange', listener);
+// Unsubscribe from the listener.
+wallpaper.off('colorChange', listener);
+// Unsubscribe from all subscriptions of the colorChange type.
+wallpaper.off('colorChange');
+```
-## wallpaper.getMinWidth
+## wallpaper.getColors(deprecated)
-getMinWidth(): Promise<number>
+getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void
-Obtains the minimum width of this wallpaper. This API uses a promise to return the result.
+Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync9+](#wallpapergetminwidthsync9) instead.
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync9+](#wallpapergetcolorssync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Return value**
+**Parameters**
-| Type| Description|
-| -------- | -------- |
-| 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.|
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+| callback | AsyncCallback<Array<[RgbaColor](#rgbacolor)>> | Yes| Callback used to return the main color information of the wallpaper.|
**Example**
- ```js
- wallpaper.getMinWidth().then((data) => {
- console.log(`success to getMinWidth: ` + JSON.stringify(data));
- }).catch((error) => {
- console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
- });
- ```
+```js
+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: ${JSON.stringify(data)}`);
+});
+```
+## wallpaper.getColors(deprecated)
-## wallpaper.getMinWidthSync9+
+getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>>
-getMinWidthSync(): number
+Obtains the main color information of the wallpaper of the specified type. This API uses a promise to return the result.
-Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result.
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync9+](#wallpapergetcolorssync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+
**Return value**
| Type| Description|
| -------- | -------- |
-| 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.|
+| Promise<Array<[RgbaColor](#rgbacolor)>> | Promise used to return the main color information of the wallpaper.|
**Example**
- ```js
- var minWidth = wallpaper.getMinWidthSync();
- ```
-
+```js
+wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
+ console.log(`success to getColors: ${JSON.stringify(data)}`);
+ }).catch((error) => {
+ console.error(`failed to getColors because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.isChangePermitted
+## wallpaper.getId(deprecated)
-isChangePermitted(callback: AsyncCallback<boolean>): void
+getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void
-Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result.
+Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed9+](#wallpaperischangeallowed9) instead.
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getIdSync9+](#wallpapergetidsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -393,136 +567,152 @@ Checks whether to allow the application to change the wallpaper for the current
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| 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.|
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+| 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.|
**Example**
- ```js
- wallpaper.isChangePermitted((error, data) => {
- if (error) {
- console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to isChangePermitted: ` + JSON.stringify(data));
- });
- ```
-
+```js
+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.isChangePermitted
+## wallpaper.getId(deprecated)
-isChangePermitted(): Promise<boolean>
+getId(wallpaperType: WallpaperType): Promise<number>
-Checks whether to allow the application to change the wallpaper for the current user. This API uses a promise to return the result.
+Obtains the ID of the wallpaper of the specified type. This API uses a promise to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed9+](#wallpaperischangeallowed9) instead.
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getIdSync9+](#wallpapergetidsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
+
**Return value**
| Type| Description|
| -------- | -------- |
-| 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.|
+| 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.|
**Example**
- ```js
- wallpaper.isChangePermitted().then((data) => {
- console.log(`success to isChangePermitted: ` + JSON.stringify(data));
+```js
+wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
+ console.log(`success to getId: ${JSON.stringify(data)}`);
}).catch((error) => {
- console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
- });
- ```
+ console.error(`failed to getId because: ${JSON.stringify(error)}`);
+});
+```
+## wallpaper.getMinHeight(deprecated)
-## wallpaper.isChangeAllowed9+
+getMinHeight(callback: AsyncCallback<number>): void
-isChangeAllowed(): boolean
+Obtains the minimum height of this wallpaper. This API uses an asynchronous callback to return the result.
-Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result.
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync9+](#wallpapergetminheightsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Return value**
+**Parameters**
-| Type| Description|
-| -------- | -------- |
-| boolean | 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.|
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| 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.|
**Example**
- ```js
- var isChangeAllowed = wallpaper.isChangeAllowed();
- ```
-
+```js
+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.isOperationAllowed
+## wallpaper.getMinHeight(deprecated)
-isOperationAllowed(callback: AsyncCallback<boolean>): void
+getMinHeight(): Promise<number>
-Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result.
+Obtains the minimum height of this wallpaper. This API uses a promise to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isUserChangeAllowed9+](#wallpaperisuserchangeallowed9) instead.
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync9+](#wallpapergetminheightsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Parameters**
+**Return value**
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| 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.|
+| Type| Description|
+| -------- | -------- |
+| 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.|
**Example**
- ```js
- wallpaper.isOperationAllowed((error, data) => {
- if (error) {
- console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
- });
- ```
-
+```js
+wallpaper.getMinHeight().then((data) => {
+ console.log(`success to getMinHeight: ${JSON.stringify(data)}`);
+}).catch((error) => {
+ console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.isOperationAllowed
+## wallpaper.getMinWidth(deprecated)
-isOperationAllowed(): Promise<boolean>
+getMinWidth(callback: AsyncCallback<number>): void
-Checks whether the user is allowed to set wallpapers. This API uses a promise to return the result.
+Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isUserChangeAllowed9+](#wallpaperisuserchangeallowed9) instead.
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync9+](#wallpapergetminwidthsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Return value**
+**Parameters**
-| Type| Description|
-| -------- | -------- |
-| 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.|
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| 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.|
**Example**
- ```js
- wallpaper.isOperationAllowed().then((data) => {
- console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
- }).catch((error) => {
- console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
- });
- ```
+```js
+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(deprecated)
-## wallpaper.isUserChangeAllowed9+
+getMinWidth(): Promise<number>
-isUserChangeAllowed(): boolean
+Obtains the minimum width of this wallpaper. This API uses a promise to return the result.
-Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result.
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync9+](#wallpapergetminwidthsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -530,26 +720,27 @@ Checks whether the user is allowed to set wallpapers. This API uses an asynchron
| Type| Description|
| -------- | -------- |
-| boolean | Whether the user is allowed to set wallpapers. The value **true** means that the operation is allowed, and **false** means the opposite.|
+| 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.|
**Example**
- ```js
- var isUserChangeAllowed = wallpaper.isUserChangeAllowed();
- ```
-
+```js
+wallpaper.getMinWidth().then((data) => {
+ console.log(`success to getMinWidth: ${JSON.stringify(data)}`);
+ }).catch((error) => {
+ console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.reset
+## wallpaper.isChangePermitted(deprecated)
-reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
+isChangePermitted(callback: AsyncCallback<boolean>): void
-Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result.
+Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore9+](#wallpaperrestore9) instead.
-
-**Required permissions**: ohos.permission.SET_WALLPAPER
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed9+](#wallpaperischangeallowed9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -557,66 +748,57 @@ Resets the wallpaper of the specified type to the default wallpaper. This API us
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned.|
+| 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.|
**Example**
- ```js
- wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
- if (error) {
- console.error(`failed to reset because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to reset.`);
- });
- ```
-
+```js
+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.reset
+## wallpaper.isChangePermitted(deprecated)
-reset(wallpaperType: WallpaperType): Promise<void>
+isChangePermitted(): Promise<boolean>
-Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result.
+Checks whether to allow the application to change the wallpaper for the current user. This API uses a promise to return the result.
> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore9+](#wallpaperrestore9) instead.
-
-**Required permissions**: ohos.permission.SET_WALLPAPER
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed9+](#wallpaperischangeallowed9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-
**Return value**
| Type| Description|
| -------- | -------- |
-| Promise<void> | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.|
+| 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.|
**Example**
- ```js
- wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to reset.`);
- }).catch((error) => {
- console.error(`failed to reset because: ` + JSON.stringify(error));
- });
- ```
-
+```js
+wallpaper.isChangePermitted().then((data) => {
+ console.log(`success to isChangePermitted: ${JSON.stringify(data)}`);
+}).catch((error) => {
+ console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.restore9+
+## wallpaper.isOperationAllowed(deprecated)
-restore(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
+isOperationAllowed(callback: AsyncCallback<boolean>): void
-Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result.
+Checks whether the user is allowed to set wallpapers. This API uses an asynchronous callback to return the result.
-**Required permissions**: ohos.permission.SET_WALLPAPER
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isUserChangeAllowed9+](#wallpaperisuserchangeallowed9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -624,64 +806,57 @@ Resets the wallpaper of the specified type to the default wallpaper. This API us
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned.|
+| 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.|
**Example**
- ```js
- wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
- if (error) {
- console.error(`failed to restore because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to restore.`);
- });
- ```
-
+```js
+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.restore9+
+## wallpaper.isOperationAllowed(deprecated)
-restore(wallpaperType: WallpaperType): Promise<void>
+isOperationAllowed(): Promise<boolean>
-Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result.
+Checks whether the user is allowed to set wallpapers. This API uses a promise to return the result.
-**Required permissions**: ohos.permission.SET_WALLPAPER
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isUserChangeAllowed9+](#wallpaperisuserchangeallowed9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-
**Return value**
| Type| Description|
| -------- | -------- |
-| Promise<void> | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.|
+| 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.|
**Example**
- ```js
- wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to restore.`);
+```js
+wallpaper.isOperationAllowed().then((data) => {
+ console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`);
}).catch((error) => {
- console.error(`failed to restore because: ` + JSON.stringify(error));
- });
- ```
-
+ console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.setWallpaper
+## wallpaper.reset(deprecated)
-setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
+reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
-Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result.
+Resets the wallpaper of the specified type to the default wallpaper. This API uses an asynchronous callback to return the result.
> **NOTE**
>
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.setImage9+](#wallpapersetimage9) instead.
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore9+](#wallpaperrestore9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
@@ -691,55 +866,30 @@ Sets a specified source as the wallpaper of a specified type. This API uses an a
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
+| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is error information.|
**Example**
- ```js
- //The source type is string.
- let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
- wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
- if (error) {
- console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to setWallpaper.`);
- });
-
- // The source type is image.PixelMap.
- import image from '@ohos.multimedia.image';
- let imageSource = image.createImageSource("file://" + wallpaperPath);
- let opts = {
- "desiredSize": {
- "height": 3648,
- "width": 2736
- }
- };
- imageSource.createPixelMap(opts).then((pixelMap) => {
- wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
- 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));
- });
- ```
-
+```js
+wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
+ if (error) {
+ console.error(`failed to reset because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to reset.`);
+});
+```
-## wallpaper.setWallpaper
+## wallpaper.reset(deprecated)
-setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>
+reset(wallpaperType: WallpaperType): Promise<void>
-Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result.
+Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result.
> **NOTE**
->
-> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.setImage9+](#wallpapersetimage9) instead.
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore9+](#wallpaperrestore9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
@@ -749,53 +899,34 @@ Sets a specified source as the wallpaper of a specified type. This API uses a pr
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
-| Promise<void> | Promise used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
+| Promise<void> | Promise that returns no value.|
**Example**
- ```js
- //The source type is string.
- let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
- wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to setWallpaper.`);
- }).catch((error) => {
- console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
- });
-
- // The source type is image.PixelMap.
- import image from '@ohos.multimedia.image';
- let imageSource = image.createImageSource("file://" + wallpaperPath);
- let opts = {
- "desiredSize": {
- "height": 3648,
- "width": 2736
- }
- };
- imageSource.createPixelMap(opts).then((pixelMap) => {
- wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- 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));
- });
- ```
-
+```js
+wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
+ console.log(`success to reset.`);
+}).catch((error) => {
+ console.error(`failed to reset because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.setImage9+
+## wallpaper.setWallpaper(deprecated)
-setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
+setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void
Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result.
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.setImage9+](#wallpapersetimage9) instead.
+
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
@@ -804,51 +935,54 @@ Sets a specified source as the wallpaper of a specified type. This API uses an a
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
+| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
+| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is error information.|
**Example**
- ```js
- //The source type is string.
- let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
- wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
- if (error) {
- console.error(`failed to setImage because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to setImage.`);
- });
-
- // The source type is image.PixelMap.
- import image from '@ohos.multimedia.image';
- let imageSource = image.createImageSource("file://" + wallpaperPath);
- let opts = {
- "desiredSize": {
- "height": 3648,
- "width": 2736
- }
- };
- imageSource.createPixelMap(opts).then((pixelMap) => {
- wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
- if (error) {
- console.error(`failed to setImage because: ` + JSON.stringify(error));
- return;
- }
- console.log(`success to setImage.`);
- });
- }).catch((error) => {
- console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
- });
- ```
+```js
+//The source type is string.
+let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
+wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
+ if (error) {
+ console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to setWallpaper.`);
+});
+
+// The source type is image.PixelMap.
+import image from '@ohos.multimedia.image';
+let imageSource = image.createImageSource("file://" + wallpaperPath);
+let opts = {
+ "desiredSize": {
+ "height": 3648,
+ "width": 2736
+ }
+};
+imageSource.createPixelMap(opts).then((pixelMap) => {
+ wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
+ 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(deprecated)
-## wallpaper.setImage9+
+setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>
-setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise<void>
+Sets a specified source as the wallpaper of a specified type. This API uses a promise to return the result.
-Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result.
+> **NOTE**
+>
+> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.setImage9+](#wallpapersetimage9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
@@ -858,48 +992,48 @@ Sets a specified source as the wallpaper of a specified type. This API uses an a
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| source | string \|[image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
+| source | string \| [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| URI of a JPEG or PNG file, or bitmap of a PNG file.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
-| Promise<void> | Promise used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
+| Promise<void> | Promise that returns no value.|
**Example**
- ```js
- //The source type is string.
- let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
- wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to setImage.`);
+```js
+//The source type is string.
+let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
+wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
+ console.log(`success to setWallpaper.`);
}).catch((error) => {
- console.error(`failed to setImage because: ` + JSON.stringify(error));
- });
+ console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
+});
- // The source type is image.PixelMap.
- import image from '@ohos.multimedia.image';
- let imageSource = image.createImageSource("file://" + wallpaperPath);
- let opts = {
- "desiredSize": {
- "height": 3648,
- "width": 2736
- }
- };
- imageSource.createPixelMap(opts).then((pixelMap) => {
- wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to setImage.`);
- }).catch((error) => {
- console.error(`failed to setImage because: ` + JSON.stringify(error));
- });
- }).catch((error) => {
- console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
- });
- ```
+// The source type is image.PixelMap.
+import image from '@ohos.multimedia.image';
+let imageSource = image.createImageSource("file://" + wallpaperPath);
+let opts = {
+ "desiredSize": {
+ "height": 3648,
+ "width": 2736
+ }
+};
+imageSource.createPixelMap(opts).then((pixelMap) => {
+ wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
+ 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)}`);
+});
+```
-## wallpaper.getFile8+
+## wallpaper.getFile(deprecated)
getFile(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void
@@ -922,17 +1056,17 @@ Obtains the wallpaper of the specified type. This API uses an asynchronous callb
**Example**
- ```js
- 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));
- });
- ```
+```js
+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)}`);
+});
+```
-## wallpaper.getFile8+
+## wallpaper.getFile(deprecated)
getFile(wallpaperType: WallpaperType): Promise<number>
@@ -960,45 +1094,15 @@ Obtains the wallpaper of the specified type. This API uses a promise to return t
**Example**
- ```js
- wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.log(`success to getFile: ` + JSON.stringify(data));
+```js
+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));
- });
- ```
-
-
-## wallpaper.getFileSync9+
-
-getFileSync(wallpaperType: WallpaperType): number;
-
-Obtains the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
-
-**Required permissions**: ohos.permission.GET_WALLPAPER
-
-**System capability**: SystemCapability.MiscServices.Wallpaper
-
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-
-**Return value**
-
-| Type| Description|
-| -------- | -------- |
-| 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.|
-
-**Example**
-
- ```js
- var file = wallpaper.getFileSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
- ```
-
+ console.error(`failed to getFile because: ${JSON.stringify(error)}`);
+});
+```
-## wallpaper.getPixelMap
+## wallpaper.getPixelMap(deprecated)
getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void;
@@ -1012,7 +1116,7 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses an
**System capability**: SystemCapability.MiscServices.Wallpaper
-**System API**: This is a system API and cannot be called by third-party applications.
+**System API**: This is a system API.
**Parameters**
@@ -1023,15 +1127,17 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses an
**Example**
- ```js
- wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (err, data) {
- console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem err : ' + JSON.stringify(err));
- console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem data : ' + JSON.stringify(data));
+```js
+wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (error, data) {
+ if (error) {
+ console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`);
+ return;
+ }
+ console.log(`success to getPixelMap : ${JSON.stringify(data)}`);
});
- ```
-
+```
-## wallpaper.getPixelMap
+## wallpaper.getPixelMap(deprecated)
getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap>
@@ -1045,7 +1151,7 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses a p
**System capability**: SystemCapability.MiscServices.Wallpaper
-**System API**: This is a system API and cannot be called by third-party applications.
+**System API**: This is a system API.
**Parameters**
@@ -1061,144 +1167,10 @@ Obtains the pixel map for the wallpaper of the specified type. This API uses a p
**Example**
- ```js
- wallpaper.getPixelMap(wallpaper.WallpaperType.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));
- });
- ```
-
-
-## wallpaper.getImage9+
-
-getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void;
-
-Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
-
-**Required permissions**: ohos.permission.GET_WALLPAPER
-
-**System capability**: SystemCapability.MiscServices.Wallpaper
-
-**System API**: This is a system API and cannot be called by third-party applications.
-
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes| Callback used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.|
-
-**Example**
-
- ```js
- wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (err, data) {
- console.info('wallpaperXTS ===> testgetImageCallbackSystem err : ' + JSON.stringify(err));
- console.info('wallpaperXTS ===> testgetImageCallbackSystem data : ' + JSON.stringify(data));
- });
- ```
-
-
-## wallpaper.getImage9+
-
-getImage(wallpaperType: WallpaperType): Promise<image.PixelMap>
-
-Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
-
-**Required permissions**: ohos.permission.GET_WALLPAPER
-
-**System capability**: SystemCapability.MiscServices.Wallpaper
-
-**System API**: This is a system API and cannot be called by third-party applications.
-
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
-
-**Return value**
-
-| Type| Description|
-| -------- | -------- |
-| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the result. Returns the pixel map size of the wallpaper if the operation is successful; returns an error message otherwise.|
-
-**Example**
-
- ```js
- wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
- console.info('wallpaperXTS ===> testgetImagePromiseSystem data : ' + data);
- console.info('wallpaperXTS ===> testgetImagePromiseSystem data : ' + JSON.stringify(data));
- }).catch((err) => {
- console.info('wallpaperXTS ===> testgetImagePromiseSystem err : ' + err);
- console.info('wallpaperXTS ===> testgetImagePromiseSystem err : ' + JSON.stringify(err));
- });
- ```
-
-
-## wallpaper.on('colorChange')9+
-
-on(type: 'colorChange', callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void
-
-Subscribes to the wallpaper color change event.
-
-**System capability**: SystemCapability.MiscServices.Wallpaper
-
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| type | string | Yes| Type of the event to subscribe to. The value **'colorChange'** indicates subscribing to the wallpaper color change event.|
-| callback | function | Yes| Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned.
- colors
Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).
- wallpaperType
Wallpaper type.|
-
-**Example**
-
- ```js
- let listener = (colors, wallpaperType) => {
- console.log(`wallpaper color changed.`);
- };
- wallpaper.on('colorChange', listener);
- ```
-
-
-## wallpaper.off('colorChange')9+
-
-off(type: 'colorChange', callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void
-
-Unsubscribes from the wallpaper color change event.
-
-**System capability**: SystemCapability.MiscServices.Wallpaper
-
-**Parameters**
-
-| Name| Type| Mandatory| Description|
-| -------- | -------- | -------- | -------- |
-| type | string | Yes| Type of the event to unsubscribe from. The value **colorChange** indicates unsubscribing from the wallpaper color change event.|
-| callback | function | No| Callback for the wallpaper color change event. If this parameter is not specified, all callbacks corresponding to the wallpaper color change event are invoked.
- colors
Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).
- wallpaperType
Wallpaper type.|
-
-**Example**
-
- ```js
- let listener = (colors, wallpaperType) => {
- console.log(`wallpaper color changed.`);
- };
- wallpaper.on('colorChange', listener);
- // Unsubscribe from the listener.
- wallpaper.off('colorChange', listener);
- // Unsubscribe from all subscriptions of the colorChange type.
- wallpaper.off('colorChange');
- ```
-
-
-## RgbaColor
-
-**System capability**: SystemCapability.MiscServices.Wallpaper
-
-| Name| Type| Readable| Writable| Description|
-| -------- | -------- | -------- | -------- | -------- |
-| red | number | Yes| Yes| Red color. The value ranges from 0 to 255.|
-| green | number | Yes| Yes| Green color. The value ranges from 0 to 255.|
-| blue | number | Yes| Yes| Blue color. The value ranges from 0 to 255.|
-| alpha | number | Yes| Yes| Alpha value. The value ranges from 0 to 255.|
+```js
+wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
+ console.log(`success to getPixelMap : ${JSON.stringify(data)}`);
+ }).catch((error) => {
+ console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`);
+});
+```