HarmonyOS鸿蒙Next中Flutter框架多设备开发指导-自由多窗场景

HarmonyOS鸿蒙Next中Flutter框架多设备开发指导-自由多窗场景

1.1 场景概述

在移动应用开发中，不同设备的屏幕形态各异，例如刘海屏、全面屏、折叠屏等，系统状态栏、导航栏、软键盘等元素亦会占据屏幕空间。分屏、悬浮窗、折叠开合及个人电脑多窗环境下，同一应用窗口可能在极窄到极宽之间反复变化；若标签位置、内容区边距与网格列数仍按单窗全屏写死，易出现底栏挡正文、侧栏出现后网格仍按全宽计算等问题。本文将详细介绍宽档位订阅、布局测量与列模板联动、多窗下手势与坐标校正等方法，以及实现原理与具体场景案例。

1.1.1 使用场景

多窗用户希望窗口拉窄时列表仍可读、拉宽时能多列展示，底栏或侧栏切换后正文区域自动留出对应占位，不被遮挡。下面是不同横向断点下标签形态与网格列数的示意。

自由多窗适配验证（多窗环境下的界面自适应），指的是带导航标签的主从布局能够根据当前宽档位与实测窗口宽度，自动切换底栏/侧栏形态并重算网格列模板、单元宽度与内边距，以提供任意窗宽下内容清晰、可操作区域合理的布局方法。

横向断点	sm	md	lg	xl
展示逻辑	底栏标签（高约 76）；内容区底部留白 76；视频区非紧凑、不按侧栏扣宽；网格列数随宽度断点（多为 2 列）	同左；宽度断点多为中等，网格仍多为 2 列	左侧竖标签（宽约 96）；视频区紧凑、固定 3 列；有效宽度为窗口宽减 96	同左；断点可能为特大宽，但因左侧标签优先，列模板仍为 3 列
展示布局

1.1.2 常见问题

未结合多窗与实测布局做适配时，易出现：

• 窗口变窄仍按大屏列数排布，卡片被压扁或折行错乱（未按逻辑宽度重算列数与单元格像素宽度）
• 底栏标签与正文重叠，或已出现左侧标签仍按全宽算网格（未区分模式设置底部留白或有效宽度减标签宽）
• 仅依赖一次读取的窗口尺寸，分屏或鸿蒙电脑上宽高滞后（未同时使用布局回调与尺寸变化监听）
• 列表滚动与单格拖拽争手势，拖拽预览相对窗口偏移（未设置手势位移阈值、未在窗口坐标系中测量并减去容器偏移）

1.1.3 多设备适配

• 适配点 1：订阅宽档位变化以切换底栏或左侧标签；根视图在布局完成时更新宽高并刷新窗口信息；切换标签时用布局动画与列表的程序化滚动对齐当前页（列表本身关闭手指滑动，由标签按钮驱动）。

图 1-1：手机竖屏下本页效果（建议含底栏或侧栏标签与内容区关系）。

图 1-2：手机横屏下同一页面，体现宽度变化后的标签位置或内容区排布。

• 适配点 2：网格按宽度断点取列模板、间距与内边距；在容器宽度确定后计算每个格子的像素宽度；拖拽时用窗口测量更新格子位置，浮层绝对定位并随手势平移。

图 2-1：电脑全屏（或应用占满桌面）下网格与可选拖拽效果。

图 2-2：PC 下网格项拖拽与浮层随手势平移示意。

1.2 开发指导

1.2.1 Flutter开发

1.2.1.1 关键能力

1）flutter中需要使用断点判断不同机型，根据不同的机型显示UI。

2）自由多窗沉浸式依赖原生接口setWindowDecorVisible和setWindowTitleButtonVisible实现。

1.2.1.2 指导案例

自由多窗开发主要涉及三个点

1）多设备类型布局规则适配实现：使用断点判断不同的机型，显示不同的UI；

2）应用响应窗口变化：通过系统接口监听当前是否是自由多窗状态。

具体实现：

v2： API22+ isInFreeWindowMode

v1: 当前可以使用"window_pcmode_switch_status"字段结合settings.registerKeyObserver()接口和settings.getValue()接口来获取并监听当前是否切换至自由多窗模式。

3）自由多窗沉浸式适配：自由多窗无法直接通过setWindowLayoutFullScreen接口实现沉浸式，而是通过setWindowDecorVisible和setWindowTitleButtonVisible分别隐藏状态栏和三键。

4）flutter调用系统接口，需要使用channel；

1.2.1.3 示例代码

1）断点逻辑：可以使用三方库 hadss_adaptive_layout，或者根据规格表自行封装断点。

final media = MediaQuery.of(context);
final widthBp = getWidthBreakpoint(media.size.width);
final mainWindowInfo = WindowInfo(widthBp: widthBp,avoidSystemInsets: media.padding);
final isLarge = widthBp == WidthBreakpoint.widthLg || widthBp == WidthBreakpoint.widthXl;
if (isLarge) {
  ...//大屏机型逻辑
}else{
  ...//小屏机型逻辑
}

2）通过系统接口监听当前是否是自由多窗状态。此处只列出arkts代码，dart调用arkts方法请参考channel；

export function observePcMode() {
  if (canIUse('SystemCapability.Applications.Settings.Core')) {
    settings.registerKeyObserver(getContext(), 'window_pcmode_switch_status', settings.domainName.USER_PROPERTY,
      () => {
        getPcMode()
      }
    )
  }
}


export function getPcMode() {
  if (canIUse('SystemCapability.Applications.Settings.Core')) {
    settings.getValue(getContext(), 'window_pcmode_switch_status', settings.domainName.USER_PROPERTY
    ).then((data) => {
      AppStorage.setOrCreate('isPCMode', data === 'true');
    })
  }
}

3）通过系统接口实现自由多窗沉浸式适配。此处只列出arkts代码，dart调用arkts方法请参考channel；

function changeRight(context: Context | undefined, max: boolean, min: boolean, isClose: boolean) {
  if (!context) {
    return;
  }
  let uiContext = context as common.UIAbilityContext;
  let mainWindow: window.Window | undefined = undefined;
  uiContext.windowStage.getMainWindow().then(
    data => {
      mainWindow = data;
      // setWindowDecorVisible用于隐藏图标、名称与状态栏
      mainWindow.setWindowDecorVisible(max);
      // setWindowTitleButtonVisible接口，隐藏主窗标题栏最大化、最小化、关闭按钮
      mainWindow.setWindowTitleButtonVisible(max, min, isClose);
    }
  ).catch((err: BusinessError) => {
    if (err.code) {
      console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
    }
  });
}

自由多窗的Sample示例代码地址：flutter 自由多窗，开发者可以通过该地址查看完整的示例代码，并根据自己的需求进行修改和扩展。