壁紙

說明： 本模塊首批接口從API version 7開始支持。后續版本的新增接口，采用上角標單獨標記接口的起始版本。 開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

導入模塊

import wallpaper from '@ohos.wallpaper';

WallpaperType

定義壁紙類型。

系統能力 : 以下各項對應的系統能力均為SystemCapability.MiscServices.Wallpaper。

wallpaper.getColors

getColors(wallpaperType: WallpaperType, callback: AsyncCallback>): void

獲取指定類型壁紙的主要顏色信息。

系統能力 : SystemCapability.MiscServices.Wallpaper

參數：

示例：

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>

獲取指定類型壁紙的主要顏色信息。

系統能力 : SystemCapability.MiscServices.Wallpaper

參數：

返回值：

示例：

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

參數：

示例：

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

參數：

返回值：

示例：

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

參數：

示例：

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

返回值：

示例：

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

參數：

示例：

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

返回值：

示例：

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

參數：

示例：

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

返回值：

示例：

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

參數：

示例：

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

返回值：

示例：

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

參數：

示例：

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

參數：

返回值：

示例：

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

參數：

示例：

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

參數：

返回值：

示例：

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): void;

獲取壁紙圖片的像素圖。

需要權限 ：ohos.permission.GET_WALLPAPER 和 ohos.permission.READ_USER_STORAGE

系統能力 : SystemCapability.MiscServices.Wallpaper

系統API ：此接口為系統接口，三方應用不支持調用。

參數：

示例：

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

獲取壁紙圖片的像素圖。

需要權限 ：ohos.permission.GET_WALLPAPER 和 ohos.permission.READ_USER_STORAGE

系統能力 : SystemCapability.MiscServices.Wallpaper

系統API ：此接口為系統接口，三方應用不支持調用。

參數：

返回值：

示例：

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

參數：

示例：

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

參數：

示例：

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。

審核編輯 黃宇