diff --git a/zh-cn/application-dev/windowmanager/application-window-stage.md b/zh-cn/application-dev/windowmanager/application-window-stage.md index c5f10cf29d3d1468a6a51a4fe9dbf74730d5d18e..b6f3089068dc396751e3c896ed833c80707cf49d 100644 --- a/zh-cn/application-dev/windowmanager/application-window-stage.md +++ b/zh-cn/application-dev/windowmanager/application-window-stage.md @@ -29,24 +29,24 @@ 上述场景涉及的常用接口如下表所示。更多API说明请参见[API参考](../reference/apis/js-apis-window.md)。 -| 实例名 | 接口名 | 描述 | -| -------- | -------- | -------- | -| WindowStage | getMainWindow(callback: AsyncCallback<Window>): void | 获取`WindowStage`实例下的主窗口。
此接口仅可在`Stage`模型下使用。 | -| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | 为当前`WindowStage`的主窗口加载具体页面。
此接口仅可在`Stage`模型下使用。 | -| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | 创建子窗口。
此接口仅可在`Stage`模型下使用。 | -| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\): void | 创建系统窗口。
-`config`：创建窗口时的参数。 | -| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面。 | -| Window | setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void | 设置窗口的背景色。 | -| Window | setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void | 设置屏幕亮度值。 | -| Window | setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void | 设置窗口是否为可触状态。 | -| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口位置。 | -| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | -| Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | 设置窗口布局是否为全屏布局。 | -| Window | setWindowSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | 设置导航栏、状态栏是否显示。 | -| Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | 设置窗口内导航栏、状态栏属性。
`systemBarProperties`：导航栏、状态栏的属性集合。 | -| Window | showWindow(callback: AsyncCallback\): void | 显示当前窗口。 | -| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | -| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | +| 实例名 | 接口名 | 描述 | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| WindowStage | getMainWindow(callback: AsyncCallback<Window>): void | 获取`WindowStage`实例下的主窗口。
此接口仅可在`Stage`模型下使用。 | +| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | 为当前`WindowStage`的主窗口加载具体页面。
此接口仅可在`Stage`模型下使用。 | +| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | 创建子窗口。
此接口仅可在`Stage`模型下使用。 | +| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\): void | 创建系统窗口。
-`config`：创建窗口时的参数。 | +| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面。 | +| Window | setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void | 设置窗口的背景色。 | +| Window | setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void | 设置屏幕亮度值。 | +| Window | setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void | 设置窗口是否为可触状态。 | +| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口位置。 | +| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | +| Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | 设置窗口布局是否为全屏布局。 | +| Window | setWindowSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | 设置导航栏、状态栏是否显示。 | +| Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | 设置窗口内导航栏、状态栏属性。
`systemBarProperties`：导航栏、状态栏的属性集合。 | +| Window | showWindow(callback: AsyncCallback\): void | 显示当前窗口。 | +| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | +| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | ## 设置应用主窗口 @@ -57,12 +57,15 @@ ### 开发步骤 1. 获取应用主窗口。 + 通过`getMainWindow`接口获取应用主窗口。 2. 设置主窗口属性。 + 可设置主窗口的背景色、亮度值、是否可触等多个属性，开发者可根据需要选择对应的接口。本示例以设置“是否可触”属性为例。 3. 为主窗口加载对应的目标页面。 + 通过`loadContent`接口加载主窗口的目标页面。 ```ts @@ -101,7 +104,6 @@ export default class EntryAbility extends UIAbility { }; ``` - ## 设置应用子窗口 开发者可以按需创建应用子窗口，如弹窗等，并对其进行属性设置等操作。 @@ -110,90 +112,94 @@ export default class EntryAbility extends UIAbility { ### 开发步骤 1. 创建应用子窗口。 + 通过`createSubWindow`接口创建应用子窗口。 2. 设置子窗口属性。 + 子窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置窗口背景色、亮度等属性。 3. 加载显示子窗口的具体内容。 + 通过`setUIContent`和`showWindow`接口加载显示子窗口的具体内容。 4. 销毁子窗口。 + 当不再需要某些子窗口时，可根据具体实现逻辑，使用`destroyWindow`接口销毁子窗口。 - - ```ts - import UIAbility from '@ohos.app.ability.UIAbility'; - - let windowStage_ = null; - let sub_windowClass = null; - export default class EntryAbility extends UIAbility { - showSubWindow() { - // 1.创建应用子窗口。 - windowStage_.createSubWindow("mySubWindow", (err, data) => { - if (err.code) { - console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err)); - return; - } - sub_windowClass = data; - console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); - // 2.子窗口创建成功后，设置子窗口的位置、大小及相关属性等。 - sub_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.'); - }); - sub_windowClass.resize(500, 500, (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.'); - }); - // 3.为子窗口加载对应的目标页面。 - sub_windowClass.setUIContent("pages/page3", (err) => { - if (err.code) { - console.error('Failed to load the content. Cause:' + JSON.stringify(err)); - return; - } - console.info('Succeeded in loading the content.'); - // 3.显示子窗口。 - sub_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.'); - }); - }); - }) - } - - destroySubWindow() { - // 4.销毁子窗口。当不再需要子窗口时，可根据具体实现逻辑，使用destroy对其进行销毁。 - sub_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.'); - }); - } - - onWindowStageCreate(windowStage) { - windowStage_ = windowStage; - // 开发者可以在适当的时机，如主窗口上按钮点击事件等，创建子窗口。并不一定需要在onWindowStageCreate调用，这里仅作展示 - this.showSubWindow(); - } - - onWindowStageDestroy() { - // 开发者可以在适当的时机，如子窗口上点击关闭按钮等，销毁子窗口。并不一定需要在onWindowStageDestroy调用，这里仅作展示 - this.destroySubWindow(); - } - }; - ``` +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +let windowStage_ = null; +let sub_windowClass = null; + +export default class EntryAbility extends UIAbility { + showSubWindow() { + // 1.创建应用子窗口。 + windowStage_.createSubWindow("mySubWindow", (err, data) => { + if (err.code) { + console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err)); + return; + } + sub_windowClass = data; + console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); + // 2.子窗口创建成功后，设置子窗口的位置、大小及相关属性等。 + sub_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.'); + }); + sub_windowClass.resize(500, 500, (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.'); + }); + // 3.为子窗口加载对应的目标页面。 + sub_windowClass.setUIContent("pages/page3", (err) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content.'); + // 3.显示子窗口。 + sub_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.'); + }); + }); + }) + } + + destroySubWindow() { + // 4.销毁子窗口。当不再需要子窗口时，可根据具体实现逻辑，使用destroy对其进行销毁。 + sub_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.'); + }); + } + + onWindowStageCreate(windowStage) { + windowStage_ = windowStage; + // 开发者可以在适当的时机，如主窗口上按钮点击事件等，创建子窗口。并不一定需要在onWindowStageCreate调用，这里仅作展示 + this.showSubWindow(); + } + + onWindowStageDestroy() { + // 开发者可以在适当的时机，如子窗口上点击关闭按钮等，销毁子窗口。并不一定需要在onWindowStageDestroy调用，这里仅作展示 + this.destroySubWindow(); + } +}; +``` ## 体验窗口沉浸式能力 @@ -203,75 +209,78 @@ export default class EntryAbility extends UIAbility { ### 开发步骤 1. 获取应用主窗口。 + 通过`getMainWindow`接口获取应用主窗口。 2. 实现沉浸式效果。有以下两种方式： + - 方式一：调用`setWindowSystemBarEnable`接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。 + - 方式二：调用`setWindowLayoutFullScreen`接口，设置应用主窗口为全屏布局；然后调用`setWindowSystemBarProperties`接口，设置导航栏、状态栏的透明度、背景/文字颜色以及高亮图标等属性，使之保持与主窗口显示协调一致，从而达到沉浸式效果。 3. 加载显示沉浸式窗口的具体内容。 + 通过`loadContent`接口加载沉浸式窗口的具体内容。 - - ```ts - import UIAbility from '@ohos.app.ability.UIAbility'; - - export default class EntryAbility extends UIAbility { - onWindowStageCreate(windowStage) { - // 1.获取应用主窗口。 - let windowClass = null; - windowStage.getMainWindow((err, data) => { - if (err.code) { - console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); - return; - } - windowClass = data; - console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); - - // 2.实现沉浸式效果。方式一：设置导航栏、状态栏不显示。 - let names = []; - windowClass.setWindowSystemBarEnable(names, (err) => { - if (err.code) { - console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); - return; - } - console.info('Succeeded in setting the system bar to be visible.'); - }); - // 2.实现沉浸式效果。方式二：设置窗口为全屏布局，配合设置导航栏、状态栏的透明度、背景/文字颜色及高亮图标等属性，与主窗口显示保持协调一致。 - let isLayoutFullScreen = true; - 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.'); - }); - let sysBarProps = { - statusBarColor: '#ff00ff', - navigationBarColor: '#00ff00', - // 以下两个属性从API Version 8开始支持 - statusBarContentColor: '#ffffff', - navigationBarContentColor: '#ffffff' - }; - windowClass.setWindowSystemBarProperties(sysBarProps, (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.'); - }); - }) - // 3.为沉浸式窗口加载对应的目标页面。 - windowStage.loadContent("pages/page2", (err) => { - if (err.code) { - console.error('Failed to load the content. Cause:' + JSON.stringify(err)); - return; - } - console.info('Succeeded in loading the content.'); - }); - } - }; - ``` +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +export default class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage) { + // 1.获取应用主窗口。 + let windowClass = null; + windowStage.getMainWindow((err, data) => { + if (err.code) { + console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); + return; + } + windowClass = data; + console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); + + // 2.实现沉浸式效果。方式一：设置导航栏、状态栏不显示。 + let names = []; + windowClass.setWindowSystemBarEnable(names, (err) => { + if (err.code) { + console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the system bar to be visible.'); + }); + // 2.实现沉浸式效果。方式二：设置窗口为全屏布局，配合设置导航栏、状态栏的透明度、背景/文字颜色及高亮图标等属性，与主窗口显示保持协调一致。 + let isLayoutFullScreen = true; + 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.'); + }); + let sysBarProps = { + statusBarColor: '#ff00ff', + navigationBarColor: '#00ff00', + // 以下两个属性从API Version 8开始支持 + statusBarContentColor: '#ffffff', + navigationBarContentColor: '#ffffff' + }; + windowClass.setWindowSystemBarProperties(sysBarProps, (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.'); + }); + }) + // 3.为沉浸式窗口加载对应的目标页面。 + windowStage.loadContent("pages/page2", (err) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content.'); + }); + } +}; +``` ## 设置悬浮窗 @@ -281,6 +290,7 @@ export default class EntryAbility extends UIAbility { ### 开发步骤 1. 申请权限。 + 创建`WindowType.TYPE_FLOAT`即悬浮窗类型的窗口，需要在`module.json5`文件的`requestPermissions`对象中配置`ohos.permission.SYSTEM_FLOAT_WINDOW`权限。更多配置信息详见[module.json5配置文件](../quick-start/module-configuration-file.md)。 > **说明：** @@ -306,81 +316,87 @@ export default class EntryAbility extends UIAbility { ``` 2. 创建悬浮窗。 + 通过`window.createWindow`接口创建悬浮窗类型的窗口。 3. 对悬浮窗进行属性设置等操作。 + 悬浮窗窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置悬浮窗背景色、亮度等属性。 4. 加载显示悬浮窗的具体内容。 + 通过`setUIContent`和`showWindow`接口加载显示悬浮窗的具体内容。 5. 销毁悬浮窗。 当不再需要悬浮窗时，可根据具体实现逻辑，使用`destroyWindow`接口销毁悬浮窗。 - ```ts - import UIAbility from '@ohos.app.ability.UIAbility'; - import window from '@ohos.window'; - - export default class EntryAbility extends UIAbility { - onWindowStageCreate(windowStage) { - // 2. 创建悬浮窗。 - let windowClass = null; - let config = {name: "floatWindow", windowType: window.WindowType.TYPE_FLOAT, ctx: this.context}; - window.createWindow(config, (err, data) => { - if (err.code) { - console.error('Failed to create the floatWindow. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Succeeded in creating the floatWindow. Data: ' + JSON.stringify(data)); - windowClass = data; - // 3.悬浮窗窗口创建成功后，设置悬浮窗的位置、大小及相关属性等。 - 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.'); - }); - windowClass.resize(500, 500, (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.'); - }); - // 4.为悬浮窗加载对应的目标页面。 - windowClass.setUIContent("pages/page4", (err) => { - if (err.code) { - console.error('Failed to load the content. Cause:' + JSON.stringify(err)); - return; - } - console.info('Succeeded in loading the content.'); - // 4.显示悬浮窗。 - 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.'); - }); - }); - //5.销毁悬浮窗。当不再需要悬浮窗时，可根据具体实现逻辑，使用destroy对其进行销毁。 - 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.'); - }); - }); - } - }; - ``` +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; +import window from '@ohos.window'; + +export default class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage) { + // 2. 创建悬浮窗。 + let windowClass = null; + let config = { + name: "floatWindow", windowType: window.WindowType.TYPE_FLOAT, ctx: this.context + }; + window.createWindow(config, (err, data) => { + if (err.code) { + console.error('Failed to create the floatWindow. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in creating the floatWindow. Data: ' + JSON.stringify(data)); + windowClass = data; + // 3.悬浮窗窗口创建成功后，设置悬浮窗的位置、大小及相关属性等。 + 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.'); + }); + windowClass.resize(500, 500, (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.'); + }); + // 4.为悬浮窗加载对应的目标页面。 + windowClass.setUIContent("pages/page4", (err) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content.'); + // 4.显示悬浮窗。 + 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.'); + }); + }); + //5.销毁悬浮窗。当不再需要悬浮窗时，可根据具体实现逻辑，使用destroy对其进行销毁。 + 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.'); + }); + }); + } +}; +``` + ## 相关实例 针对window开发（Stage模型），有以下相关实例可供参考： - [`Window`：一多设置典型页面（Settings）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Beta1/code/SuperFeature/MultiDeviceAppDev/Settings) -- [`WindowManage`：窗口管理（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Beta1/code/BasicFeature/WindowManagement/WindowManage) +- [`WindowManage`：窗口管理（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Beta1/code/BasicFeature/WindowManagement/WindowManage) \ No newline at end of file