文档管理中心
指南应用框架ArkUI(方舟UI框架)窗口管理窗口类型子窗口开发指导

子窗口开发指导

场景介绍

子窗口是最基础的辅助窗口类型,用于提供辅助性的功能或展示额外的信息。

说明
  • 在非自由窗口状态下,子窗只会在应用主窗口范围显示。
  • 自由窗口状态下,子窗可超出应用主窗口范围显示。

开发步骤

  1. 通过createSubWindow()接口或createSubWindowWithOptions()创建应用子窗口。子窗口创建后默认为沉浸式布局

    API版本26.0.0开始,支持在使用createSubWindowWithOptions()创建子窗时设置SubWindowOptions中的zLevelAboveParentLoosened为true,此时创建的子窗称为独立子窗。

    独立子窗在自由窗口状态下,不跟随主窗前后台的切换,仅跟随主窗一起销毁,独立子窗与主窗可通过点击调整层级。

    收起
    自动换行
    深色代码主题
    复制
    1. let windowStage_: window.WindowStage | undefined = undefined;
    2. let subWindowClass: window.Window | undefined = undefined;
    3. // ...
    4. // 获取windowStage
    5. windowStage_ = AppStorage.get('windowStage');
    6. // 创建应用子窗口。
    7. if (windowStage_ == null) {
    8. console.error('Failed to create the subwindow. Cause: windowStage_ is null');
    9. } else {
    10. // 1.使用createSubWindow接口创建子窗
    11. windowStage_.createSubWindow('SubWindow', (err, data) => {
    12. if (err?.code) {
    13. console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
    14. }
    15. subWindowClass = data;
    16. if (!subWindowClass) {
    17. console.error('sub_windowClass is null');
    18. return;
    19. }
    20. console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
    21. // ...
    22. })
    23. }
    收起
    自动换行
    深色代码主题
    复制
    1. let independentWindowClass: window.Window | undefined = undefined;
    2. // ...
    3. // 获取windowStage
    4. windowStage_ = AppStorage.get('windowStage');
    5. // 1.创建独立子窗口。
    6. // ...
    7. let options : window.SubWindowOptions = {
    8. title: 'IndependentSubWindow',
    9. decorEnabled: true,
    10. zLevelAboveParentLoosened: true // 独立子窗需将zLevelAboveParentLoosened置为true
    11. };
    12. let promise = windowStage_.createSubWindowWithOptions('IndependentSubWindow', options);
    13. promise.then((data: window.Window | undefined) => {
    14. independentWindowClass = data;
    15. if (!independentWindowClass) {
    16. console.error('independent_sub_windowClass is null');
    17. return;
    18. }
    19. console.info(`Succeeded in creating the subwindow. Data: ${JSON.stringify(data)}`);
    20. // ...
    21. });
  2. 设置子窗口属性。

    • 子窗口创建成功后,可以改变其大小、位置等,还可以根据应用需要设置窗口背景色、亮度等属性。

    • 在调用showWindow()之前,建议设置子窗口的大小和位置。

    • 如果没有设置子窗口的大小,调用showWindow()后有如下表现:

      • 自由窗口状态下,默认子窗口大小为当前物理屏幕的大小。

      • 自由窗口状态下,默认子窗口大小为主窗口大小。

    此处以设置独立子窗的属性为例。示例代码如下:

    收起
    自动换行
    深色代码主题
    复制
    1. // 2.子窗口创建成功后,设置子窗口的位置、大小及相关属性等。
    2. independentWindowClass.moveWindowTo(100, 100, (err) => {
    3. if (err?.code) {
    4. console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
    5. return;
    6. }
    7. console.info('Succeeded in moving the window.');
    8. if (!independentWindowClass) {
    9. console.error('independent_windowClass is null');
    10. return;
    11. }
    12. independentWindowClass.resize(1000, 500, (err) => {
    13. if (err?.code) {
    14. console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`);
    15. return;
    16. }
    17. console.info('Succeeded in changing the window size.');
    18. });
    19. });
  3. 加载显示子窗口的具体内容。

    通过setUIContent()showWindow()接口加载和显示子窗口的具体内容。

    此处以加载显示独立子窗的具体内容为例。示例代码如下:

    收起
    自动换行
    深色代码主题
    复制
    1. // 3.为子窗口加载对应的目标页面。
    2. independentWindowClass.setUIContent('pages/IndependentSubWindow', (err) => {
    3. if (err?.code) {
    4. console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
    5. return;
    6. }
    7. console.info('Succeeded in loading the content.');
    8. if (!independentWindowClass) {
    9. console.error('independent_windowClass is null');
    10. return;
    11. }
    12. // 显示子窗口。
    13. independentWindowClass.showWindow((err) => {
    14. if (err?.code) {
    15. console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
    16. return;
    17. }
    18. console.info('Succeeded in showing the window.');
    19. });
    20. });
  4. 销毁子窗口。

    当不再需要某些子窗口时,可根据具体实现逻辑,使用destroyWindow()接口销毁子窗口。

    此处以销毁独立子窗为例。示例代码如下:

    收起
    自动换行
    深色代码主题
    复制
    1. // 4.销毁子窗口。当不再需要子窗口时,可根据具体实现逻辑,使用destroy对其进行销毁。
    2. independentWindowClass.destroyWindow((err) => {
    3. if (err?.code) {
    4. console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`);
    5. return;
    6. }
    7. console.info('Succeeded in destroying the window.');
    8. });
在 指南 中进行搜索
请输入您想要搜索的关键词