Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
“31aa48e240effffc1283fea57ed05058a4645e69”上不存在“2.0/src/connector/odbc/git@gitcode.net:taosdata/tdengine.git”
未验证 提交 5ec1f71e 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!12550 翻译完成 12397+12288 

Merge pull request !12550 from ester.zhou/cherry-pick-1671091543
上级 1d82430d 5a8dce49
显示空白变更内容
内联 并排
Showing with 628 addition and 656 deletion
en/application-dev/reference/apis/js-apis-wallpaper.md
浏览文件 @ 5ec1f71e
# 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.
......@@ -10,11 +10,10 @@ The **wallpaper** module is part of the theme framework and provides the system-
## 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.getColorsSync<sup>9+</sup>](#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.getColorsSync<sup>9+</sup>
getColorsSync(wallpaperType: WallpaperType): Array&lt;RgbaColor&gt;
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&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | 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&lt;[RgbaColor](#rgbacolor)&gt; | 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&lt;Array&lt;RgbaColor&gt;&gt;
## wallpaper.getIdSync<sup>9+</sup>
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.getColorsSync<sup>9+</sup>](#wallpapergetcolorssync9) instead.
Obtains the ID of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -81,87 +84,101 @@ Obtains the main color information of the wallpaper of the specified type. This
| Type| Description|
| -------- | -------- |
| Promise&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | 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.getColorsSync<sup>9+</sup>
## wallpaper.getMinHeightSync<sup>9+</sup>
getColorsSync(wallpaperType: WallpaperType): Array&lt;RgbaColor&gt;
getMinHeightSync(): number
Obtains the main color information of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
Obtains the minimum height of this wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
| 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.getMinWidthSync<sup>9+</sup>
getMinWidthSync(): number
Obtains the minimum width of this wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Return value**
| Type| Description|
| -------- | -------- |
| Array&lt;[RgbaColor](#rgbacolor)&gt; | Promise used to return the main color information of the wallpaper.|
| 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 colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
```
```js
let minWidth = wallpaper.getMinWidthSync();
```
## wallpaper.isChangeAllowed<sup>9+</sup>
## wallpaper.getId
isChangeAllowed(): boolean
getId(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): void
Checks whether to allow the application to change the wallpaper for the current user.
Obtains the ID 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.getIdSync<sup>9+</sup>](#wallpapergetidsync9) instead.
**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.isUserChangeAllowed<sup>9+</sup>
isUserChangeAllowed(): boolean
Checks whether the user is allowed to set wallpapers.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
| callback | AsyncCallback&lt;number&gt; | 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.|
| 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
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
let isUserChangeAllowed = wallpaper.isUserChangeAllowed();
```
## wallpaper.getId
## wallpaper.restore<sup>9+</sup>
getId(wallpaperType: WallpaperType): Promise&lt;number&gt;
restore(wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
Obtains the ID of the wallpaper of the 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 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.getIdSync<sup>9+</sup>](#wallpapergetidsync9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -170,29 +187,27 @@ Obtains the ID of the wallpaper of the specified type. This API uses a promise t
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | 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.|
| callback | AsyncCallback&lt;void&gt; | 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).then((data) => {
console.log(`success to getId: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getId because: ` + JSON.stringify(error));
});
```
```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.restore<sup>9+</sup>
## wallpaper.getIdSync<sup>9+</sup>
restore(wallpaperType: WallpaperType): Promise&lt;void&gt;
getIdSync(wallpaperType: WallpaperType): number
Resets the wallpaper of the specified type to the default wallpaper. This API uses a promise to return the result.
Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -206,24 +221,25 @@ 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.|
| Promise&lt;void&gt; | Promise that returns no value.|
**Example**
```js
var id = wallpaper.getIdSync(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.getMinHeight
## wallpaper.setImage<sup>9+</sup>
getMinHeight(callback: AsyncCallback&lt;number&gt;): void
setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
Obtains the minimum height of this wallpaper. 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.getMinHeightSync<sup>9+</sup>](#wallpapergetminheightsync9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -231,161 +247,254 @@ Obtains the minimum height of this wallpaper. This API uses an asynchronous call
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;number&gt; | 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.|
| 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&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is error information.|
**Example**
```js
wallpaper.getMinHeight((error, 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 getMinHeight because: ` + JSON.stringify(error));
console.error(`failed to setImage because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to getMinHeight: ` + JSON.stringify(data));
});
```
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.getMinHeight
## wallpaper.setImage<sup>9+</sup>
getMinHeight(): Promise&lt;number&gt;
setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise&lt;void&gt;
Obtains the minimum height of this wallpaper. 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.getMinHeightSync<sup>9+</sup>](#wallpapergetminheightsync9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| 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&lt;number&gt; | 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&lt;void&gt; | Promise that returns no value.|
**Example**
```js
wallpaper.getMinHeight().then((data) => {
console.log(`success to getMinHeight: ` + 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).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 getMinHeight because: ` + JSON.stringify(error));
console.error(`failed to setImage because: ${JSON.stringify(error)}`);
});
```
}).catch((error) => {
console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});
```
## wallpaper.getFileSync<sup>9+</sup>
## wallpaper.getMinHeightSync<sup>9+</sup>
getFileSync(wallpaperType: WallpaperType): number;
getMinHeightSync(): number
Obtains the wallpaper of the specified type.
Obtains the minimum height of this wallpaper. 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 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.|
| 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 minHeight = wallpaper.getMinHeightSync();
```
```js
let file = wallpaper.getFileSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
```
## wallpaper.getMinWidth
## wallpaper.getImage<sup>9+</sup>
getMinWidth(callback: AsyncCallback&lt;number&gt;): void
getImage(wallpaperType: WallpaperType, callback: AsyncCallback&lt;image.PixelMap&gt;): void;
Obtains the minimum width 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.getMinWidthSync<sup>9+</sup>](#wallpapergetminwidthsync9) 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&lt;number&gt; | 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.|
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
| callback | AsyncCallback&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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.getMinWidth((error, data) => {
```js
wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (error, data) {
if (error) {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
console.error(`failed to getImage because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to getMinWidth: ` + JSON.stringify(data));
});
```
console.log(`success to getImage: ${JSON.stringify(data)}`);
});
```
## wallpaper.getMinWidth
## wallpaper.getImage<sup>9+</sup>
getMinWidth(): Promise&lt;number&gt;
getImage(wallpaperType: WallpaperType): Promise&lt;image.PixelMap&gt;
Obtains the minimum width 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.getMinWidthSync<sup>9+</sup>](#wallpapergetminwidthsync9) 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&lt;number&gt; | 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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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.getMinWidth().then((data) => {
console.log(`success to getMinWidth: ` + 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 getMinWidth because: ` + JSON.stringify(error));
});
```
console.error(`failed to getImage because: ${JSON.stringify(error)}`);
});
```
## wallpaper.getMinWidthSync<sup>9+</sup>
## wallpaper.on('colorChange')<sup>9+</sup>
getMinWidthSync(): number
on(type: 'colorChange', callback: (colors: Array&lt;RgbaColor&gt;, wallpaperType: WallpaperType) =&gt; void): void
Obtains the minimum width 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 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|
| -------- | -------- | -------- | -------- |
| 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.<br>- colors<br> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br> Wallpaper type.|
**Example**
```js
var minWidth = wallpaper.getMinWidthSync();
```
```js
let listener = (colors, wallpaperType) => {
console.log(`wallpaper color changed.`);
};
wallpaper.on('colorChange', listener);
```
## wallpaper.off('colorChange')<sup>9+</sup>
## wallpaper.isChangePermitted
off(type: 'colorChange', callback?: (colors: Array&lt;RgbaColor&gt;, wallpaperType: WallpaperType) =&gt; void): void
isChangePermitted(callback: AsyncCallback&lt;boolean&gt;): void
Unsubscribes from the wallpaper color change event.
Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result.
**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 set, this API unsubscribes from all callbacks corresponding to **type**.<br>- colors<br> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br> Wallpaper type.|
**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');
```
## wallpaper.getColors<sup>(deprecated)</sup>
getColors(wallpaperType: WallpaperType, callback: AsyncCallback&lt;Array&lt;RgbaColor&gt;&gt;): void
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.isChangeAllowed<sup>9+</sup>](#wallpaperischangeallowed9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync<sup>9+</sup>](#wallpapergetcolorssync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -393,80 +502,129 @@ Checks whether to allow the application to change the wallpaper for the current
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 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&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Yes| Callback used to return the main color information of the wallpaper.|
**Example**
```js
wallpaper.isChangePermitted((error, data) => {
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
console.error(`failed to getColors because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
});
```
console.log(`success to getColors: ${JSON.stringify(data)}`);
});
```
## wallpaper.isChangePermitted
## wallpaper.getColors<sup>(deprecated)</sup>
isChangePermitted(): Promise&lt;boolean&gt;
getColors(wallpaperType: WallpaperType): Promise&lt;Array&lt;RgbaColor&gt;&gt;
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 main color information 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.isChangeAllowed<sup>9+</sup>](#wallpaperischangeallowed9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getColorsSync<sup>9+</sup>](#wallpapergetcolorssync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;boolean&gt; | 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&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Promise used to return the main color information of the wallpaper.|
**Example**
```js
wallpaper.isChangePermitted().then((data) => {
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getColors: ${JSON.stringify(data)}`);
}).catch((error) => {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
});
```
console.error(`failed to getColors because: ${JSON.stringify(error)}`);
});
```
## wallpaper.getId<sup>(deprecated)</sup>
## wallpaper.isChangeAllowed<sup>9+</sup>
getId(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): void
isChangeAllowed(): boolean
Obtains the ID of the wallpaper of the specified type. 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.getIdSync<sup>9+</sup>](#wallpapergetidsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
| callback | AsyncCallback&lt;number&gt; | 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.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to getId because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to getId: ${JSON.stringify(data)}`);
});
```
## wallpaper.getId<sup>(deprecated)</sup>
getId(wallpaperType: WallpaperType): Promise&lt;number&gt;
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.getIdSync<sup>9+</sup>](#wallpapergetidsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**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.|
| Promise&lt;number&gt; | 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
var isChangeAllowed = wallpaper.isChangeAllowed();
```
```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)}`);
});
```
## wallpaper.isOperationAllowed
## wallpaper.getMinHeight<sup>(deprecated)</sup>
isOperationAllowed(callback: AsyncCallback&lt;boolean&gt;): void
getMinHeight(callback: AsyncCallback&lt;number&gt;): void
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 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.isUserChangeAllowed<sup>9+</sup>](#wallpaperisuserchangeallowed9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync<sup>9+</sup>](#wallpapergetminheightsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -474,30 +632,29 @@ Checks whether the user is allowed to set wallpapers. This API uses an asynchron
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 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.|
| callback | AsyncCallback&lt;number&gt; | 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
wallpaper.isOperationAllowed((error, data) => {
```js
wallpaper.getMinHeight((error, data) => {
if (error) {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
});
```
console.log(`success to getMinHeight: ${JSON.stringify(data)}`);
});
```
## wallpaper.isOperationAllowed
## wallpaper.getMinHeight<sup>(deprecated)</sup>
isOperationAllowed(): Promise&lt;boolean&gt;
getMinHeight(): Promise&lt;number&gt;
Checks whether the user is allowed to set wallpapers. This API uses a promise 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.isUserChangeAllowed<sup>9+</sup>](#wallpaperisuserchangeallowed9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinHeightSync<sup>9+</sup>](#wallpapergetminheightsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
......@@ -505,24 +662,57 @@ Checks whether the user is allowed to set wallpapers. This API uses a promise to
| Type| Description|
| -------- | -------- |
| Promise&lt;boolean&gt; | 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.|
| Promise&lt;number&gt; | 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().then((data) => {
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
});
```
```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.getMinWidth<sup>(deprecated)</sup>
## wallpaper.isUserChangeAllowed<sup>9+</sup>
getMinWidth(callback: AsyncCallback&lt;number&gt;): void
isUserChangeAllowed(): boolean
Obtains the minimum width of this 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.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.getMinWidthSync<sup>9+</sup>](#wallpapergetminwidthsync9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;number&gt; | 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.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<sup>(deprecated)</sup>
getMinWidth(): Promise&lt;number&gt;
Obtains the minimum width 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.getMinWidthSync<sup>9+</sup>](#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&lt;number&gt; | 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<sup>(deprecated)</sup>
reset(wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
isChangePermitted(callback: AsyncCallback&lt;boolean&gt;): 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.restore<sup>9+</sup>](#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.isChangeAllowed<sup>9+</sup>](#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&lt;void&gt; | 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&lt;boolean&gt; | 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) => {
```js
wallpaper.isChangePermitted((error, data) => {
if (error) {
console.error(`failed to reset because: ` + JSON.stringify(error));
console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to reset.`);
});
```
console.log(`success to isChangePermitted: ${JSON.stringify(data)}`);
});
```
## wallpaper.reset
## wallpaper.isChangePermitted<sup>(deprecated)</sup>
reset(wallpaperType: WallpaperType): Promise&lt;void&gt;
isChangePermitted(): Promise&lt;boolean&gt;
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.restore<sup>9+</sup>](#wallpaperrestore9) instead.
**Required permissions**: ohos.permission.SET_WALLPAPER
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.isChangeAllowed<sup>9+</sup>](#wallpaperischangeallowed9) instead.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**System capability**: SystemCapability.MiscServices.Wallpaper
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.|
| Promise&lt;boolean&gt; | 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.restore<sup>9+</sup>
## wallpaper.isOperationAllowed<sup>(deprecated)</sup>
restore(wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
isOperationAllowed(callback: AsyncCallback&lt;boolean&gt;): 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.isUserChangeAllowed<sup>9+</sup>](#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&lt;void&gt; | 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&lt;boolean&gt; | 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) => {
```js
wallpaper.isOperationAllowed((error, data) => {
if (error) {
console.error(`failed to restore because: ` + JSON.stringify(error));
console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to restore.`);
});
```
console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`);
});
```
## wallpaper.restore<sup>9+</sup>
## wallpaper.isOperationAllowed<sup>(deprecated)</sup>
restore(wallpaperType: WallpaperType): Promise&lt;void&gt;
isOperationAllowed(): Promise&lt;boolean&gt;
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.isUserChangeAllowed<sup>9+</sup>](#wallpaperisuserchangeallowed9) instead.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes| Wallpaper type.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the result is returned. Otherwise, error information is returned.|
| Promise&lt;boolean&gt; | 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<sup>(deprecated)</sup>
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
reset(wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): 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.setImage<sup>9+</sup>](#wallpapersetimage9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore<sup>9+</sup>](#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&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
| callback | AsyncCallback&lt;void&gt; | 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) => {
```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
if (error) {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
console.error(`failed to reset 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));
});
```
console.log(`success to reset.`);
});
```
## wallpaper.setWallpaper
## wallpaper.reset<sup>(deprecated)</sup>
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise&lt;void&gt;
reset(wallpaperType: WallpaperType): Promise&lt;void&gt;
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.setImage<sup>9+</sup>](#wallpapersetimage9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [wallpaper.restore<sup>9+</sup>](#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&lt;void&gt; | Promise used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
| Promise&lt;void&gt; | 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.setImage<sup>9+</sup>
## wallpaper.setWallpaper<sup>(deprecated)</sup>
setImage(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): void
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback&lt;void&gt;): 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.setImage<sup>9+</sup>](#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&lt;void&gt; | Yes| Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
| callback | AsyncCallback&lt;void&gt; | 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) => {
```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 setImage because: ` + JSON.stringify(error));
console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to setImage.`);
});
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 = {
// 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) => {
};
imageSource.createPixelMap(opts).then((pixelMap) => {
wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
if (error) {
console.error(`failed to setImage because: ` + JSON.stringify(error));
console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to setImage.`);
});
}).catch((error) => {
console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
console.log(`success to setWallpaper.`);
});
```
}).catch((error) => {
console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});
```
## wallpaper.setWallpaper<sup>(deprecated)</sup>
## wallpaper.setImage<sup>9+</sup>
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise&lt;void&gt;
setImage(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise&lt;void&gt;
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.setImage<sup>9+</sup>](#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&lt;void&gt; | Promise used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned.|
| Promise&lt;void&gt; | 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 = {
// 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.`);
};
imageSource.createPixelMap(opts).then((pixelMap) => {
wallpaper.setWallpaper(pixelMap, 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)}`);
});
}).catch((error) => {
console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
});
```
console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});
```
## wallpaper.getFile<sup>8+</sup>
## wallpaper.getFile<sup>(deprecated)</sup>
getFile(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): 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) => {
```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to getFile because: ` + JSON.stringify(error));
console.error(`failed to getFile because: ${JSON.stringify(error)}`);
return;
}
console.log(`success to getFile: ` + JSON.stringify(data));
});
```
console.log(`success to getFile: ${JSON.stringify(data)}`);
});
```
## wallpaper.getFile<sup>8+</sup>
## wallpaper.getFile<sup>(deprecated)</sup>
getFile(wallpaperType: WallpaperType): Promise&lt;number&gt;
......@@ -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.getFileSync<sup>9+</sup>
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<sup>(deprecated)</sup>
getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback&lt;image.PixelMap&gt;): 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<sup>(deprecated)</sup>
getPixelMap(wallpaperType: WallpaperType): Promise&lt;image.PixelMap&gt;
......@@ -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.getImage<sup>9+</sup>
getImage(wallpaperType: WallpaperType, callback: AsyncCallback&lt;image.PixelMap&gt;): 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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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.getImage<sup>9+</sup>
getImage(wallpaperType: WallpaperType): Promise&lt;image.PixelMap&gt;
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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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')<sup>9+</sup>
on(type: 'colorChange', callback: (colors: Array&lt;RgbaColor&gt;, wallpaperType: WallpaperType) =&gt; 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.<br>- colors<br>Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br>Wallpaper type.|
**Example**
```js
let listener = (colors, wallpaperType) => {
console.log(`wallpaper color changed.`);
};
wallpaper.on('colorChange', listener);
```
## wallpaper.off('colorChange')<sup>9+</sup>
off(type: 'colorChange', callback?: (colors: Array&lt;RgbaColor&gt;, wallpaperType: WallpaperType) =&gt; 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.<br>- colors<br>Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br>- wallpaperType<br>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)}`);
});
```
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或