目录

窗口布局

场景介绍

窗口布局是指对窗口的位置、大小属性进行设置和管理的能力。通过窗口布局能力，开发者可以灵活控制应用窗口在屏幕上的显示形态，实现多样化的界面呈现效果。

窗口布局主要包含以下能力：

合理运用窗口布局能力，可以帮助开发者：

管理窗口尺寸限制或宽高比限制

通过管理窗口尺寸限制或宽高比限制，可以约束窗口的可调整范围和显示比例，防止窗口过大或过小影响用户体验。

[h2]窗口尺寸限制

WindowLimits表示窗口的最小和最大尺寸限制，包含窗口的最小高度（minWindowHeight）、最大高度（maxWindowHeight）、最小宽度（minWindowWidth）、最大宽度（maxWindowWidth）。使用getWindowLimits()、getWindowLimitsVP()接口可以查询当前窗口的尺寸限制。

系统提供了多种配置窗口尺寸限制的方式，窗口尺寸限制的最终生效结果由以下配置取交集得到，优先级从高到低：

配置方式 优先级 单位 生效时机 使用场景

调用setWindowLimits()传入参数windowLimits

调用setWindowLimits()接口传入参数windowLimits、isForcible

 最高（运行时设置）

px或vp

（通过pixelUnit指定）

 窗口创建后动态生效 需要根据运行时状态动态调整窗口尺寸限制的场景，如根据内容自动适配、用户交互后调整等。
调用startAbility()接口时通过StartOptions设置 中（启动时设置） vp Ability启动时生效 需要在启动时指定窗口尺寸限制的场景，如拉起其他应用时指定其窗口大小范围。
通过module.json5配置文件中abilities标签配置 低（静态配置） vp 应用安装后生效 需要预设窗口尺寸限制的场景，作为默认配置供应用使用，对于当前UIAbility对应的主窗生效。
默认系统限制 低（系统默认） vp 应用安装后生效 应用不需要指定窗口尺寸限制，跟随系统默认限制（基于不同产品和窗口类型，系统默认限制存在差异）。

[h2]窗口内容宽高比限制

针对窗口宽高比限制，适用于以下典型场景：

目前支持应用调用以下相关接口设置窗口内容区域的宽高比限制。

接口 功能描述 适用场景 生效范围
setAspectRatio() 设置窗口内容布局（不含边框和标题栏等装饰）的比例，该比例参数默认持久化保存。 - 为同一应用下多个启动实例配置相同的内容宽高比。当同一应用的某个主窗口调用此接口设置宽高比生效后，后续打开的主窗口均会沿用该宽高比。 自由窗口状态下的主窗
setContentAspectRatio()

设置窗口内容布局（不含边框和标题栏等装饰）的比例。

窗口宽高会跟随窗口边框装饰尺寸或可见性变化而调整，并支持配置该比例参数是否持久化保存。

- 自定义主窗口标题栏尺寸及可见性

- 为单个主窗口单独设置宽高比

 自由窗口状态下的主窗

使用示例：

// Index.ets
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0000;
const TAG = 'IndexPage';

// ...
  /**
   步骤2：为主窗口设置指定宽高比例
   */
  private setWindowAspectRatioEnabled(enabled: boolean): void {
    const mainWindow = this.getMainWindow();
    if (!mainWindow) {
      this.resultText = '找不到主窗口';
      return;
    }
    if (enabled) {
      const ratio = 1.5;
      // 设置可布局内容宽高比限制
      mainWindow.setAspectRatio(ratio)
        .then(() => {
          AppStorage.setOrCreate('WINDOW_ASPECT_RATIO_ENABLED', enabled);
          this.resultText = '已开启比例限制';
        })
        .catch((err: Error) => {
          const businessError = err as BusinessError;
          this.resultText = `设置比例限制失败: ${JSON.stringify(businessError)}`;
          hilog.error(DOMAIN, TAG, `set aspect ratio failed: ${JSON.stringify(businessError)}`);
        });
    } else {
      // 取消可布局内容宽高比限制
      mainWindow.resetAspectRatio()
        .then(() => {
          AppStorage.setOrCreate('WINDOW_ASPECT_RATIO_ENABLED', enabled);
          this.resultText = '已关闭比例限制';
        })
        .catch((err: Error) => {
          const businessError = err as BusinessError;
          this.resultText = `重置比例限制失败: ${JSON.stringify(businessError)}`;
          hilog.error(DOMAIN, TAG, `reset aspect ratio failed: ${JSON.stringify(businessError)}`);
        });
    }
  }

调整窗口位置与大小

[h2]设置主窗口启动时的初始位置与大小

应用窗口可以设置启动时初始的位置与大小，可通过以下两种方式实现。

[h2]动态调整窗口位置与大小

窗口创建后，开发者可以通过接口动态调整窗口的位置与大小。

[h2]通过拖拽改变窗口的位置大小

目前提供了以下两种拖拽窗口的能力。

[h2]感知窗口位置与大小的变化

应用可以通过主动查询、注册事件监听、声明环境变量的方式来感知窗口位置和大小的变化，从而做出响应。

目前可通过以下相关接口查询、监听窗口位置与大小的变化：

接口 返回值类型 说明
on('windowSizeChange') Size 监听窗口大小变化，单位为px。
on('windowRectChange') RectChangeOptions 监听窗口矩形（窗口位置及窗口大小）变化，返回对应值及变化原因，单位为px。
on('rectChangeInGlobalDisplay') RectChangeOptions 监听窗口矩形（窗口位置及窗口大小）在全局坐标系中的变化，返回对应值及变化原因，单位为px。
getWindowProperties() WindowProperties

获取当前窗口的属性。其中窗口位置与大小相关的属性为：

windowRect：窗口的位置和大小，相对于当前屏幕坐标系。

drawableRect：窗口内的可绘制区域尺寸，其中左边界上边界相对于窗口左上顶点计算。globalDisplayRect：窗口的位置和大小，相对于全局坐标系。

应用还可以通过使用环境变量来感知窗口位置与大小的变化。环境变量是一种全局状态管理机制，在多设备开发的场景中，开发者可以使用@Env装饰器监听系统环境变量的改变，并根据系统环境变量来进行相应的场景判断，以减少不同设备间的适配逻辑和重复开发。详情请见@Env：环境变量。

环境变量允许组件感知并响应窗口尺寸的变化。当窗口大小发生变化时，声明并使用环境变量进行布局的组件可实现响应式布局效果。

环境变量名称 返回类型 说明
SystemProperties.WINDOW_SIZE window.SizeInVP 返回窗口尺寸，单位为vp。包含width和height属性。
SystemProperties.WINDOW_SIZE_PX window.Size 返回窗口尺寸，单位为px。包含width和height属性。