@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, need to 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.

FoldState¹⁴⁺

Enumerates the types of the folding state of a device.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

RotateState¹⁴⁺

Enumerates the landscape or portrait mode of a device.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

WallpaperInfo¹⁴⁺

Defines the wallpaper information structure.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

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

Error codes

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

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 because: ${JSON.stringify(error)}`);
            return;
        }
        console.info(`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

Error codes

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

Return 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 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 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

Error codes

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

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

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

Return value

Error codes

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

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 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. Multi-thread concurrent calls are not supported.

System capability: SystemCapability.MiscServices.Wallpaper

System API: This is a system API.

Parameters

Error codes

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

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 because: ${JSON.stringify(error)}`);
}

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

Error codes

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

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 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

Return value

Error codes

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

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 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

Error codes

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

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

Error codes

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

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

Error codes

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

Example

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

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

Return value

Error codes

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

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 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

Error codes

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

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 because: ${JSON.stringify(error)}`);
        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 because: ${JSON.stringify(error)}`);
            return;
        }
        console.info(`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

Return value

Error codes

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

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 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.info(`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 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

Error codes

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

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 because: ${JSON.stringify(error)}`);
        return;
    }
    console.info(`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 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

Return value

Error codes

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

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

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

Return value

Error codes

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

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

wallpaper.setAllWallpapers¹⁴⁺

setAllWallpapers(wallpaperInfos: Array<WallpaperInfo>\, wallpaperType: WallpaperType): Promise&lt;void&gt;

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

Return value

Error codes

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

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 because: ${JSON.stringify(error)}`);
});

wallpaper.getPixelMap^(deprecated)

getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback&lt;image.PixelMap&gt;): 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

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 because: ${JSON.stringify(error)}`);
        return;
    }
    console.info(`success to getPixelMap : ${JSON.stringify(data)}`);
  });

wallpaper.getPixelMap^(deprecated)

getPixelMap(wallpaperType: WallpaperType): Promise&lt;image.PixelMap&gt;

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

Return value

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Basic Services Kit

harmony 鸿蒙DeviceInfo

harmony 鸿蒙InitSync

harmony 鸿蒙OH_Print

harmony 鸿蒙OsAccount

harmony 鸿蒙Pasteboard

harmony 鸿蒙Print_Margin

harmony 鸿蒙Print_PageSize

harmony 鸿蒙Print_PrintAttributes

harmony 鸿蒙Print_PrintDocCallback