HarmonyOS 鸿蒙Next中如何限制自由窗口的尺寸调节范围

HarmonyOS 鸿蒙Next中如何限制自由窗口的尺寸调节范围 如何限制自由窗口的尺寸调节范围

3 回复

限制自由窗口的尺寸调节范围可以通过以下两种主要方式实现：

1. 在应用配置文件中静态配置

在应用的 module.json5 配置文件中的 abilities 标签下，通过设置以下字段来限制该 Ability 支持的窗口尺寸和宽高比范围：

字段名 数据类型 描述 单位
minWindowWidth 数值 标识该 Ability 支持的最小窗口宽度 vp
minWindowHeight 数值 标识该 Ability 支持的最小窗口高度 vp
maxWindowWidth 数值 标识该 Ability 支持的最大窗口宽度 vp
maxWindowHeight 数值 标识该 Ability 支持的最大窗口高度 vp
minWindowRatio 数值 标识该 Ability 支持的最小宽高比 -
maxWindowRatio 数值 标识该 Ability 支持的最大宽高比 - 
{
  "module": {
    "abilities": [
      {
        "minWindowWidth": 320,
        "minWindowHeight": 240,
        "maxWindowWidth": 1440,
        "maxWindowHeight": 900,
        "minWindowRatio": 0.5,
        "maxWindowRatio": 2
      }
    ]
  }
}

2. 在运行时通过 API 动态设置

在应用运行过程中，可以通过 Window 相关的 API 动态获取和设置窗口的尺寸限制。

  • 获取当前窗口尺寸限制：使用 getWindowLimits() 接口。
  • 设置当前窗口尺寸限制：使用 setWindowLimits(windowLimits: WindowLimits) 接口。该接口设置的尺寸限制将与系统默认限制取交集后生效。
    • 从 API version 15 开始，针对 2in1 设备，提供了 setWindowLimits(windowLimits: WindowLimits, isForcible: boolean) 接口。当 isForcible 设置为 true 时，窗口宽高最小值以系统限制值和 40vp 两者中的低数值为准。

WindowLimits 参数说明：

字段名 数据类型 描述 单位
minWidth number 窗口的最小宽度。 px
minHeight number 窗口的最小高度。 px
maxWidth number 窗口的最大宽度。 px
maxHeight number 窗口的最大高度。 px

代码示例：

import { BusinessError } from '@kit.BasicServicesKit';
try {
  let windowLimits: window.WindowLimits = {
    maxWidth: 1500,
    maxHeight: 1000,
    minWidth: 500,
    minHeight: 400
  };
  let promise = windowClass.setWindowLimits(windowLimits);
  promise.then((data) => {
    console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`);
}

3. 其他相关接口的约束

当使用 resize()、resizeAsync() 等接口改变窗口大小时，所设置的尺寸也会受到上述 WindowLimits 的约束：

  • 若设置的尺寸小于最小限值，则最小限值生效。
  • 若设置的尺寸大于最大限值，则最大限值生效。

总结

限制自由窗口尺寸调节范围的核心方法是：

  1. 静态配置：在 module.json5 中通过 abilities 的 minWindowWidth、maxWindowWidth 等字段进行声明式配置。
  2. 动态设置：在运行时通过 setWindowLimits() API 进行编程式设置，并与系统限制共同作用。

相关文档：【官方指南_如何限制自由窗窗口尺寸】

更多关于HarmonyOS 鸿蒙Next中如何限制自由窗口的尺寸调节范围的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


在HarmonyOS Next中，可以通过设置窗口的minWindowWidth、minWindowHeight、maxWindowWidth和maxWindowHeight属性来限制自由窗口的尺寸调节范围。这些属性在UIAbility或AbilityStage的onWindowStageCreate回调中配置，作用于WindowStage对象。

在HarmonyOS Next中，可以通过设置窗口的WindowSizeLimits属性来精确控制自由窗口的尺寸调节范围。具体方法如下：

  1. 获取窗口对象：首先获取需要设置的自由窗口的Window对象。

  2. 设置尺寸限制：使用Window对象的setWindowSizeLimits方法，传入WindowSizeLimits配置对象。该对象包含以下关键属性：

    • minWidth：最小宽度（单位：vp）
    • maxWidth：最大宽度
    • minHeight：最小高度
    • maxHeight：最大高度

  3. 示例代码：

import { window } from '@kit.ArkUI';

let windowClass = window.getLastWindow(this.context);
let limits = {
  minWidth: 300,  // 最小宽度300vp
  maxWidth: 800,  // 最大宽度800vp  
  minHeight: 400, // 最小高度400vp
  maxHeight: 600  // 最大高度600vp
};
windowClass.setWindowSizeLimits(limits);
  1. 注意事项：
    • 尺寸单位使用虚拟像素（vp），系统会自动适配不同屏幕密度
    • 设置后用户拖拽窗口边缘时，尺寸会被限制在指定范围内
    • 如需禁用尺寸调节，可将最小和最大值设为相同

此方法适用于需要固定窗口尺寸或限制窗口缩放范围的场景，如视频播放器、工具栏等特定功能的自由窗口。

回到顶部