HarmonyOS API:@ohos.window (窗口)

joytrian
发布于 2023-4-4 15:45
浏览
0收藏

版本:v3.1 Beta

@ohos.window (窗口)

更新时间: 2023-02-24 16:50


窗口提供管理窗口的一些基础能力,包括对当前窗口的创建、销毁、各属性设置,以及对各窗口间的管理调度。


该模块提供以下窗口相关的常用功能:

  • ​Window​​:当前窗口实例,窗口管理器管理的基本单元。
  • ​WindowStage​​:窗口管理器。管理各个基本窗口单元。


说明

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

导入模块

import window from '@ohos.window';

WindowType7+

窗口类型枚举。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

说明

TYPE_APP

0

表示应用子窗口。

模型约束: 此接口仅可在FA模型下使用。

Configuration9+

创建子窗口时的参数。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

类型

必填

说明

name

string

窗口名字。

windowType

​WindowType​

窗口类型。

ctx

​BaseContext​

当前应用上下文信息。不设置,则默认为空。

FA模型下不需要使用该参数,即可创建子窗口。

displayId

number

当前物理屏幕id。不设置,则默认为-1。

parentId

number

父窗口id。不设置,则默认为-1。

AvoidAreaType7+

窗口内容需要规避区域的类型枚举。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

说明

TYPE_SYSTEM

0

表示系统默认区域。一般包括状态栏、导航栏和Dock栏,各设备系统定义可能不同。

TYPE_KEYBOARD9+

3

表示软键盘区域。

SystemBarProperties

状态栏、导航栏的属性。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

类型

必填

说明

statusBarColor

string

状态栏背景颜色,为十六进制RGB或ARGB颜色,不区分大小写,例如#00FF00或#FF00FF00。默认值:#0x66000000。

isStatusBarLightIcon7+

boolean

状态栏图标是否为高亮状态。true表示高亮;false表示不高亮。默认值:false。

statusBarContentColor8+

string

状态栏文字颜色。当设置此属性后, isStatusBarLightIcon属性设置无效。默认值:0xE5FFFFFF。

navigationBarColor

string

导航栏背景颜色,为十六进制RGB或ARGB颜色,不区分大小写,例如#00FF00或#FF00FF00。默认值:#0x66000000。

isNavigationBarLightIcon7+

boolean

导航栏图标是否为高亮状态。true表示高亮;false表示不高亮。默认值:false。

navigationBarContentColor8+

string

导航栏文字颜色。当设置此属性后, isNavigationBarLightIcon属性设置无效。默认值:#0xE5FFFFFF。

Orientation9+

窗口显示方向类型枚举。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

说明

UNSPECIFIED

0

表示未定义方向模式,由系统判定。

PORTRAIT

1

表示竖屏显示模式。

LANDSCAPE

2

表示横屏显示模式。

PORTRAIT_INVERTED

3

表示反向竖屏显示模式。

LANDSCAPE_INVERTED

4

表示反向横屏显示模式。

AUTO_ROTATION

5

表示传感器自动旋转模式。

AUTO_ROTATION_PORTRAIT

6

表示传感器自动竖向旋转模式。

AUTO_ROTATION_LANDSCAPE

7

表示传感器自动横向旋转模式。

AUTO_ROTATION_RESTRICTED

8

表示受开关控制的自动旋转模式。

AUTO_ROTATION_PORTRAIT_RESTRICTED

9

表示受开关控制的自动竖向旋转模式。

AUTO_ROTATION_LANDSCAPE_RESTRICTED

10

表述受开关控制的自动横向旋转模式。

LOCKED

11

表示锁定模式。

Rect7+

窗口矩形区域。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

类型

可读

可写

说明

left

number

矩形区域的左边界。

top

number

矩形区域的上边界。

width

number

矩形区域的宽度。

height

number

矩形区域的高度。

AvoidArea7+

窗口内容规避区域。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

类型

可读

可写

说明

visible9+

boolean

规避区域是否可见。

true表示可见;false表示不可见。

leftRect

​Rect​

屏幕左侧的矩形区。

topRect

​Rect​

屏幕顶部的矩形区。

rightRect

​Rect​

屏幕右侧的矩形区。

bottomRect

​Rect​

屏幕底部的矩形区。

Size7+

窗口大小。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

类型

可读

可写

说明

width

number

窗口宽度。

height

number

窗口高度。

WindowProperties

窗口属性。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称

类型

可读

可写

说明

windowRect7+

​Rect​

窗口尺寸。

type7+

​WindowType​

窗口类型。

isFullScreen

boolean

是否全屏,默认为false。true表示全屏;false表示非全屏。

isLayoutFullScreen7+

boolean

窗口是否为沉浸式,默认为false。true表示沉浸式;false表示非沉浸式。

focusable7+

boolean

窗口是否可聚焦,默认为true。true表示可聚焦;false表示不可聚焦。

touchable7+

boolean

窗口是否可触摸,默认为true。true表示可触摸;false表示不可触摸。

brightness

number

屏幕亮度, 取值范围为0~1,1表示最大亮度值。

isKeepScreenOn

boolean

屏幕是否常亮,默认为false。true表示常亮;false表示不常亮。

isPrivacyMode7+

boolean

隐私模式,默认为false。true表示模式开启;false表示模式关闭。

isTransparent7+

boolean

窗口是否透明。默认为false。true表示透明;false表示不透明。

id9+

number

窗口ID,默认值为0.0。

window.createWindow9+

createWindow(config: Configuration, callback: AsyncCallback<Window>): void

创建子窗口,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

config

​Configuration​

创建窗口时的参数。

callback

AsyncCallback<​​Window​​>

回调函数。返回当前创建的窗口对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300001

Repeated operation.

1300006

This window context is abnormal.

示例:

let windowClass = null;
let config = {name: "alertWindow", windowType: window.WindowType.TYPE_APP, ctx: this.context};
try {
    window.createWindow(config, (err, data) => {
        if (err.code) {
            console.error('Failed to create the window. Cause: ' + JSON.stringify(err));
            return;
        }
        windowClass = data;
        console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data));
        windowClass.resetSize(500, 1000);
    });
} catch (exception) {
    console.error('Failed to create the window. Cause: ' + JSON.stringify(exception));
}

window.createWindow9+

createWindow(config: Configuration): Promise<Window>

创建子窗口,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

config

​Configuration​

创建窗口时的参数。

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前创建的窗口对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300001

Repeated operation.

1300006

This window context is abnormal.

示例:

let windowClass = null;
let config = {name: "alertWindow", windowType: window.WindowType.TYPE_APP, ctx: this.context};
try {
    let promise = window.createWindow(config);
    promise.then((data)=> {
        windowClass = data;
        console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
    }).catch((err)=>{
        console.error('Failed to create the Window. Cause:' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to create the window. Cause: ' + JSON.stringify(exception));
}

window.findWindow9+

findWindow(name: string): Window

查找name所对应的窗口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

name

string

窗口id。

返回值:

类型

说明

​Window​

当前查找的窗口对象。

示例:

let windowClass = null;
try {
    windowClass = window.findWindow('alertWindow');
} catch (exception) {
    console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception));
}

window.getLastWindow9+

getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void

获取当前应用内最后显示的窗口,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

ctx

​BaseContext​

当前应用上下文信息。

callback

AsyncCallback<​​Window​​>

回调函数。返回当前应用内最后显示的窗口对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300006

This window context is abnormal.

示例:

let windowClass = null;
try {
    window.getLastWindow(this.context, (err, data) => {
        if (err.code) {
            console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
            return;
        }
        windowClass = data;
        console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
    });
} catch (exception) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(exception));
}

window.getLastWindow9+

getLastWindow(ctx: BaseContext): Promise<Window>

获取当前应用内最后显示的窗口,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

ctx

​BaseContext​

当前应用上下文信息。

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前应用内最后显示的窗口对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300006

This window context is abnormal.

示例:

let windowClass = null;
try {
    let promise = window.getLastWindow(this.context);
    promise.then((data)=> {
        windowClass = data;
        console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
    }).catch((err)=>{
        console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(exception));
}

window.create(deprecated)

create(id: string, type: WindowType, callback: AsyncCallback<Window>): void

创建子窗口,使用callback异步回调。

说明

从 API version 7开始支持,从API version 9开始废弃,推荐使用​​createWindow()​​。

模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

id

string

窗口id。

type

​WindowType​

窗口类型。

callback

AsyncCallback<​​Window​​>

回调函数。返回当前创建的子窗口对象。

示例:

let windowClass = null;
window.create('first', window.WindowType.TYPE_APP,(err,data) => {
    if(err.code){
        console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err));
        return;
    }
    windowClass = data;
    console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data));
});

window.create(deprecated)

create(id: string, type: WindowType): Promise<Window>

创建子窗口,使用Promise异步回调。

说明

从 API version 7开始支持,从API version 9开始废弃,推荐使用​​createWindow()​​。

模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

id

string

窗口id。

type

​WindowType​

窗口类型。

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前创建的子窗口对象。

示例:

let windowClass = null;
let promise = window.create('first', window.WindowType.TYPE_APP);
promise.then((data)=> {
    windowClass = data;
    console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data));
}).catch((err)=>{
    console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err));
});

window.create(deprecated)

create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void

创建子窗口,使用callback异步回调。

当前此接口仅可在FA模型下使用。

说明

从 API version 7开始支持,从API version 9开始废弃,推荐使用​​createWindow()​​。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

ctx

​BaseContext​

当前应用上下文信息。

id

string

窗口id。

type

​WindowType​

窗口类型。

callback

AsyncCallback<​​Window​​>

回调函数。返回当前创建的子窗口对象。

示例:

window.create(deprecated)

create(ctx: BaseContext, id: string, type: WindowType): Promise<Window>

创建子窗口,使用Promise异步回调。

当前此接口仅可在FA模型下使用。


说明

从 API version 7开始支持,从API version 9开始废弃,推荐使用​​createWindow()​​。


系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

ctx

​BaseContext​

当前应用上下文信息。

id

string

窗口id。

type

​WindowType​

窗口类型。

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前创建的子窗口对象。

示例:

let windowClass = null;
window.create(this.context, 'alertWindow', window.WindowType.TYPE_APP, (err, data) => {
    if (err.code) {
        console.error('Failed to create the window. Cause: ' + JSON.stringify(err));
        return;
    }
    windowClass = data;
    console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data));
    windowClass.resetSize(500, 1000);
});

window.find(deprecated)

find(id: string, callback: AsyncCallback<Window>): void

查找id所对应的窗口,使用callback异步回调。


说明

从 API version 7开始支持,从API version 9开始废弃,推荐使用​​findWindow()​​。


系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

id

string

窗口id。

callback

AsyncCallback<​​Window​​>

回调函数。返回当前查找到的窗口对象。

示例:

let windowClass = null;
window.find('alertWindow', (err, data) => {
    if (err.code) {
        console.error('Failed to find the Window. Cause: ' + JSON.stringify(err));
        return;
    }
    windowClass = data;
    console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data));
});

window.find(deprecated)

find(id: string): Promise<Window>

查找id所对应的窗口,使用Promise异步回调。


说明

从 API version 7开始支持,从API version 9开始废弃,推荐使用​​findWindow()​​。


系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

id

string

窗口id。

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前查找的窗口对象。

示例:

let windowClass = null;
let promise = window.find('alertWindow');
promise.then((data)=> {
    windowClass = data;
    console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data));
}).catch((err)=>{
    console.error('Failed to find the Window. Cause: ' + JSON.stringify(err));
});

window.getTopWindow(deprecated)

getTopWindow(callback: AsyncCallback<Window>): void

获取当前应用内最后显示的窗口,使用callback异步回调。


说明

从 API version 6开始支持,从API version 9开始废弃,推荐使用​​getLastWindow()​​。


模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

callback

AsyncCallback<​​Window​​>

回调函数。返回当前应用内最后显示的窗口对象。

示例:

let windowClass = null;
window.getTopWindow((err, data) => {
    if (err.code) {
        console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
        return;
    }
    windowClass = data;
    console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
});

window.getTopWindow(deprecated)

getTopWindow(): Promise<Window>

获取当前应用内最后显示的窗口,使用Promise异步回调。


说明

从 API version 6开始支持,从API version 9开始废弃,推荐使用​​getLastWindow()​​。


模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前应用内最后显示的窗口对象。

示例:

let windowClass = null;
let promise = window.getTopWindow();
promise.then((data)=> {
    windowClass = data;
    console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
}).catch((err)=>{
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
});

window.getTopWindow(deprecated)

getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void

获取当前应用内最后显示的窗口,使用callback异步回调。


说明

从 API version 8开始支持,从API version 9开始废弃,推荐使用​​getLastWindow()​​。


系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

ctx

​BaseContext​

当前应用上下文信息。

callback

AsyncCallback<​​Window​​>

回调函数。返回当前应用内最后显示的窗口对象。

示例:

let windowClass = null;
window.getTopWindow(this.context, (err, data) => {
    if (err.code) {
        console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
        return;
    }
    windowClass = data;
    console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
});

window.getTopWindow(deprecated)

getTopWindow(ctx: BaseContext): Promise<Window>

获取当前应用内最后显示的窗口,使用Promise异步回调。


说明

从 API version 8开始支持,从API version 9开始废弃,推荐使用​​getLastWindow()​​。


系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

ctx

​BaseContext​

当前应用上下文信息。

返回值:

类型

说明

Promise<​​Window​​>

Promise对象。返回当前应用内最后显示的窗口对象。

示例:

let windowClass = null;
let promise = window.getTopWindow(this.context);
promise.then((data)=> {
     windowClass = data;
    console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
}).catch((err)=>{
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err));
});

Window

当前窗口实例,窗口管理器管理的基本单元。

下列API示例中都需先使用​​getLastWindow()​​​、​​createWindow()​​​、​​findWindow()​​中的任一方法获取到Window实例,再通过此实例调用对应方法。

showWindow9+

showWindow(callback: AsyncCallback<void>): void

显示当前窗口,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

windowClass.showWindow((err) => {
    if (err.code) {
        console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in showing the window.');
});

showWindow9+

showWindow(): Promise<void>

显示当前窗口,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

let promise = windowClass.showWindow();
promise.then(()=> {
    console.info('Succeeded in showing the window.');
}).catch((err)=>{
    console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
});

destroyWindow9+

destroyWindow(callback: AsyncCallback<void>): void

销毁当前窗口,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

windowClass.destroyWindow((err) => {
    if (err.code) {
        console.error('Failed to destroy the window. Cause:' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in destroying the window.');
});

destroyWindow9+

destroyWindow(): Promise<void>

销毁当前窗口,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let promise = windowClass.destroyWindow();
promise.then(()=> {
    console.info('Succeeded in destroying the window.');
}).catch((err)=>{
    console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err));
});

moveWindowTo9+

moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void

移动窗口位置,使用callback异步回调。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

x

number

窗口在x轴方向移动的值,值为正表示右移,单位为px。

y

number

窗口在y轴方向移动的值,值为正表示下移,单位为px。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

moveWindowTo9+

moveWindowTo(x: number, y: number): Promise<void>

移动窗口位置,使用Promise异步回调。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

x

number

窗口在x轴方向移动的值,值为正表示右移,单位为px。

y

number

窗口在y轴方向移动的值,值为正表示下移,单位为px。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

try {
    windowClass.moveWindowTo(300, 300, (err)=>{
        if (err.code) {
            console.error('Failed to move the window. Cause:' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in moving the window.');
    });
} catch (exception) {
    console.error('Failed to move the window. Cause:' + JSON.stringify(exception));
}

resize9+

resize(width: number, height: number, callback: AsyncCallback<void>): void

改变当前窗口大小,使用callback异步回调。

应用主窗口与子窗口存在大小限制,宽度范围:[320, 2560],高度范围:[240, 2560],单位为vp。

系统窗口存在大小限制,宽度范围:[0, 2560],高度范围:[0, 2560],单位为vp。

设置的宽度与高度受到此约束限制。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

width

number

目标窗口的宽度,单位为px。

height

number

目标窗口的高度,单位为px。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

try {
    windowClass.resize(500, 1000, (err) => {
        if (err.code) {
            console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in changing the window size.');
    });
} catch (exception) {
    console.error('Failed to change the window size. Cause:' + JSON.stringify(exception));
}

resize9+

resize(width: number, height: number): Promise<void>

改变当前窗口大小,使用Promise异步回调。

应用主窗口与子窗口存在大小限制,宽度范围:[320, 2560],高度范围:[240, 2560],单位为vp。

系统窗口存在大小限制,宽度范围:[0, 2560],高度范围:[0, 2560],单位为vp。

设置的宽度与高度受到此约束限制。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

width

number

目标窗口的宽度,单位为px。

height

number

目标窗口的高度,单位为px。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

try {
    let promise = windowClass.resize(500, 1000);
    promise.then(()=> {
        console.info('Succeeded in changing the window size.');
    }).catch((err)=>{
        console.error('Failed to change the window size. Cause: ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to change the window size. Cause: ' + JSON.stringify(exception));
}

getWindowProperties9+

getWindowProperties(): WindowProperties

获取当前窗口的属性,返回WindowProperties。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型

说明

​WindowProperties​

当前窗口属性。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

try {
    let properties = windowClass.getWindowProperties();
} catch (exception) {
    console.error('Failed to obtain the window properties. Cause: ' + JSON.stringify(exception));
}

getWindowAvoidArea9+

getWindowAvoidArea(type: AvoidAreaType): AvoidArea

获取窗口内容规避的区域;如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

​AvoidAreaType​

表示规避区类型。

返回值:

类型

说明

​AvoidArea​

窗口内容规避区域。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

let type = window.AvoidAreaType.TYPE_SYSTEM;
try {
    let avoidArea = windowClass.getWindowAvoidArea(type);
} catch (exception) {
    console.error('Failed to obtain the area. Cause:' + JSON.stringify(exception));
}

setWindowLayoutFullScreen9+

setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void

设置窗口的布局是否为全屏显示状态,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

isLayoutFullScreen

boolean

窗口的布局是否为全屏显示状态(该全屏状态下状态栏、导航栏仍然显示)。true表示全屏显示;false表示非全屏显示。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let isLayoutFullScreen= true;
try {
    windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err) => {
        if (err.code) {
            console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in setting the window layout to full-screen mode.');
    });
} catch (exception) {
    console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(exception));
}

setWindowLayoutFullScreen9+

setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>

设置窗口的布局是否为全屏显示状态,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

isLayoutFullScreen

boolean

窗口的布局是否为全屏显示状态(该全屏状态下状态栏、导航栏仍然显示)。true表示全屏显示;false表示非全屏显示。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let isLayoutFullScreen = true;
try {
    let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen);
    promise.then(()=> {
        console.info('Succeeded in setting the window layout to full-screen mode.');
    }).catch((err)=>{
        console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(exception));
}

setWindowSystemBarEnable9+

setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void

设置导航栏、状态栏的可见模式,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

names

Array<'status'|'navigation'>

设置状态栏和导航栏是否显示。

例如,需全部显示,该参数设置为['status', 'navigation'];不设置,则默认不显示。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

// 此处以不显示导航栏、状态栏为例
let names = [];
try {
    windowClass.setWindowSystemBarEnable(names, (err) => {
        if (err.code) {
            console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in setting the system bar to be invisible.');
    });
} catch (exception) {
    console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(exception));
}

setWindowSystemBarEnable9+

setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void>

设置导航栏、状态栏的可见模式,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

names

Array<'status'|'navigation'>

设置状态栏和导航栏是否显示。

例如,需全部显示,该参数设置为['status', 'navigation'];不设置,则默认不显示。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

// 此处以不显示导航栏、状态栏为例
let names = [];
try {
    let promise = windowClass.setWindowSystemBarEnable(names);
    promise.then(()=> {
        console.info('Succeeded in setting the system bar to be invisible.');
    }).catch((err)=>{
        console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(exception));
}

setWindowSystemBarProperties9+

setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void

设置窗口内导航栏、状态栏的属性,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

SystemBarProperties

​SystemBarProperties​

导航栏、状态栏的属性。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let SystemBarProperties = {
    statusBarColor: '#ff00ff',
    navigationBarColor: '#00ff00',
    //以下两个属性从API Version8开始支持
    statusBarContentColor:'#ffffff',
    navigationBarContentColor:'#00ffff'
};
try {
    windowClass.setWindowSystemBarProperties(SystemBarProperties, (err) => {
        if (err.code) {
            console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in setting the system bar properties.');
    });
} catch (exception) {
    console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(exception));
}

setWindowSystemBarProperties9+

setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void>

设置窗口内导航栏、状态栏的属性,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

SystemBarProperties

​SystemBarProperties​

导航栏、状态栏的属性。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let SystemBarProperties = {
    statusBarColor: '#ff00ff',
    navigationBarColor: '#00ff00',
    //以下两个属性从API Version8开始支持
    statusBarContentColor:'#ffffff',
    navigationBarContentColor:'#00ffff'
};
try {
    let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties);
    promise.then(()=> {
        console.info('Succeeded in setting the system bar properties.');
    }).catch((err)=>{
        console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(exception));
}

setPreferredOrientation9+

setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void

设置窗口的显示方向属性,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

Orientation

​Orientation​

窗口显示方向的属性。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

let orientation = window.Orientation.AUTO_ROTATION;
try {
    windowClass.setPreferredOrientation(orientation, (err) => {
        if (err.code) {
            console.error('Failed to set window orientation. Cause: ' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in setting window orientation.');
    });
} catch (exception) {
    console.error('Failed to set window orientation. Cause: ' + JSON.stringify(exception));
}

setPreferredOrientation9+

setPreferredOrientation(orientation: Orientation): Promise<void>

设置窗口的显示方向属性,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

Orientation

​Orientation​

窗口显示方向的属性。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

let orientation = window.Orientation.AUTO_ROTATION;
try {
    let promise = windowClass.setPreferredOrientation(orientation);
    promise.then(()=> {
        console.info('Succeeded in setting the window orientation.');
    }).catch((err)=>{
        console.error('Failed to set the window orientation. Cause: ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to set window orientation. Cause: ' + JSON.stringify(exception));
}

setUIContent9+

setUIContent(path: string, callback: AsyncCallback<void>): void

为当前窗口加载具体页面内容,使用callback异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

path

string

设置加载页面的路径。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

try {
    windowClass.setUIContent('pages/page2/page2', (err) => {
    if (err.code) {
            console.error('Failed to load the content. Cause:' + JSON.stringify(err));
            return;
    }
    console.info('Succeeded in loading the content.');
    });
} catch (exception) {
    console.error('Failed to load the content. Cause:' + JSON.stringify(exception));
}

setUIContent9+

setUIContent(path: string): Promise<void>

为当前窗口加载具体页面内容,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

path

string

设置加载页面的路径。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

try {
    let promise = windowClass.setUIContent('pages/page2/page2');
    promise.then(()=> {
        console.info('Succeeded in loading the content.');
    }).catch((err)=>{
        console.error('Failed to load the content. Cause: ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to load the content. Cause: ' + JSON.stringify(exception));
}

loadContent9+

loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void

为当前窗口加载与LocalStorage相关联的具体页面内容,使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

path

string

设置加载页面的路径。

storage

​LocalStorage​

存储单元,为应用程序范围内的可变状态属性和非可变状态属性提供存储。

callback

AsyncCallback<void>

回调函数。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let storage = new LocalStorage();
storage.setOrCreate('storageSimpleProp',121);
console.log('onWindowStageCreate');
try {
    windowClass.loadContent('pages/page2', storage, (err) => {
        if (err.code) {
            console.error('Failed to load the content. Cause:' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in loading the content.');
    });
} catch (exception) {
    console.error('Failed to load the content. Cause:' + JSON.stringify(exception));
}

loadContent9+

loadContent(path: string, storage: LocalStorage): Promise<void>

为当前窗口加载与LocalStorage相关联的具体页面内容,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

path

string

设置加载页面的路径。

storage

​LocalStorage​

存储单元,为应用程序范围内的可变状态属性和非可变状态属性提供存储。

返回值:

类型

说明

Promise<void>

无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

1300003

This window manager service works abnormally.

示例:

let storage = new LocalStorage();
storage.setOrCreate('storageSimpleProp',121);
console.log('onWindowStageCreate');
try {
    let promise = windowClass.loadContent('pages/page2', storage);
    promise.then(() => {
        console.info('Succeeded in loading the content.');
    }).catch((err) => {
        console.error('Failed to load the content. Cause:' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to load the content. Cause:' + JSON.stringify(exception));
}

isWindowShowing9+

isWindowShowing(): boolean

判断当前窗口是否已显示。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型

说明

boolean

当前窗口是否已显示。true表示当前窗口已显示,false则表示当前窗口未显示。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

try {
    let data = windowClass.isWindowShowing();
    console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
} catch (exception) {
    console.error('Failed to check whether the window is showing. Cause: ' + JSON.stringify(exception));
}

on('windowSizeChange')7+

on(type: 'windowSizeChange', callback: Callback<Size>): void

开启窗口尺寸变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

string

监听事件,固定为'windowSizeChange',即窗口尺寸变化事件。

callback

Callback<​​Size​​>

回调函数。返回当前的窗口尺寸。

示例:

try {
    windowClass.on('windowSizeChange', (data) => {
        console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data));
    });
} catch (exception) {
    console.error('Failed to enable the listener for window size changes. Cause: ' + JSON.stringify(exception));
}

off('windowSizeChange')7+

off(type: 'windowSizeChange', callback?: Callback<Size>): void

关闭窗口尺寸变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

string

监听事件,固定为'windowSizeChange',即窗口尺寸变化事件。

callback

Callback<​​Size​​>

回调函数。返回当前的窗口尺寸。

示例:

try {
    windowClass.off('windowSizeChange');
} catch (exception) {
    console.error('Failed to disable the listener for window size changes. Cause: ' + JSON.stringify(exception));
}

on('avoidAreaChange')9+

on(type: 'avoidAreaChange', callback: Callback<{AvoidAreaType, AvoidArea}>): void

开启系统规避区变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

string

监听事件,固定为'avoidAreaChange',即系统规避区变化事件。

callback

Callback<{​​AvoidAreaType​​​, ​​AvoidArea​​}>

回调函数。返回当前规避区以及规避区类型。

示例:

try {
    windowClass.on('avoidAreaChange', (data) => {
        console.info('Succeeded in enabling the listener for system avoid area changes. type:' +
            JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area));
    });
} catch (exception) {
    console.error('Failed to enable the listener for system avoid area changes. Cause: ' + JSON.stringify(exception));
}

off('avoidAreaChange')9+

off(type: 'avoidAreaChange', callback: Callback<{AvoidAreaType, AvoidArea}>): void

关闭系统规避区变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

string

监听事件,固定为'avoidAreaChange',即系统规避区变化事件。

callback

Callback<{​​AvoidAreaType​​​, ​​AvoidArea​​}>

回调函数。返回当前规避区以及规避区类型。

示例:

try {
    windowClass.off('avoidAreaChange');
} catch (exception) {
    console.error('Failed to disable the listener for system avoid area changes. Cause: ' + JSON.stringify(exception));
}

on('keyboardHeightChange')7+

on(type: 'keyboardHeightChange', callback: Callback<number>): void

开启键盘高度变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

string

监听事件,固定为'keyboardHeightChange',即键盘高度变化事件。

callback

Callback<number>

回调函数。返回当前的键盘高度。

示例:

try {
    windowClass.on('keyboardHeightChange', (data) => {
        console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data));
    });
} catch (exception) {
    console.error('Failed to enable the listener for keyboard height changes. Cause: ' + JSON.stringify(exception));
}

off('keyboardHeightChange')7+

off(type: 'keyboardHeightChange', callback?: Callback<number>): void

关闭键盘高度变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

type

string

监听事件,固定为'keyboardHeightChange',即键盘高度变化事件。

callback

Callback<number>

回调函数。返回当前的键盘高度。

示例:

try {
    windowClass.off('keyboardHeightChange');
} catch (exception) {
    console.error('Failed to disable the listener for keyboard height changes. Cause: ' + JSON.stringify(exception));
}

setWindowBackgroundColor9+

setWindowBackgroundColor(color: string): void

设置窗口的背景色。Stage模型下,该接口需要在​​loadContent​​之后使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名

类型

必填

说明

color

string

需要设置的背景色,为十六进制RGB或ARGB颜色,不区分大小写,例如#00FF00或#FF00FF00。

错误码:

以下错误码的详细介绍请参见​​窗口错误码​​。

错误码ID

错误信息

1300002

This window state is abnormal.

示例:

let color = '#00ff33';
try {
    windowClass.setWindowBackgroundColor(color);
} catch (exception) {
    console.error('Failed to set the background color. Cause: ' + JSON.stringify(exception));
}

文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-window-0000001477981397-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001477981397__windowcreatewindow9​

已于2023-4-4 15:45:14修改
收藏
回复
举报
回复
    相关推荐