@ohos.wallpaper (壁纸)


@ohos.wallpaper (壁纸)

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

说明:

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

导入模块

import wallpaper from '@ohos.wallpaper';
1

WallpaperType

定义壁纸的枚举类型。

系统能力: SystemCapability.MiscServices.Wallpaper

名称 说明
WALLPAPER_SYSTEM 0 主屏幕壁纸标识。
WALLPAPER_LOCKSCREEN 1 锁屏壁纸标识。

RgbaColor

定义壁纸颜色信息结构。

系统能力: SystemCapability.MiscServices.Wallpaper

名称 类型 可读 可写 说明
red number 表示红色值,范围为 0 到 255。
green number 表示绿色值,范围为 0 到 255。
blue number 表示蓝色值,范围为 0 到 255。
alpha number 表示 alpha 值,范围为 0 到 255。

wallpaper.getColorsSync9+

getColorsSync(wallpaperType: WallpaperType): Array<RgbaColor>

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

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值

类型 说明
Array<RgbaColor> 返回壁纸的主要颜色信息。

示例

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)}`);
}
1
2
3
4
5
6

wallpaper.getIdSync9+

getIdSync(wallpaperType: WallpaperType): number

获取指定类型壁纸的ID。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值

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

示例

try {
    let id = wallpaper.getIdSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
    console.log(`success to getIdSync: ${JSON.stringify(id)}`);
} catch (error) {
    console.error(`failed to getIdSync because: ${JSON.stringify(error)}`);
}
1
2
3
4
5
6

wallpaper.getMinHeightSync9+

getMinHeightSync(): number

获取壁纸的最小高度值。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

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

示例:

let minHeight = wallpaper.getMinHeightSync();
1

wallpaper.getMinWidthSync9+

getMinWidthSync(): number

获取壁纸的最小宽度值。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

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

示例:

let minWidth = wallpaper.getMinWidthSync();
1

wallpaper.isChangeAllowed9+

isChangeAllowed(): boolean

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

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

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

示例:

let isChangeAllowed = wallpaper.isChangeAllowed();
1

wallpaper.isUserChangeAllowed9+

isUserChangeAllowed(): boolean

是否允许用户设置壁纸。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型 说明
boolean 返回是否允许用户设置壁纸。如果允许返回true,否则返回false。

示例:

let isUserChangeAllowed = wallpaper.isUserChangeAllowed();
1

wallpaper.restore9+

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

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

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<void> 回调函数,移除壁纸成功,error为undefined,否则返回error信息。

示例:

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

wallpaper.restore9+

restore(wallpaperType: WallpaperType): Promise<void>

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

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

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

wallpaper.setImage9+

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

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

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
source string | image.PixelMap JPEG或png文件的Uri路径,或者png格式文件的位图。
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<void> 回调函数,设置壁纸成功,error为undefined,否则返回error信息。

示例:

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

wallpaper.setImage9+

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

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

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
source string | image.PixelMap JPEG或png文件的Uri路径,或者png格式文件的位图。
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

// source类型为string
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setImage(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then(() => {
    console.log(`success to setImage.`);
}).catch((error) => {
    console.error(`failed to setImage because: ${JSON.stringify(error)}`);
});

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

wallpaper.getFileSync9+

getFileSync(wallpaperType: WallpaperType): number;

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

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

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

示例:

try {
    let file = wallpaper.getFileSync(wallpaper.WallpaperType.WALLPAPER_SYSTEM);
    console.log(`success to getFileSync: ${JSON.stringify(file)}`);
} catch (error) {
    console.error(`failed to getFileSync because: ${JSON.stringify(error)}`);
}
1
2
3
4
5
6

wallpaper.getImage9+

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

获取壁纸图片的像素图。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

系统接口:此接口为系统接口。

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<image.PixelMap> 回调函数,调用成功则返回壁纸图片的像素图对象,调用失败则返回error信息。

示例:

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

wallpaper.getImage9+

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

获取壁纸图片的像素图。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

系统接口:此接口为系统接口。

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<image.PixelMap> 调用成功则返回壁纸图片的像素图对象,调用失败则返回error信息。

示例:

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

wallpaper.on('colorChange')9+

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

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

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
type string 取值为'colorChange',表示壁纸颜色变化结果上报事件。
callback function 壁纸颜色变化触发该回调方法,返回壁纸类型和壁纸的主要颜色信息。
- colors
壁纸的主要颜色信息,其类型见RgbaColor
- wallpaperType
壁纸类型。

示例:

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

wallpaper.off('colorChange')9+

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

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

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
type string 取值为'colorChange',表示取消订阅壁纸颜色变化结果上报事件。
callback function 表示要取消的壁纸颜色变化的回调,不填写该参数则取消订阅该type对应的所有回调。
- colors
壁纸的主要颜色信息,其类型见RgbaColor
- wallpaperType
壁纸类型。

示例:

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

try {
    // 取消订阅listener
    wallpaper.off('colorChange', listener);
} catch (error) {
    console.error(`failed to off because: ${JSON.stringify(error)}`);
}

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

wallpaper.getColors(deprecated)

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

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getColorsSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<Array<RgbaColor>> 回调函数,返回壁纸的主要颜色信息。

示例:

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

wallpaper.getColors(deprecated)

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

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getColorsSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<Array<RgbaColor>> 返回壁纸的主要颜色信息。

示例:

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

wallpaper.getId(deprecated)

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

获取指定类型壁纸的ID。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getIdSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<number> 回调函数,返回壁纸的ID。如果配置了指定类型的壁纸就返回一个大于等于0的数,否则返回-1。取值范围是-1到(2^31-1)。

示例:

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

wallpaper.getId(deprecated)

getId(wallpaperType: WallpaperType): Promise<number>

获取指定类型壁纸的ID。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getIdSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

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

示例:

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

wallpaper.getMinHeight(deprecated)

getMinHeight(callback: AsyncCallback<number>): void

获取壁纸的最小高度值。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getMinHeightSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
callback AsyncCallback<number> 回调函数,返回壁纸的最小高度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的高度值代替。

示例:

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

wallpaper.getMinHeight(deprecated)

getMinHeight(): Promise<number>

获取壁纸的最小高度值。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getMinHeightSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

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

示例:

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

wallpaper.getMinWidth(deprecated)

getMinWidth(callback: AsyncCallback<number>): void

获取壁纸的最小宽度值。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getMinWidthSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
callback AsyncCallback<number> 回调函数,壁纸的最小宽度值,单位是像素。如果返回值等于0,说明没有设置壁纸,调用者应该使用默认显示的宽度值代替。

示例:

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

wallpaper.getMinWidth(deprecated)

getMinWidth(): Promise<number>

获取壁纸的最小宽度值。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getMinWidthSync9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

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

示例:

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

wallpaper.isChangePermitted(deprecated)

isChangePermitted(callback: AsyncCallback<boolean>): void

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.isChangeAllowed9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
callback AsyncCallback<boolean> 回调函数,返回是否允许应用改变当前用户的壁纸。如果允许返回true,否则返回false。

示例:

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

wallpaper.isChangePermitted(deprecated)

isChangePermitted(): Promise<boolean>

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.isChangeAllowed9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型 说明
Promise<boolean> 返回是否允许应用改变当前用户的壁纸。如果允许返回true,否则返回false。

示例:

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

wallpaper.isOperationAllowed(deprecated)

isOperationAllowed(callback: AsyncCallback<boolean>): void

是否允许用户设置壁纸。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.isUserChangeAllowed9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
callback AsyncCallback<boolean> 回调函数,返回是否允许用户设置壁纸。如果允许返回true,否则返回false。

示例:

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

wallpaper.isOperationAllowed(deprecated)

isOperationAllowed(): Promise<boolean>

是否允许用户设置壁纸。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.isUserChangeAllowed9+代替。

系统能力: SystemCapability.MiscServices.Wallpaper

返回值:

类型 说明
Promise<boolean> 异步回调函数,返回是否允许用户设置壁纸。如果允许返回true,否则返回false。

示例:

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

wallpaper.reset(deprecated)

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

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.restore9+代替。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<void> 回调函数,移除壁纸成功,error为undefined,否则返回error信息。

示例:

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

wallpaper.reset(deprecated)

reset(wallpaperType: WallpaperType): Promise<void>

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.restore9+代替。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

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

wallpaper.setWallpaper(deprecated)

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

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.setImage9+代替。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
source string | image.PixelMap JPEG或png文件的Uri路径,或者png格式文件的位图。
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<void> 回调函数,设置壁纸成功,error为undefined,否则返回error信息。

示例:

// source类型为string
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error) => {
    if (error) {
        console.error(`failed to setWallpaper because: ${JSON.stringify(error)}`);
       return;
       }
    console.log(`success to setWallpaper.`);
});

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

wallpaper.setWallpaper(deprecated)

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

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

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.setImage9+代替。

需要权限:ohos.permission.SET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
source string | image.PixelMap JPEG或png文件的Uri路径,或者png格式文件的位图。
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

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

wallpaper.getFile(deprecated)

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

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

说明:

从 API version 8开始支持,从API version 9开始废弃。建议使用wallpaper.getFileSync9+代替。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<number> 回调函数,调用成功则返回壁纸文件描述符ID,调用失败则返回error信息。

示例:

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

wallpaper.getFile(deprecated)

getFile(wallpaperType: WallpaperType): Promise<number>

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

说明:

从 API version 8开始支持,从API version 9开始废弃。建议使用wallpaper.getFileSync9+代替。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<number> 调用成功则返回壁纸文件描述符ID,调用失败则返回error信息。

示例:

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

wallpaper.getPixelMap(deprecated)

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

获取壁纸图片的像素图。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getImage9+代替。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

系统接口:此接口为系统接口。

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。
callback AsyncCallback<image.PixelMap> 回调函数,调用成功则返回壁纸图片的像素图对象,调用失败则返回error信息。

示例:

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

wallpaper.getPixelMap(deprecated)

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

获取壁纸图片的像素图。

说明:

从 API version 7开始支持,从API version 9开始废弃。建议使用wallpaper.getImage9+代替。

需要权限:ohos.permission.GET_WALLPAPER

系统能力: SystemCapability.MiscServices.Wallpaper

系统接口:此接口为系统接口。

参数:

参数名 类型 必填 说明
wallpaperType WallpaperType 壁纸类型。

返回值:

类型 说明
Promise<image.PixelMap> 调用成功则返回壁纸图片的像素图对象,调用失败则返回error信息。

示例:

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