@ohos.wallpaper (Wallpaper)

The wallpaper module is a system service module in OpenHarmony that provides the wallpaper management service. You can use the APIs of this module to show, set, and switch between wallpapers.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import wallpaper from '@ohos.wallpaper';

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.

WallpaperType⁷⁺

Enumerates the wallpaper types.

System capability: SystemCapability.MiscServices.Wallpaper

Name	Value	Description
WALLPAPER_SYSTEM	0	Home screen wallpaper.
WALLPAPER_LOCKSCREEN	1	Lock screen wallpaper.

RgbaColor^(deprecated)

Defines the RGBA color space for the wallpaper.

NOTE

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

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.

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.

Example

import { BusinessError } from '@ohos.base';

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 because: ${JSON.stringify(error)}`);
            return;
        }
        console.log(`success to setVideo.`);
    });
} catch (error) {
    console.error(`failed to setVideo because: ${JSON.stringify(error)}`);
}

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.

Return value

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

Example

import { BusinessError } from '@ohos.base';

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

wallpaper.setCustomWallpaper¹⁰⁺

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

Sets the content from a specified URI as the wallpaper. This API works only when com.ohos.sceneboard is set. 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 the custom 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.

Example

import { BusinessError } from '@ohos.base';

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 because: ${JSON.stringify(error)}`);
            return;
        }
        console.log(`success to setCustomWallpaper.`);
    });
} catch (error) {
    console.error(`failed to setCustomWallpaper because: ${JSON.stringify(error)}`);
}

wallpaper.setCustomWallpaper¹⁰⁺

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

Sets the content from a specified URI as the wallpaper. This API works only when com.ohos.sceneboard is set. 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 the custom wallpaper.
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

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

Example

import { BusinessError } from '@ohos.base';

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

wallpaper.on(‘wallpaperChange’)¹⁰⁺

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

Subscribes to wallpaper change events.

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.

Example

try {
    let listener = (wallpaperType: wallpaper.WallpaperType, resourceType: wallpaper.WallpaperResourceType): void => {
        console.log(`wallpaper color changed.`);
    };
    wallpaper.on('wallpaperChange', listener);
} catch (error) {
    console.error(`failed to on because: ${JSON.stringify(error)}`);
}

wallpaper.off(‘wallpaperChange’)¹⁰⁺

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

Unsubscribes from wallpaper change events.

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.

Example

let listener = (wallpaperType: wallpaper.WallpaperType, resourceType: wallpaper.WallpaperResourceType): void => {
    console.log(`wallpaper color changed.`);
};
try {
    wallpaper.on('wallpaperChange', listener);
} catch (error) {
    console.error(`failed to on because: ${JSON.stringify(error)}`);
}

try {
    // Unsubscribe from the listener.
    wallpaper.off('wallpaperChange', listener);
} catch (error) {
    console.error(`failed to off because: ${JSON.stringify(error)}`);
}

try {
    // Unsubscribe from all callbacks of the 'wallpaperChange' event type.
    wallpaper.off('wallpaperChange');
} catch (error) {
    console.error(`failed to off because: ${JSON.stringify(error)}`);
}

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.

Example

try {
    let colors = wallpaper.getColorsSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
    console.log(`success to getColorsSync: ${JSON.stringify(colors)}`);
} catch (error) {
    console.error(`failed to getColorsSync because: ${JSON.stringify(error)}`);
}

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.

Example

let minHeight = wallpaper.getMinHeightSync();

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.

Example

let minWidth = wallpaper.getMinWidthSync();

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.

Example

import { BusinessError } from '@ohos.base';

wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
    if (error) {
        console.error(`failed to restore because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`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.

Example

import { BusinessError } from '@ohos.base';
 
wallpaper.restore(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
    console.log(`success to restore.`);
  }).catch((error: BusinessError) => {
    console.error(`failed to restore because: ${JSON.stringify(error)}`);
});

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.

Example

import { BusinessError } from '@ohos.base';
import image from '@ohos.multimedia.image';

// 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 because: ${JSON.stringify(error)}`);
        return;
     }
    console.log(`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 because: ${JSON.stringify(error)}`);
            return;
        }
        console.log(`success to setImage.`);
    });
}).catch((error: BusinessError) => {
    console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});

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.

Example

import { BusinessError } from '@ohos.base';
import image from '@ohos.multimedia.image';

// 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.log(`success to setImage.`);
}).catch((error: BusinessError) => {
    console.error(`failed to setImage because: ${JSON.stringify(error)}`);
});

// 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.log(`success to setImage.`);
    }).catch((error: BusinessError) => {
        console.error(`failed to setImage because: ${JSON.stringify(error)}`);
    });
}).catch((error: BusinessError) => {
    console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});

wallpaper.getImage⁹⁺

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

Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

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 '@ohos.base';

wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: image.PixelMap) => {
    if (error) {
        console.error(`failed to getImage because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getImage: ${JSON.stringify(data)}`);
});

wallpaper.getImage⁹⁺

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

Obtains the pixel map for the wallpaper of the specified type. 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.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getImage(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: image.PixelMap) => {
    console.log(`success to getImage: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to getImage because: ${JSON.stringify(error)}`);
});

wallpaper.on(‘colorChange’)^(deprecated)

on(type: ‘colorChange’, callback: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void

Subscribes to the wallpaper color change event.

NOTE

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

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the event to subscribe to. The value ‘colorChange’ indicates subscribing to the wallpaper color change event.
callback	function	Yes	Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned. - colors Main color information of the wallpaper. For details, see RgbaColor. - wallpaperType Wallpaper type.

Example

try {
    let listener = (colors: Array<wallpaper.RgbaColor>, wallpaperType: wallpaper.WallpaperType): void => {
        console.log(`wallpaper color changed.`);
    };
    wallpaper.on('colorChange', listener);
} catch (error) {
    console.error(`failed to on because: ${JSON.stringify(error)}`);
}

wallpaper.off(‘colorChange’)^(deprecated)

off(type: ‘colorChange’, callback?: (colors: Array<RgbaColor>, wallpaperType: WallpaperType) => void): void

Unsubscribes from the wallpaper color change event.

NOTE

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

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 used for unsubscription. If this parameter is not set, this API unsubscribes from all callbacks of the specified event type. - colors Main color information of the wallpaper. For details, see RgbaColor. - wallpaperType Wallpaper type.

Example

let listener = (colors: Array<wallpaper.RgbaColor>, wallpaperType: wallpaper.WallpaperType): void => {
    console.log(`wallpaper color changed.`);
};
try {
    wallpaper.on('colorChange', listener);
} catch (error) {
    console.error(`failed to on because: ${JSON.stringify(error)}`);
}

try {
    // Unsubscribe from the listener.
    wallpaper.off('colorChange', listener);
} catch (error) {
    console.error(`failed to off because: ${JSON.stringify(error)}`);
}

try {
    // Unsubscribe from all subscriptions of the colorChange type.
    wallpaper.off('colorChange');
} catch (error) {
    console.error(`failed to off because: ${JSON.stringify(error)}`);
}

wallpaper.getColors^(deprecated)

getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): 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.

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<Array<RgbaColor>>	Yes	Callback used to return the main color information of the wallpaper.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: Array<wallpaper.RgbaColor>) => {
    if (error) {
        console.error(`failed to getColors because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getColors: ${JSON.stringify(data)}`);
});

wallpaper.getColors^(deprecated)

getColors(wallpaperType: WallpaperType): Promise<Array<RgbaColor>>

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.

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

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

Example

import { BusinessError } from '@ohos.base';

wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: Array<wallpaper.RgbaColor>) => {
    console.log(`success to getColors: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to getColors because: ${JSON.stringify(error)}`);
});

wallpaper.getId^(deprecated)

getId(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void

Obtains the ID of the wallpaper of the specified type. This API uses an asynchronous callback to return the result.

NOTE

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

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<number>	Yes	Callback used to return the wallpaper ID. If the wallpaper of the specified type is configured, a number greater than or equal to 0 is returned. Otherwise, -1 is returned. The value ranges from -1 to (2^31-1).

Example

import { BusinessError } from '@ohos.base';

wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: Number) => {
    if (error) {
        console.error(`failed to getId because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getId: ${JSON.stringify(data)}`);
});

wallpaper.getId^(deprecated)

getId(wallpaperType: WallpaperType): Promise<number>

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.

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Promise<number>	Promise used to return the wallpaper ID. If this type of wallpaper is configured, a number greater than or equal to 0 is returned. Otherwise, -1 is returned. The value ranges from -1 to (2^31-1).

Example

import { BusinessError } from '@ohos.base';

wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: Number) => {
    console.log(`success to getId: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to getId because: ${JSON.stringify(error)}`);
});

wallpaper.getMinHeight^(deprecated)

getMinHeight(callback: AsyncCallback<number>): void

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.

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<number>	Yes	Callback used to return the minimum wallpaper height, in pixels. If the return value is 0, no wallpaper is set. In this case, the default height should be used instead.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getMinHeight((error: BusinessError, data: Number) => {
    if (error) {
        console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getMinHeight: ${JSON.stringify(data)}`);
});

wallpaper.getMinHeight^(deprecated)

getMinHeight(): Promise<number>

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.

System capability: SystemCapability.MiscServices.Wallpaper

Return value

Type	Description
Promise<number>	Promise used to return the minimum wallpaper height, in pixels. If the return value is 0, no wallpaper is set. In this case, the default height should be used instead.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getMinHeight().then((data: Number) => {
    console.log(`success to getMinHeight: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
    console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`);
});

wallpaper.getMinWidth^(deprecated)

getMinWidth(callback: AsyncCallback<number>): void

Obtains the minimum width of this wallpaper. This API uses an asynchronous callback to return the result.

NOTE

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

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<number>	Yes	Callback used to return the minimum wallpaper width, in pixels. If the return value is 0, no wallpaper is set. In this case, the default width should be used instead.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getMinWidth((error: BusinessError, data: Number) => {
    if (error) {
        console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getMinWidth: ${JSON.stringify(data)}`);
});

wallpaper.getMinWidth^(deprecated)

getMinWidth(): Promise<number>

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.

System capability: SystemCapability.MiscServices.Wallpaper

Return value

Type	Description
Promise<number>	Promise used to return the minimum wallpaper width, in pixels. If the return value is 0, no wallpaper is set. In this case, the default width should be used instead.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getMinWidth().then((data: Number) => {
    console.log(`success to getMinWidth: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`);
});

wallpaper.isChangePermitted^(deprecated)

isChangePermitted(callback: AsyncCallback<boolean>): void

Checks whether to allow the application to change the wallpaper for the current user. This API uses an asynchronous callback to return the result.

NOTE

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

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return whether to allow the application to change the wallpaper for the current user. The value true means that the operation is allowed, and false means the opposite.

Example

import { BusinessError } from '@ohos.base';

wallpaper.isChangePermitted((error: BusinessError, data: Boolean) => {
    if (error) {
        console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to isChangePermitted: ${JSON.stringify(data)}`);
});

wallpaper.isChangePermitted^(deprecated)

isChangePermitted(): Promise<boolean>

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.

System capability: SystemCapability.MiscServices.Wallpaper

Return value

Type	Description
Promise<boolean>	Promise used to return whether to allow the application to change the wallpaper for the current user. The value true means that the operation is allowed, and false means the opposite.

Example

import { BusinessError } from '@ohos.base';

wallpaper.isChangePermitted().then((data: Boolean) => {
    console.log(`success to isChangePermitted: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
    console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`);
});

wallpaper.isOperationAllowed^(deprecated)

isOperationAllowed(callback: AsyncCallback<boolean>): void

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.

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return whether the user is allowed to set wallpapers. The value true means that the operation is allowed, and false means the opposite.

Example

import { BusinessError } from '@ohos.base';

wallpaper.isOperationAllowed((error: BusinessError, data: Boolean) => {
    if (error) {
        console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`);
});

wallpaper.isOperationAllowed^(deprecated)

isOperationAllowed(): Promise<boolean>

Checks whether the user is allowed to set wallpapers. This API uses a promise to return the result.

NOTE

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

System capability: SystemCapability.MiscServices.Wallpaper

Return value

Type	Description
Promise<boolean>	Promise used to return whether the user is allowed to set wallpapers. The value true means that the operation is allowed, and false means the opposite.

Example

import { BusinessError } from '@ohos.base';

wallpaper.isOperationAllowed().then((data: Boolean) => {
    console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`);
});

wallpaper.reset^(deprecated)

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

NOTE

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

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

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.

Example

import { BusinessError } from '@ohos.base';

wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
    if (error) {
        console.error(`failed to reset because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to reset.`);
});

wallpaper.reset^(deprecated)

reset(wallpaperType: WallpaperType): Promise<void>

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.

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

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

Example

import { BusinessError } from '@ohos.base';

wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
    console.log(`success to reset.`);
}).catch((error: BusinessError) => {
    console.error(`failed to reset because: ${JSON.stringify(error)}`);
});

wallpaper.setWallpaper^(deprecated)

setWallpaper(source: string|image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback<void>): void

Sets a specified source as the wallpaper of a specified type. This API uses an asynchronous callback to return the result.

NOTE

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

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

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.

Example

import { BusinessError } from '@ohos.base';
import image from '@ohos.multimedia.image';

// The source type is string.
let wallpaperPath = "/data/storage/el2/base/haps/entry/files/js.jpeg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
    if (error) {
        console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
       return;
       }
    console.log(`success to setWallpaper.`);
});

// 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.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError) => {
        if (error) {
            console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
            return;
        }
        console.log(`success to setWallpaper.`);
    });
}).catch((error: BusinessError) => {
    console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});

wallpaper.setWallpaper^(deprecated)

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

NOTE

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

Required permissions: ohos.permission.SET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

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.

Example

import { BusinessError } from '@ohos.base';
import image from '@ohos.multimedia.image';

// The source type is string.
let wallpaperPath = "/data/storage/el2/base/haps/entry/files/js.jpeg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
    console.log(`success to setWallpaper.`);
  }).catch((error: BusinessError) => {
    console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
});
  
// 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.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
        console.log(`success to setWallpaper.`);
    }).catch((error: BusinessError) => {
        console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
    });
  }).catch((error: BusinessError) => {
    console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
});

wallpaper.getFile^(deprecated)

getFile(wallpaperType: WallpaperType, callback: AsyncCallback<number>): void

Obtains the wallpaper of the specified type. This API uses an asynchronous callback to return the result.

NOTE

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

Required permissions: ohos.permission.GET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.
callback	AsyncCallback<number>	Yes	Callback used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: number) => {
    if (error) {
        console.error(`failed to getFile because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getFile: ${JSON.stringify(data)}`);
});

wallpaper.getFile^(deprecated)

getFile(wallpaperType: WallpaperType): Promise<number>

Obtains the wallpaper of the specified type. This API uses a promise to return the result.

NOTE

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

Required permissions: ohos.permission.GET_WALLPAPER

System capability: SystemCapability.MiscServices.Wallpaper

Parameters

Name	Type	Mandatory	Description
wallpaperType	WallpaperType	Yes	Wallpaper type.

Return value

Type	Description
Promise<number>	Promise used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned.

Example

import { BusinessError } from '@ohos.base';

wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: number) => {
    console.log(`success to getFile: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to getFile because: ${JSON.stringify(error)}`);
});

wallpaper.getPixelMap^(deprecated)

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

Obtains the pixel map for the wallpaper of the specified type. This API uses an asynchronous callback to return the result.

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 '@ohos.base';

wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error: BusinessError, data: image.PixelMap) => {
    if (error) {
        console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`);
        return;
    }
    console.log(`success to getPixelMap : ${JSON.stringify(data)}`);
  });

wallpaper.getPixelMap^(deprecated)

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

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.

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 '@ohos.base';

wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data: image.PixelMap) => {
    console.log(`success to getPixelMap : ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`failed to getPixelMap because: ${JSON.stringify(error)}`);
});

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)