@ohos.wallpaper (Wallpaper) (System API)

The wallpaper module provides APIs for switching between wallpapers. Since API version 9, the APIs of this module function as system APIs, and only system applications are allowed to switch between wallpapers. Applications that use the wallpaper, for example, the home screen, should subscribe to wallpaper changes and update the wallpaper accordingly.

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. This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.wallpaper (Wallpaper).

Modules to Import

import { wallpaper } from '@kit.BasicServicesKit';

WallpaperResourceType¹⁰⁺

Enumerates the types of wallpaper resources.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Name	Value	Description
DEFAULT	0	Default type (image resource).
PICTURE	1	Image resource.
VIDEO	2	Video resource.
PACKAGE	3	Package resource.

FoldState¹⁴⁺

Enumerates the types of the folding state of a device.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Name	Value	Description
NORMAL	0	Default state.
UNFOLD_ONCE_STATE	1	Initial unfolded state.
UNFOLD_TWICE_STATE	2	Secondary unfolded state.

RotateState¹⁴⁺

Enumerates the landscape or portrait mode of a device.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Name	Value	Description
PORTRAIT	0	Portrait mode (default).
LANDSCAPE	1	Landscape mode.

WallpaperInfo¹⁴⁺

Defines the wallpaper information structure.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Name	Type	Read-Only	Optional	Description
foldState	FoldState	No	No	Folding state of a device.
rotateState	RotateState	No	No	Landscape/portrait mode of a device.
source	string	No	No	Wallpaper resource URI. Only the application sandbox directory is supported.

wallpaper.setVideo¹⁰⁺

setVideo(source: string, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void

Sets a video resource as the home screen wallpaper or lock screen wallpaper. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
source	string	Yes	URI of an MP4 file.
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the wallpaper is set, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.mp4";
try {
    wallpaper.setVideo(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
        if (error) {
            console.error(`failed to setVideo. Code: ${error.code}, Message: ${error.message}`);
            return;
        }
        console.info(`success to setVideo.`);
    });
} catch (error) {
    console.error(`failed to setVideo. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.setVideo¹⁰⁺

setVideo(source: string, wallpaperType: WallpaperType): Promise<void>

Sets a video resource as the home screen wallpaper or lock screen wallpaper. This API uses a promise to return the result.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
source	string	Yes	URI of an MP4 file.
wallpaperType	WallpaperType	Yes	Wallpaper type.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.mp4";
try {
    wallpaper.setVideo(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
        console.info(`success to setVideo.`);
    }).catch((error: BusinessError) => {
        console.error(`failed to setVideo. Code: ${error.code}, Message: ${error.message}`);
    });
} catch (error) {
    console.error(`failed to setVideo. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.setCustomWallpaper¹⁰⁺

setCustomWallpaper(source: string, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void

Sets a specific ZIP file as the wallpaper. This API works only when com.ohos.sceneboard is set. Applications with the ohos.permission.GET_WALLPAPER permission have access to the /data/wallpaper/ directory. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
source	string	Yes	ZIP file to set as the wallpaper.
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the wallpaper is set, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.zip";
try {
    wallpaper.setCustomWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
        if (error) {
            console.error(`failed to setCustomWallpaper. Code: ${error.code}, Message: ${error.message}`);
            return;
        }
        console.info(`success to setCustomWallpaper.`);
    });
} catch (error) {
    console.error(`failed to setCustomWallpaper. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.setCustomWallpaper¹⁰⁺

setCustomWallpaper(source: string, wallpaperType: WallpaperType): Promise<void>

Sets a specific ZIP file as the wallpaper. This API works only when com.ohos.sceneboard is set. Applications with the ohos.permission.GET_WALLPAPER permission have access to the /data/wallpaper/ directory. This API uses a promise to return the result.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
source	string	Yes	ZIP file to set as the wallpaper.
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let wallpaperPath = "/data/storage/el2/base/haps/entry/files/test.zip";
try {
    wallpaper.setCustomWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
        console.info(`success to setCustomWallpaper.`);
    }).catch((error: BusinessError) => {
        console.error(`failed to setCustomWallpaper. Code: ${error.code}, Message: ${error.message}`);
    });
} catch (error) {
    console.error(`failed to setCustomWallpaper. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.on('wallpaperChange')¹⁰⁺

on(type: 'wallpaperChange', callback: (wallpaperType: WallpaperType, resourceType: WallpaperResourceType, uri?: string) => void): void

Subscribes to wallpaper change events. Multi-thread concurrent calls are not supported.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'wallpaperChange'.
callback	function	Yes	Callback used to return the wallpaper type and wallpaper resource type. - wallpaperType: wallpaper type. - resourceType: wallpaper resource type. - uri: URI of the wallpaper resource.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

try {
    let listener = (wallpaperType: wallpaper.WallpaperType, resourceType: wallpaper.WallpaperResourceType): void => {
        console.info(`wallpaper color changed.`);
    };
    wallpaper.on('wallpaperChange', listener);
} catch (error) {
    console.error(`failed to on. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.off('wallpaperChange')¹⁰⁺

off(type: 'wallpaperChange', callback?: (wallpaperType: WallpaperType, resourceType: WallpaperResourceType, uri?: string) => void): void

Unsubscribes from wallpaper change events. Multi-thread concurrent calls are not supported.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'wallpaperChange'.
callback	function	No	Callback used for unsubscription. If this parameter is not set, this API unsubscribes from all callbacks of the specified event type. - wallpaperType: wallpaper type. - resourceType: wallpaper resource type. - uri: URI of the wallpaper resource.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

let listener = (wallpaperType: wallpaper.WallpaperType, resourceType: wallpaper.WallpaperResourceType): void => {
    console.info(`wallpaper color changed.`);
};
try {
    wallpaper.on('wallpaperChange', listener);
} catch (error) {
    console.error(`failed to on. Code: ${error.code}, Message: ${error.message}`);
}

try {
    // Unsubscribe from the listener.
    wallpaper.off('wallpaperChange', listener);
} catch (error) {
    console.error(`failed to off. Code: ${error.code}, Message: ${error.message}`);
}

try {
    // Unsubscribe from all callbacks of the 'wallpaperChange' event type.
    wallpaper.off('wallpaperChange');
} catch (error) {
    console.error(`failed to off. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.getColorsSync⁹⁺

getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>

Obtains the main color information of the wallpaper of the specified type.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Array<RgbaColor>	Promise used to return the main color information of the wallpaper.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

try {
    let colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
    console.info(`success to getColorsSync: ${JSON.stringify(colors)}`);
} catch (error) {
    console.error(`failed to getColorsSync. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.getMinHeightSync⁹⁺

getMinHeightSync(): number

Obtains the minimum height of this wallpaper.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	permission verification failed, application which is not a system application uses system API.

Example

try {
  let minHeight = wallpaper.getMinHeightSync();
  console.info(`success to getMinHeightSync: ${JSON.stringify(minHeight)}`);
} catch (error) {
  console.error(`failed to getMinHeightSync. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.getMinWidthSync⁹⁺

getMinWidthSync(): number

Obtains the minimum width of this wallpaper.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	permission verification failed, application which is not a system application uses system API.

Example

try {
  let minWidth = wallpaper.getMinWidthSync();
  console.info(`success to getMinWidthSync: ${JSON.stringify(minWidth)}`);
} catch (error) {
  console.error(`failed to getMinWidthSync. Code: ${error.code}, Message: ${error.message}`);
}

wallpaper.restore⁹⁺

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

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the wallpaper is reset, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
    if (error) {
        console.error(`failed to restore. Code: ${error.code}, Message: ${error.message}`);
        return;
    }
    console.info(`success to restore.`);
});

wallpaper.restore⁹⁺

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

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
 
wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
    console.info(`success to restore.`);
  }).catch((error: BusinessError) => {
    console.error(`failed to restore. Code: ${error.code}, Message: ${error.message}`);
});

wallpaper.setImage⁹⁺

setImage(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.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
source	string | image.PixelMap	Yes	URI of a JPEG or PNG file, or pixel map of a PNG file.
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the wallpaper is set, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

// The source type is string.
let wallpaperPath = "/data/storage/el2/base/haps/entry/files/js.jpeg";
wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
    if (error) {
        console.error(`failed to setImage. Code: ${error.code}, Message: ${error.message}`);
        return;
     }
    console.info(`success to setImage.`);
});
  
// The source type is image.PixelMap.
let imageSource = image.createImageSource("file://" + wallpaperPath);
let opts: image.DecodingOptions = {
    desiredSize: {
        height: 3648,
        width: 2736
    }
};
imageSource.createPixelMap(opts).then((pixelMap: image.PixelMap) => {
    wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
        if (error) {
            console.error(`failed to setImage. Code: ${error.code}, Message: ${error.message}`);
            return;
        }
        console.info(`success to setImage.`);
    });
}).catch((error: BusinessError) => {
    console.error(`failed to createPixelMap. Code: ${error.code}, Message: ${error.message}`);
});

wallpaper.setImage⁹⁺

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.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
source	string | image.PixelMap	Yes	URI of a JPEG or PNG file, or pixel map of a PNG file.
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

// The source type is string.
let wallpaperPath = "/data/storage/el2/base/haps/entry/files/js.jpeg";
wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
    console.info(`success to setImage.`);
}).catch((error: BusinessError) => {
    console.error(`failed to setImage. Code: ${error.code}, Message: ${error.message}`);
});

// The source type is image.PixelMap.
let imageSource = image.createImageSource("file://" + wallpaperPath);
let opts: image.DecodingOptions = {
    desiredSize: {
        height: 3648,
        width: 2736
    }
};
imageSource.createPixelMap(opts).then((pixelMap: image.PixelMap) => {
    wallpaper.setImage(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
        console.info(`success to setImage.`);
    }).catch((error: BusinessError) => {
        console.error(`failed to setImage. Code: ${error.code}, Message: ${error.message}`);
    });
}).catch((error: BusinessError) => {
    console.error(`failed to createPixelMap. Code: ${error.code}, Message: ${error.message}`);
});

wallpaper.getImage⁹⁺

getImage(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void

Obtains the pixel map for the wallpaper of the specified type. This API only works for the static wallpaper set using setImage. 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.

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<image.PixelMap>	Yes	Callback used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: image.PixelMap) => {
  if (error) {
    console.error(`failed to getImage. Code: ${error.code}, Message: ${error.message}`);
    return;
  }
  console.info(`success to getImage: ${JSON.stringify(data.getImageInfoSync())}`);
});

wallpaper.getImage⁹⁺

getImage(wallpaperType: WallpaperType): Promise<image.PixelMap>

Obtains the pixel map for the wallpaper of the specified type. This API only works for the static wallpaper set using setImage. This API uses a promise to return the result.

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	Yes	Wallpaper type.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: image.PixelMap) => {
  console.info(`success to getImage: ${JSON.stringify(data.getImageInfoSync())}`);
}).catch((error: BusinessError) => {
  console.error(`failed to getImage. Code: ${error.code}, Message: ${error.message}`);
});

wallpaper.getWallpaperByState¹⁴⁺

getWallpaperByState(wallpaperType:WallpaperType, foldState:FoldState, rotateState:RotateState): Promise<image.PixelMap>

Obtains the pixel map of the wallpaper of a specific type, folding state, or landscape/portrait mode. If the specified wallpaper does not exist, the matching follows a degrading order: unfolded-land > unfolded-port > normal-port. This API uses a promise to return the result.

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	Yes	Wallpaper type.
foldState	FoldState	Yes	Folding state type.
rotateState	RotateState	Yes	Landscape/portrait mode.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.The type must be WallpaperType, parameter range must be WALLPAPER_LOCKSCREEN or WALLPAPER_SYSTEM; 3.The type must be FoldState, parameter range must be NORMAL or UNFOLD_ONCE_STATE or UNFOLD_TWICE_STATE;4.The type must be RotateState, parameter range must be PORTRAIT or LANDSCAPE.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { wallpaper } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

wallpaper.getWallpaperByState(wallpaper.WallpaperType.WALLPAPER_SYSTEM,wallpaper.FoldState.NORMAL,wallpaper.RotateState.PORTRAIT).then((data:image.PixelMap) => {
  console.info(`success to getWallpaperByState: ${JSON.stringify(data.getImageInfoSync())}`);
}).catch((error: BusinessError) => {
  console.error(`failed to getWallpaperByState. Code: ${error.code}, Message: ${error.message}`);
});

wallpaper.setAllWallpapers¹⁴⁺

setAllWallpapers(wallpaperInfos: Array<WallpaperInfo>, wallpaperType: WallpaperType): Promise<void>

Sets all wallpaper to a specific folding state, landscape/portrait mode, and resource path, where wallpaper.FoldState.NORMAL and wallpaper.RotateState.PORTRAIT are mandatory. This API uses a promise to return the result.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
wallpaperInfos	Array<WallpaperInfo>	Yes	Information structure of all wallpapers.
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	permission denied.
202	permission verification failed, application which is not a system application uses system API.
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.The first parameter type must be Array<WallpaperInfo>. The second type must be WallpaperType; 3.The first parameter type must be Array<WallpaperInfo>, must include wallpaper with FoldState NORMAL and RotateState PORTRAIT.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { wallpaper } from '@kit.BasicServicesKit';

let wallpaperInfos: Array<wallpaper.WallpaperInfo>
wallpaperInfos = [
  {
    foldState: wallpaper.FoldState.NORMAL,
    rotateState: wallpaper.RotateState.PORTRAIT,
    source: '/data/storage/el2/base/haps/entry/files/normal.jpeg'
  },
  {
    foldState: wallpaper.FoldState.UNFOLD_ONCE_STATE,
    rotateState: wallpaper.RotateState.LANDSCAPE,
    source: '/data/storage/el2/base/haps/entry/files/unfold_once_state.jpeg'
  },
  {
    foldState: wallpaper.FoldState.UNFOLD_TWICE_STATE,
    rotateState: wallpaper.RotateState.PORTRAIT,
    source: '/data/storage/el2/base/haps/entry/files/unfold_twice_state.jpeg'
  }
];
wallpaper.setAllWallpapers(wallpaperInfos, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
  console.info(`success to setAllWallpapers.`);
}).catch((error: BusinessError) => {
  console.error(`failed to setAllWallpapers. Code: ${error.code}, Message: ${error.message}`);
});

wallpaper.getPixelMap^(deprecated)

getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void

Obtains the pixel map for the wallpaper of the specified type.

NOTE

This API is supported since API version 7 and deprecated since API version 9.

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	Yes	Wallpaper type.
callback	AsyncCallback<image.PixelMap>	Yes	Callback used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: image.PixelMap) => {
  if (error) {
    console.error(`failed to getPixelMap. Code: ${error.code}, Message: ${error.message}`);
    return;
  }
  console.info(`success to getPixelMap : ${JSON.stringify(data.getImageInfoSync())}`);
});

wallpaper.getPixelMap^(deprecated)

getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap>

Obtains the pixel map for the wallpaper of the specified type.

NOTE

This API is supported since API version 7 and deprecated since API version 9.

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	Yes	Wallpaper type.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the result. If the operation is successful, the pixel map of the wallpaper is returned. Otherwise, error information is returned.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: image.PixelMap) => {
  console.info(`success to getPixelMap : ${JSON.stringify(data.getImageInfoSync())}`);
}).catch((error: BusinessError) => {
  console.error(`failed to getPixelMap. Code: ${error.code}, Message: ${error.message}`);
});