diff --git a/en/application-dev/reference/apis/js-apis-window.md b/en/application-dev/reference/apis/js-apis-window.md index d3eecc390d495e9d0fc1c40b2241b1edec805c8d..eb34c96a9852d8f183a791bb31764f5c5ab97a31 100644 --- a/en/application-dev/reference/apis/js-apis-window.md +++ b/en/application-dev/reference/apis/js-apis-window.md @@ -479,7 +479,7 @@ Obtains the top window of the current application. This API uses a promise to re on(type: 'systemBarTintChange', callback: Callback<SystemBarTintState>): void -Enables listening for the properties changes of the status bar and navigation bar. +Enables listening for properties changes of the status bar and navigation bar. This is a system API and cannot be called by third-party applications. @@ -490,7 +490,7 @@ This is a system API and cannot be called by third-party applications. | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **systemBarTintChange**, which indicates listening for properties changes of the status bar and navigation bar.| - | callback | Callback<[SystemBarTintState](#systembartintstate)> | Yes | Callback used to return the listened information. | + | callback | Callback<[SystemBarTintState](#systembartintstate)> | Yes | Callback used to return the information. | - Example @@ -516,7 +516,7 @@ This is a system API and cannot be called by third-party applications. | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **systemBarTintChange**, which indicates listening for properties changes of the status bar and navigation bar.| - | callback | Callback<[SystemBarTintState](#systembartintstate)> | No | Callback used to return the listened information. | + | callback | Callback<[SystemBarTintState](#systembartintstate)> | No | Callback used to return the information. | - Example @@ -934,7 +934,7 @@ Obtains the area where this window cannot be displayed, for example, the system | Name | Type | Mandatory| Description | | -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | - | type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area.**TYPE_SYSTEM** indicates the default area of the system. **TYPE_CUTOUT** indicates the notch.| + | type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. **TYPE_SYSTEM** indicates the default area of the system. **TYPE_CUTOUT** indicates the notch.| | callback | AsyncCallback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the area. | - Example @@ -962,7 +962,7 @@ Obtains the area where this window cannot be displayed, for example, the system | Name| Type | Mandatory| Description | | ------ | ------------------------------- | ---- | ------------------------------------------------------------ | - | type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area.**TYPE_SYSTEM** indicates the default area of the system. **TYPE_CUTOUT** indicates the notch.| + | type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. **TYPE_SYSTEM** indicates the default area of the system. **TYPE_CUTOUT** indicates the notch.| - Return value @@ -1251,7 +1251,7 @@ Loads content to this window. This API uses an asynchronous callback to return t | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | -------------------- | - | path | string | Yes | Path of the page to which the content will be loaded.| + | path | string | Yes | Path of the page from which the content will be loaded.| | callback | AsyncCallback<void> | Yes | Callback used to return the execution result. | - Example @@ -1278,7 +1278,7 @@ Loads content to this window. This API uses a promise to return the result. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | -------------------- | - | path | string | Yes | Path of the page to which the content will be loaded.| + | path | string | Yes | Path of the page from which the content will be loaded.| - Return value @@ -1361,7 +1361,7 @@ Enables listening for window size changes. | Name | Type | Mandatory| Description | | -------- | ----------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **windowSizeChange**, which indicates listening for window size changes.| - | callback | Callback<[Size](#size)> | Yes | Callback used to return the listened information. | + | callback | Callback<[Size](#size)> | Yes | Callback used to return the information. | - Example @@ -1384,8 +1384,8 @@ Disables listening for window size changes. | Name | Type | Mandatory| Description | | -------- | ----------------------------- | ---- | ------------------------------------------------------------ | - | type | string | Yes | Listening type.
Set it to **windowSizeChange7+**, which indicates listening for window size changes.| - | callback | Callback<[Size](#size)> | No | Callback used to return the listened information. | + | type | string | Yes | Listening type.
Set it to **windowSizeChange**, which indicates listening for window size changes.| + | callback | Callback<[Size](#size)> | No | Callback used to return the information. | - Example @@ -1407,7 +1407,7 @@ Enables listening for changes to the area where the window cannot be displayed. | Name | Type | Mandatory| Description | | -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **systemAvoidAreaChange**, which indicates listening for changes to the area where the window cannot be displayed.| - | callback | Callback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the listened information. | + | callback | Callback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the information. | - Example @@ -1431,7 +1431,7 @@ Disables listening for changes to the area where the window cannot be displayed. | Name | Type | Mandatory| Description | | -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **systemAvoidAreaChange**, which indicates listening for changes to the area where the window cannot be displayed.| - | callback | Callback<[AvoidArea](#avoidarea)> | No | Callback used to return the listened information. | + | callback | Callback<[AvoidArea](#avoidarea)> | No | Callback used to return the information. | - Example @@ -1455,7 +1455,7 @@ This API is defined but not implemented in OpenHarmony 3.1 Release. It will be a | Name | Type | Mandatory| Description | | -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **keyboardHeightChange**, which indicates listening for keyboard height changes.| - | callback | Callback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the listened information. | + | callback | Callback<number> | Yes | Callback used to return the information. | - Example @@ -1481,7 +1481,7 @@ This API is defined but not implemented in OpenHarmony 3.1 Release. It will be a | Name | Type | Mandatory| Description | | -------- | ---------------------- | ---- | ------------------------------------------------------------ | | type | string | Yes | Listening type.
Set it to **keyboardHeightChange**, which indicates listening for keyboard height changes.| - | callback | Callback<number> | No | Callback used to return the listened information. | + | callback | Callback<number> | No | Callback used to return the information. | - Example @@ -2160,4 +2160,301 @@ This API is defined but not implemented in OpenHarmony 3.1 Release. It will be a }); ``` -### +## WindowStageEventType9+ + +Describes the lifecycle of a window stage. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Default Value| Description | +| ---------- | ------ | -------- | +| FOREGROUND | 1 | The window stage is running in the foreground.| +| ACTIVE | 2 | The window stage gains focus.| +| INACTIVE | 3 | The window stage loses focus.| +| BACKGROUND | 4 | The window stage is running in the background.| + +## WindowStage9+ + +Before calling any of the following APIs, you must use `[onWindowStageCreate()](js-apis-application-ability.md#abilityonwindowstagecreate)` to create a **WindowStage** instance. + +### getMainWindow9+ + +getMainWindow(): Promise<Window> + +Obtains the main window of this window stage. This API uses a promise to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +- Return value + + | Type | Description | + | -------------------------------- | ---------------------------------------------------------- | + | Promise<[Window](#window)> | Promise used to return the main window.| + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var windowClass = null; + let promise = windowStage.getMainWindow(); + promise.then((data)=> { + windowClass = data; + console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)) + }).catch((err)=>{ + console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); + }); + } + } + ``` + +### getMainWindow9+ + +getMainWindow(callback: AsyncCallback<Window>): void + +Obtains the main window of this window stage. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | -------------------------------------- | ---- | --------------------------------------- | + | callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window.| + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var 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)); + }); + } + } + ``` + +### createSubWindow9+ + +createSubWindow(name: string): Promise<Window> + +Creates a subwindow for this window stage. This API uses a promise to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core +- Parameters + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | -------------- | + | name | String | Yes | Name of the subwindow.| +- Return value + + | Type | Description | + | -------------------------------- | ------------------------------------------------- | + | Promise<[Window](#window)> | Promise used to return the subwindow created.| +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var windowClass = null; + let promise = windowStage.createSubWindow("mySubWindow"); + promise.then((data)=> { + windowClass = data; + console.info('Succeeded in create sub window. Data: ' + JSON.stringify(data)) + }).catch((err)=>{ + console.error('Failed to create sub window. Cause: ' + JSON.stringify(err)); + }) + } + } + ``` + +### createSubWindow9+ + +createSubWindow(name: string, callback: AsyncCallback<Window>): void + +Creates a subwindow for this window stage. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | -------------------------------------- | ---- | ------------------------------ | + | name | String | Yes | Name of the subwindow. | + | callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.| + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var windowClass = null; + windowStage.createSubWindow("mySubWindow", (err, data) => { + if (err.code) { + console.error('Failed to create sub window. Cause: ' + JSON.stringify(err)); + return; + } + windowClass = data; + console.info('Succeeded in create sub window. Data: ' + JSON.stringify(data)); + windowClass.resetSize(500, 1000); + }); + } + } + ``` + +### getSubWindow9+ + +getSubWindow(): Promise<Array<Window>> + +Obtains all the subwindows of this window stage. This API uses a promise to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core +- Return value + + | Type | Description | + | --------------------------------------------- | ------------------------------------------------------------ | + | Promise<Array<[Window](#window)>> | Promise used to return all the subwindows.| + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var windowClass = null; + let promise = windowStage.getSubWindow(); + promise.then((data)=> { + windowClass = data; + console.info('Succeeded in obtaining the sub window. Data: ' + JSON.stringify(data)) + }).catch((err)=>{ + console.error('Failed to obtain the sub window. Cause: ' + JSON.stringify(err)); + }) + } + } + ``` + +### getSubWindow9+ + +getSubWindow(callback: AsyncCallback<Array<Window>>): void + +Obtains all the subwindows of this window stage. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | --------------------------------------------------- | ---- | ------------------------------------------- | + | callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the subwindows.| + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var windowClass = null; + windowStage.getSubWindow((err, data) => { + if (err.code) { + console.error('Failed to obtain the sub window. Cause: ' + JSON.stringify(err)); + return; + } + windowClass = data; + console.info('Succeeded in obtaining the sub window. Data: ' + JSON.stringify(data)); + }); + } + } + ``` + +### loadContent9+ + +loadContent(path: string, callback: AsyncCallback<void>): void + +Loads content to this window stage. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Coretype with the value 'windowSizeChange' + +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | ------------------------- | ---- | -------------------- | + | path | string | Yes | Path of the page from which the content will be loaded.| + | callback | AsyncCallback<void> | Yes | Callback used to return the execution result. | + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + windowStage.loadContent("pages/page2", (err, data) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content. Data: ' + JSON.stringify(data)) + }); + } + } + ``` +### on('windowStageEvent')9+ + +on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void + +Enables listening for window stage lifecycle changes. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | + | type | string | Yes | Listening type.
Set it to **windowStageEvent**, which indicates listening for window stage lifecycle changes.| + | callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the information. | + +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var type = 'windowStageEvent'; + windowStage.on(type, (data) => { + console.info('Succeeded in enabling the listener for window stage event changes. Data: ' + JSON.stringify(data)); + }); + } + } + ``` + +### off('windowStageEvent')9+ + +off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void + +Disables listening for window stage lifecycle changes. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core +- Parameters + + | Name | Type | Mandatory| Description | + | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | + | type | string | Yes | Listening type.
Set it to **windowStageEvent**, which indicates listening for window stage lifecycle changes.| + | callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | No | Callback used to return the information. | +- Example + + ``` + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + var type = 'windowStageEvent'; + windowStage.off(type); + } + } + ```