壁紙
說明: 本模塊首批接口從API version 7開始支持。后續版本的新增接口,采用上角標單獨標記接口的起始版本。
導入模塊
import wallpaper from '@ohos.wallpaper';
WallpaperType
定義壁紙類型。
系統能力: 以下各項對應的系統能力均為SystemCapability.MiscServices.Wallpaper。
名稱 | 說明 |
---|---|
WALLPAPER_LOCKSCREEN | 鎖屏壁紙標識。 |
WALLPAPER_SYSTEM | 主屏幕壁紙標識。 |
wallpaper.getColors
getColors(wallpaperType: WallpaperType, callback: AsyncCallback<Array>): void
獲取指定類型壁紙的主要顏色信息。
系統能力: 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.`);
});
wallpaper.getColors
getColors(wallpaperType: WallpaperType): Promise<Array>
獲取指定類型壁紙的主要顏色信息。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
返回值:
類型 | 說明 |
---|---|
Promise<Array<[RgbaColor]>> | 返回壁紙的主要顏色信息。 |
示例:
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {console.log(`success to getColors.`);
}).catch((error) => {console.error(`failed to getColors because: ` + JSON.stringify(error));
});
wallpaper.getId
getId(wallpaperType: WallpaperType, callback: AsyncCallback): void
獲取指定類型壁紙的ID。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
callback | AsyncCallback | 是 | 回調函數,返回壁紙的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));
});
wallpaper.getId
getId(wallpaperType: WallpaperType): Promise
獲取指定類型壁紙的ID。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
返回值:
類型 | 說明 |
---|---|
Promise | 壁紙的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));
});
wallpaper.getMinHeight
getMinHeight(callback: AsyncCallback): void
獲取壁紙的最小高度值。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
callback | AsyncCallback | 是 | 回調函數,返回壁紙的最小高度值,單位是像素。如果返回值等于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));
});
wallpaper.getMinHeight
getMinHeight(): Promise
獲取壁紙的最小高度值。
系統能力: SystemCapability.MiscServices.Wallpaper
返回值:
類型 | 說明 |
---|---|
Promise | 返回壁紙的最小高度值,單位是像素。如果返回值等于0,說明沒有設置壁紙,調用者應該使用默認顯示的高度值代替。 |
示例:
wallpaper.getMinHeight().then((data) => {console.log(`success to getMinHeight: ` + JSON.stringify(data));
}).catch((error) => {console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
});
wallpaper.getMinWidth
getMinWidth(callback: AsyncCallback): void
獲取壁紙的最小寬度值。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
callback | AsyncCallback | 是 | 回調函數,壁紙的最小寬度值,單位是像素。如果返回值等于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));
});
wallpaper.getMinWidth
getMinWidth(): Promise
獲取壁紙的最小寬度值。
系統能力: SystemCapability.MiscServices.Wallpaper
返回值:
類型 | 說明 |
---|---|
Promise | 壁紙的最小寬度值,單位是像素。如果返回值等于0,說明沒有設置壁紙,調用者應該使用默認顯示的寬度值代替。 |
示例:
wallpaper.getMinWidth().then((data) => {console.log(`success to getMinWidth: ` + JSON.stringify(data));
}).catch((error) => {console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
});
wallpaper.isChangePermitted
isChangePermitted(callback: AsyncCallback): void
是否允許應用改變當前用戶的壁紙。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
callback | AsyncCallback | 是 | 回調函數,返回是否允許應用改變當前用戶的壁紙。如果允許返回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));
});
wallpaper.isChangePermitted
isChangePermitted(): Promise
是否允許應用改變當前用戶的壁紙。
系統能力: SystemCapability.MiscServices.Wallpaper
返回值:
類型 | 說明 |
---|---|
Promise | 返回是否允許應用改變當前用戶的壁紙。如果允許返回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));
});
wallpaper.isOperationAllowed
isOperationAllowed(callback: AsyncCallback): void
是否允許用戶設置壁紙。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
callback | AsyncCallback | 是 | 回調函數,返回是否允許用戶設置壁紙。如果允許返回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));
});
wallpaper.isOperationAllowed
isOperationAllowed(): Promise
是否允許用戶設置壁紙。
系統能力: SystemCapability.MiscServices.Wallpaper
返回值:
類型 | 說明 |
---|---|
Promise | 異步回調函數,返回是否允許用戶設置壁紙。如果允許返回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));
});
wallpaper.reset
reset(wallpaperType: WallpaperType, callback: AsyncCallback): void
移除指定類型的壁紙,恢復為默認顯示的壁紙。
需要權限:ohos.permission.SET_WALLPAPER
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
callback | AsyncCallback | 是 | 回調函數,調用成功則返回是否移除成功的結果,調用失敗則返回error信息。 |
示例:
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {if (error) {console.error(`failed to reset because: ` + JSON.stringify(error));return;}console.log(`success to reset.`);
});
wallpaper.reset
reset(wallpaperType: WallpaperType): Promise
移除指定類型的壁紙,恢復為默認顯示的壁紙。
需要權限:ohos.permission.SET_WALLPAPER
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
返回值:
類型 | 說明 |
---|---|
Promise | 調用成功則返回是否移除成功的結果,調用失敗則返回error信息。 |
示例:
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {console.log(`success to reset.`);
}).catch((error) => {console.error(`failed to reset because: ` + JSON.stringify(error));
});
wallpaper.setWallpaper
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType, callback: AsyncCallback): void
將指定資源設置為指定類型的壁紙。
需要權限:ohos.permission.SET_WALLPAPER
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
source | string | [PixelMap] | |
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
callback | AsyncCallback | 是 | 回調函數,調用成功則返回是返回設置的結果,調用失敗則返回error信息。 |
示例:
// source類型為string
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { 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, data) => { 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));
});
wallpaper.setWallpaper
setWallpaper(source: string | image.PixelMap, wallpaperType: WallpaperType): Promise
將指定資源設置為指定類型的壁紙。
需要權限:ohos.permission.SET_WALLPAPER
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
source | string | [PixelMap] | 是 |
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
返回值:
類型 | 說明 |
---|---|
Promise | 調用成功則返回是返回設置的結果,調用失敗則返回error信息。 |
示例:
// source類型為string
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {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((data) => {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));
});
wallpaper.getFile8+
getFile(wallpaperType: WallpaperType, callback: AsyncCallback): void
獲取指定類型的壁紙文件。
需要權限:ohos.permission.GET_WALLPAPER 和 ohos.permission.READ_USER_STORAGE
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
callback | AsyncCallback | 是 | 回調函數,調用成功則返回壁紙文件描述符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));
});
wallpaper.getFile8+
getFile(wallpaperType: WallpaperType): Promise
獲取指定類型的壁紙文件。
需要權限:ohos.permission.GET_WALLPAPER 和 ohos.permission.READ_USER_STORAGE
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
返回值:
類型 | 說明 |
---|---|
Promise | 調用成功則返回壁紙文件描述符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));
});
wallpaper.getPixelMap
getPixelMap(wallpaperType: WallpaperType, callback: AsyncCallback<image.PixelMap>): void;
獲取壁紙圖片的像素圖。
需要權限:ohos.permission.GET_WALLPAPER 和 ohos.permission.READ_USER_STORAGE
系統能力: SystemCapability.MiscServices.Wallpaper
系統API:此接口為系統接口,三方應用不支持調用。
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
callback | AsyncCallback | 是 | 回調函數,調用成功則返回壁紙圖片的像素圖大小,調用失敗則返回error信息。 |
示例:
wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM, function (err, data) {console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem err : ' + JSON.stringify(err));console.info('wallpaperXTS ===> testGetPixelMapCallbackSystem data : ' + JSON.stringify(data));
});
wallpaper.getPixelMap
getPixelMap(wallpaperType: WallpaperType): Promise<image.PixelMap>
獲取壁紙圖片的像素圖。
需要權限:ohos.permission.GET_WALLPAPER 和 ohos.permission.READ_USER_STORAGE
系統能力: SystemCapability.MiscServices.Wallpaper
系統API:此接口為系統接口,三方應用不支持調用。
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
wallpaperType | [WallpaperType] | 是 | 壁紙類型。 |
返回值:
類型 | 說明 |
---|---|
Promise | 調用成功則返回壁紙圖片的像素圖大小,調用失敗則返回error信息。 |
示例:
wallpaper.getPixelMap(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem data : ' + data);console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem data : ' + JSON.stringify(data));
}).catch((err) => {console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem err : ' + err);console.info('wallpaperXTS ===> testGetPixelMapPromiseSystem err : ' + JSON.stringify(err));
});
wallpaper.on(‘colorChange’)
on(type: ‘colorChange’, callback: (colors: Array, wallpaperType: WallpaperType) => void): void
訂閱壁紙顏色變化結果上報事件。
系統能力: SystemCapability.MiscServices.Wallpaper
參數:
參數名 | 類型 | 必填 | 說明 |
---|---|---|---|
type | string | 是 | 取值為’colorChange’,表示壁紙顏色變化結果上報事件。 |
callback | function | 是 | 壁紙顏色變化觸發該回調方法,返回壁紙類型和壁紙的主要顏色信息。 - colors 壁紙的主要顏色信息,其類型見[RgbaColor]。 - wallpaperType 壁紙類型。 |
示例:
let listener = (colors, wallpaperType) => {console.log(`wallpaper color changed.`);
};
wallpaper.on('colorChange', listener);
wallpaper.off(‘colorChange’)
off(type: ‘colorChange’, callback?: (colors: Array, 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.`);
};
wallpaper.on('colorChange', listener);
// 取消訂閱listener
wallpaper.off('colorChange', listener);
// 取消所有'colorChange'類型的訂閱
wallpaper.off('colorChange');
RgbaColor
系統能力: 以下各項對應的系統能力均為SystemCapability.MiscServices.Wallpaper。
名稱 | 參數類型 | 可讀 | 可寫 | 說明 |
---|---|---|---|---|
red | number | 是 | 是 | 表示紅色值,范圍為 0 到 255。 |
green | number | 是 | 是 | 表示綠色值,范圍為 0 到 255。 |
blue | number | 是 | 是 | 表示藍色值,范圍為 0 到 255。 |
alpha | number | 是 | 是 | 表示 alpha 值,范圍為 0 到 255。 |