壁纸

2024-01-23 17:27 更新

壁纸管理服务是系统服务,主要为系统提供壁纸管理服务能力,支持系统显示、设置、切换壁纸等功能。

说明

本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

  1. import wallpaper from '@ohos.wallpaper';

WallpaperType7+

定义壁纸的枚举类型。

系统能力: SystemCapability.MiscServices.Wallpaper

名称

说明

WALLPAPER_SYSTEM

0

主屏幕壁纸标识。

WALLPAPER_LOCKSCREEN

1

锁屏壁纸标识。

RgbaColor(deprecated)

定义壁纸颜色信息结构。

系统能力: SystemCapability.MiscServices.Wallpaper

名称

类型

可读

可写

说明

red

number

表示红色值,范围为 0 到 255。

green

number

表示绿色值,范围为 0 到 255。

blue

number

表示蓝色值,范围为 0 到 255。

alpha

number

表示 alpha 值,范围为 0 到 255。

wallpaper.on('colorChange')(deprecated)

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

订阅壁纸颜色变化结果上报事件。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

type

string

取值为'colorChange',表示壁纸颜色变化结果上报事件。

callback

function

壁纸颜色变化触发该回调方法,返回壁纸类型和壁纸的主要颜色信息。

- colors

壁纸的主要颜色信息,其类型见RgbaColor

- wallpaperType

壁纸类型。

示例:

  1. try {
  2. let listener = (colors, wallpaperType) => {
  3. console.log(`wallpaper color changed.`);
  4. };
  5. wallpaper.on('colorChange', listener);
  6. } catch (error) {
  7. console.error(`failed to on because: ${JSON.stringify(error)}`);
  8. }

wallpaper.off('colorChange')(deprecated)

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

取消订阅壁纸颜色变化结果上报事件。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

type

string

取值为'colorChange',表示取消订阅壁纸颜色变化结果上报事件。

callback

function

表示要取消的壁纸颜色变化的回调,不填写该参数则取消订阅该type对应的所有回调。

- colors

壁纸的主要颜色信息,其类型见RgbaColor

- wallpaperType

壁纸类型。

示例:

  1. let listener = (colors, wallpaperType) => {
  2. console.log(`wallpaper color changed.`);
  3. };
  4. try {
  5. wallpaper.on('colorChange', listener);
  6. } catch (error) {
  7. console.error(`failed to on because: ${JSON.stringify(error)}`);
  8. }
  9. try {
  10. // 取消订阅listener
  11. wallpaper.off('colorChange', listener);
  12. } catch (error) {
  13. console.error(`failed to off because: ${JSON.stringify(error)}`);
  14. }
  15. try {
  16. // 取消所有'colorChange'类型的订阅
  17. wallpaper.off('colorChange');
  18. } catch (error) {
  19. console.error(`failed to off because: ${JSON.stringify(error)}`);
  20. }

wallpaper.getColors(deprecated)

getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array<RgbaColor>>): void

获取指定类型壁纸的主要颜色信息。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

callback

AsyncCallback<Array<RgbaColor>>

回调函数,返回壁纸的主要颜色信息。

示例:

  1. wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
  2. if (error) {
  3. console.error(`failed to getColors because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to getColors: ${JSON.stringify(data)}`);
  7. });

wallpaper.getColors(deprecated)

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

获取指定类型壁纸的主要颜色信息。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

返回值:

类型

说明

Promise<Array<RgbaColor>>

返回壁纸的主要颜色信息。

示例:

  1. wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
  2. console.log(`success to getColors: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to getColors because: ${JSON.stringify(error)}`);
  5. });

wallpaper.getId(deprecated)

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

获取指定类型壁纸的ID。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

callback

AsyncCallback<number>

回调函数,返回壁纸的ID。如果配置了指定类型的壁纸就返回一个大于等于0的数,否则返回-1。取值范围是-1到(2^31-1)。

示例:

  1. wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
  2. if (error) {
  3. console.error(`failed to getId because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to getId: ${JSON.stringify(data)}`);
  7. });

wallpaper.getId(deprecated)

getId(wallpaperType: WallpaperType): Promise<number>

获取指定类型壁纸的ID。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

返回值:

类型

说明

Promise<number>

壁纸的ID。如果配置了这种壁纸类型的壁纸就返回一个大于等于0的数,否则返回-1。取值范围是-1到(2^31-1)。

示例:

  1. wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
  2. console.log(`success to getId: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to getId because: ${JSON.stringify(error)}`);
  5. });

wallpaper.getMinHeight(deprecated)

getMinHeight(callback: AsyncCallback<number>): void

获取壁纸的最小高度值。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

callback

AsyncCallback<number>

回调函数,返回壁纸的最小高度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的高度值代替。

示例:

  1. wallpaper.getMinHeight((error, data) => {
  2. if (error) {
  3. console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to getMinHeight: ${JSON.stringify(data)}`);
  7. });

wallpaper.getMinHeight(deprecated)

getMinHeight(): Promise<number>

获取壁纸的最小高度值。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型

说明

Promise<number>

返回壁纸的最小高度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的高度值代替。

示例:

  1. wallpaper.getMinHeight().then((data) => {
  2. console.log(`success to getMinHeight: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to getMinHeight because: ${JSON.stringify(error)}`);
  5. });

wallpaper.getMinWidth(deprecated)

getMinWidth(callback: AsyncCallback<number>): void

获取壁纸的最小宽度值。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

callback

AsyncCallback<number>

回调函数,壁纸的最小宽度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的宽度值代替。

示例:

  1. wallpaper.getMinWidth((error, data) => {
  2. if (error) {
  3. console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to getMinWidth: ${JSON.stringify(data)}`);
  7. });

wallpaper.getMinWidth(deprecated)

getMinWidth(): Promise<number>

获取壁纸的最小宽度值。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型

说明

Promise<number>

壁纸的最小宽度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的宽度值代替。

示例:

  1. wallpaper.getMinWidth().then((data) => {
  2. console.log(`success to getMinWidth: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to getMinWidth because: ${JSON.stringify(error)}`);
  5. });

wallpaper.isChangePermitted(deprecated)

isChangePermitted(callback: AsyncCallback<boolean>): void

是否允许应用改变当前用户的壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

回调函数,返回是否允许应用改变当前用户的壁纸。如果允许返回true,否则返回false。

示例:

  1. wallpaper.isChangePermitted((error, data) => {
  2. if (error) {
  3. console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to isChangePermitted: ${JSON.stringify(data)}`);
  7. });

wallpaper.isChangePermitted(deprecated)

isChangePermitted(): Promise<boolean>

是否允许应用改变当前用户的壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型

说明

Promise<boolean>

返回是否允许应用改变当前用户的壁纸。如果允许返回true,否则返回false。

示例:

  1. wallpaper.isChangePermitted().then((data) => {
  2. console.log(`success to isChangePermitted: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to isChangePermitted because: ${JSON.stringify(error)}`);
  5. });

wallpaper.isOperationAllowed(deprecated)

isOperationAllowed(callback: AsyncCallback<boolean>): void

是否允许用户设置壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

回调函数,返回是否允许用户设置壁纸。如果允许返回true,否则返回false。

示例:

  1. wallpaper.isOperationAllowed((error, data) => {
  2. if (error) {
  3. console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`);
  7. });

wallpaper.isOperationAllowed(deprecated)

isOperationAllowed(): Promise<boolean>

是否允许用户设置壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型

说明

Promise<boolean>

异步回调函数,返回是否允许用户设置壁纸。如果允许返回true,否则返回false。

示例:

  1. wallpaper.isOperationAllowed().then((data) => {
  2. console.log(`success to isOperationAllowed: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to isOperationAllowed because: ${JSON.stringify(error)}`);
  5. });

wallpaper.reset(deprecated)

reset(wallpaperType: WallpaperType, callback: AsyncCallback<void>): void

移除指定类型的壁纸,恢复为默认显示的壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

callback

AsyncCallback<void>

回调函数,移除壁纸成功,error为undefined,否则返回error信息。

示例:

  1. wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
  2. if (error) {
  3. console.error(`failed to reset because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to reset.`);
  7. });

wallpaper.reset(deprecated)

reset(wallpaperType: WallpaperType): Promise<void>

移除指定类型的壁纸,恢复为默认显示的壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

示例:

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

wallpaper.setWallpaper(deprecated)

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

将指定资源设置为指定类型的壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

source

string | image.PixelMap

JPEG或PNG文件的Uri路径,或者PNG格式文件的位图。

wallpaperType

WallpaperType

壁纸类型。

callback

AsyncCallback<void>

回调函数,设置壁纸成功,error为undefined,否则返回error信息。

示例:

  1. // source类型为string
  2. let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
  3. wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
  4. if (error) {
  5. console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
  6. return;
  7. }
  8. console.log(`success to setWallpaper.`);
  9. });
  10. // source类型为image.PixelMap
  11. import image from '@ohos.multimedia.image';
  12. let imageSource = image.createImageSource("file://" + wallpaperPath);
  13. let opts = {
  14. "desiredSize": {
  15. "height": 3648,
  16. "width": 2736
  17. }
  18. };
  19. imageSource.createPixelMap(opts).then((pixelMap) => {
  20. wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
  21. if (error) {
  22. console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
  23. return;
  24. }
  25. console.log(`success to setWallpaper.`);
  26. });
  27. }).catch((error) => {
  28. console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
  29. });

wallpaper.setWallpaper(deprecated)

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

将指定资源设置为指定类型的壁纸。

说明

从 API version 7开始支持,从API version 9开始废弃。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

source

string | image.PixelMap

JPEG或PNG文件的Uri路径,或者PNG格式文件的位图。

wallpaperType

WallpaperType

壁纸类型。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

示例:

  1. // source类型为string
  2. let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
  3. wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
  4. console.log(`success to setWallpaper.`);
  5. }).catch((error) => {
  6. console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
  7. });
  8. // source类型为image.PixelMap
  9. import image from '@ohos.multimedia.image';
  10. let imageSource = image.createImageSource("file://" + wallpaperPath);
  11. let opts = {
  12. "desiredSize": {
  13. "height": 3648,
  14. "width": 2736
  15. }
  16. };
  17. imageSource.createPixelMap(opts).then((pixelMap) => {
  18. wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
  19. console.log(`success to setWallpaper.`);
  20. }).catch((error) => {
  21. console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
  22. });
  23. }).catch((error) => {
  24. console.error(`failed to createPixelMap because: ${JSON.stringify(error)}`);
  25. });

wallpaper.getFile(deprecated)

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

获取指定类型的壁纸文件。

说明

从 API version 8开始支持,从API version 9开始废弃。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

callback

AsyncCallback<number>

回调函数,调用成功则返回壁纸文件描述符ID,调用失败则返回error信息。

示例:

  1. wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
  2. if (error) {
  3. console.error(`failed to getFile because: ${JSON.stringify(error)}`);
  4. return;
  5. }
  6. console.log(`success to getFile: ${JSON.stringify(data)}`);
  7. });

wallpaper.getFile(deprecated)

getFile(wallpaperType: WallpaperType): Promise<number>

获取指定类型的壁纸文件。

说明

从 API version 8开始支持,从API version 9开始废弃。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名

类型

必填

说明

wallpaperType

WallpaperType

壁纸类型。

返回值:

类型

说明

Promise<number>

调用成功则返回壁纸文件描述符ID,调用失败则返回error信息。

示例:

  1. wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
  2. console.log(`success to getFile: ${JSON.stringify(data)}`);
  3. }).catch((error) => {
  4. console.error(`failed to getFile because: ${JSON.stringify(error)}`);
  5. });
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号