HarmonyOS 7.0 API 26 ContainerReader 实战：自由窗口拖拽时如何减少无效重建

在鸿蒙电脑或平板的自由窗口里，用户可以一直拖动窗口边缘。页面如果把每一次窗口尺寸变化都写进顶层状态，常见结果是：侧栏、标题、列表、弹窗一起重新计算，窗口越拖越卡；更麻烦的是，嵌套组件明明只剩 600vp 宽，却仍然按整个窗口 1100vp 的断点排成三栏。

这篇文章只处理一个问题：**可复用组件应该根据谁的宽度切布局？**

先把能力边界说清楚

HarmonyOS 7.0 的 API 26 新增了 ContainerReader。它读取的是组件容器自己的尺寸和断点，不是物理屏幕宽度，也不是整个应用窗口宽度。这个差别在自由窗口、Navigation 分栏、卡片嵌套场景里非常关键。

官方文档在 2026-08-29 更新了 ContainerReader 说明，几个容易漏掉的约束是：

• size 和 widthBreakpoint 必须使用状态变量，并通过 !! 做双向绑定；
• 容器尺寸由父组件和自身布局确定，不能反过来依赖子组件撑开；
• breakpointConfig 的 width 数组必须单调递增，单位是 vp；
• 宽度断点数组最多配置 4 个阈值，对应最多 5 个区间；
• ContainerReader 从 API 26 开始提供，低版本不能直接走这条实现。

判断对象	适合解决的问题	容易踩的坑
屏幕宽度	设备大类、横竖屏粗分	自由窗口缩小后仍把电脑当大屏
窗口宽度	页面级单栏/双栏切换	组件放进侧栏后宽度判断仍然偏大
容器宽度	卡片、面板、Grid 等局部布局	父容器没有明确尺寸时读数不稳定

我的选择很直接：页面骨架可以看窗口，真正需要复用的卡片和面板看容器。两层判断各管一层，不把所有变化都塞进页面根节点。

问题是怎样发生的

下面这个写法看起来没问题：窗口宽度大于 900vp 就显示三栏，否则显示一栏。但当左侧导航占掉 280vp、右侧检查器再占掉 320vp 时，中间内容区可能只剩 620vp。此时窗口仍然大于 900vp，中间组件却已经装不下三栏。

连续拖动时，windowSizeChange 还会密集触发。如果回调里同时计算列数、读取持久化配置、刷新数据源，布局抖动和掉帧就会一起出现。

可以用三步复现：

1. 在鸿蒙电脑自由窗口中打开一个“左侧导航 + 中间列表 + 右侧详情”的页面；

2. 把窗口从 1280vp 连续缩小到 720vp，再来回拖过 900vp；

3. 记录中间列表实际宽度、列数切换次数和主线程耗时。

错误信号通常有三个：列宽低于设计下限；断点附近反复重排；窗口回调里出现和布局无关的 IO 或数据请求。

案例一：固定侧栏后的内容区仍按窗口宽度排版

先把响应式逻辑收进内容组件。页面只负责分配空间，组件自己根据容器断点选择单栏、双栏或三栏。

import { ContainerReader, Size } from '@kit.ArkUI';

@Component
struct AdaptiveWorkspace {
  @State containerSize: Size = { width: 0, height: 0 };
  @State widthBp: WidthBreakpoint = WidthBreakpoint.WIDTH_MD;

  private columns(): string {
    if (this.widthBp === WidthBreakpoint.WIDTH_XS) {
      return '1fr';
    }
    if (this.widthBp === WidthBreakpoint.WIDTH_SM) {
      return '1fr 1fr';
    }
    return '1fr 1fr 1fr';
  }

  build() {
    ContainerReader({
      size: this.containerSize!!,
      widthBreakpoint: this.widthBp!!
    }) {
      Column({ space: 12 }) {
        Text('内容区宽度：' + this.containerSize.width + 'vp')
          .fontSize(14)
          .fontColor('#59636E')

        Grid() {
          ForEach([0, 1, 2, 3, 4, 5], (index: number) => {
            GridItem() {
              Text('模块 ' + (index + 1))
                .width('100%')
                .height(96)
                .textAlign(TextAlign.Center)
            }
          })
        }
        .columnsTemplate(this.columns())
        .columnsGap(12)
        .rowsGap(12)
        .width('100%')
        .layoutWeight(1)
      }
      .width('100%')
      .height('100%')
    }
    .breakpointConfig({ width: [520, 840] })
    .width('100%')
    .height('100%')
  }
}

@Entry
@Component
struct FreeWindowPage {
  build() {
    Row() {
      Column() { Text('导航') }
        .width(240)
        .height('100%')

      AdaptiveWorkspace()
        .layoutWeight(1)
        .height('100%')
    }
    .width('100%')
    .height('100%')
  }
}

这个改法的效果不是“ContainerReader 自动让所有代码变快”，而是**把尺寸状态限制在真正需要重排的子树里**。左侧导航不依赖 containerSize，就没有理由跟着每一次内容区尺寸变化重新计算。

案例二：同一个卡片放在主区和检查器里，布局却应该不同

可复用卡片经常同时出现在主内容区和右侧检查器。它们处在同一个窗口中，但容器宽度完全不同。如果按窗口断点，两个卡片会同时切换；按容器断点，它们可以各自选择最合适的结构。

import { ContainerReader, Size } from '@kit.ArkUI';

@Component
struct MetricCard {
  @Prop title: string = '';
  @State size: Size = { width: 0, height: 0 };
  @State widthBp: WidthBreakpoint = WidthBreakpoint.WIDTH_SM;

  build() {
    ContainerReader({
      size: this.size!!,
      widthBreakpoint: this.widthBp!!
    }) {
      if (this.widthBp === WidthBreakpoint.WIDTH_XS) {
        Column({ space: 8 }) {
          Text(this.title).fontWeight(FontWeight.Bold)
          Text('42 ms').fontSize(28)
          Text('最近一次采样').fontColor('#667085')
        }
        .alignItems(HorizontalAlign.Start)
      } else {
        Row() {
          Column({ space: 6 }) {
            Text(this.title).fontWeight(FontWeight.Bold)
            Text('最近一次采样').fontColor('#667085')
          }
          Blank()
          Text('42 ms').fontSize(32).fontWeight(FontWeight.Bold)
        }
      }
    }
    .breakpointConfig({ width: [360] })
    .width('100%')
    .padding(16)
    .backgroundColor('#FFFFFF')
    .borderRadius(12)
  }
}

把 MetricCard 放到 680vp 的主区时，它使用横向布局；放到 300vp 的检查器时，它自动变成纵向布局。调用方不需要传 compact=true，也不用知道卡片内部的断点规则，封装边界更干净。

三种方案怎么选

方案一：只监听 windowSizeChange

适合页面根布局。优点是覆盖全窗口，兼容思路清晰；缺点是嵌套组件拿到的不是自己的真实可用宽度。不要在高频回调里做网络请求、数据库读取或大数组重排。

方案二：使用页面级窗口断点

适合 Navigation 是否展开、页面是单栏还是双栏这类骨架变化。它比手写大量 if 更规整，但仍然解决不了“同一窗口内两个容器宽度不同”的问题。

方案三：使用 ContainerReader

适合 API 26 及以上的局部响应式组件。它最大的价值不是多一个取宽度接口，而是让组件脱离调用页面：放在主区、侧栏、弹窗或分屏里，都依据自身空间作决定。

最终做法通常不是三选一，而是分层：窗口断点决定页面骨架，ContainerReader 决定局部组件内部结构。

为什么拖拽时仍可能卡

用了 ContainerReader 之后仍然卡，通常不是组件失效，而是把它读到的 size 用错了。

• 在 build 中根据每一个像素变化创建大数组；
• 把 size 同步到 AppStorage，导致无关页面一起收到更新；
• 断点切换时重新发请求，而不是复用已经加载的数据；
• 父容器尺寸依赖子组件，子组件又依赖 ContainerReader，形成反复测量；
• 只看平均帧率，没有检查断点切换瞬间的长帧。

更稳的写法是让 UI 主要依赖 widthBreakpoint，只在调试信息或确实需要精确尺寸时读取 size。数据加载和布局选择分开，拖动窗口只改变布局，不重新获取业务数据。

可测试的断点决策

把断点规则抽成纯函数，边界值就能直接测试，避免 519、520、839、840 这些位置上线后才暴露问题。

type PanelMode = 'compact' | 'medium' | 'expanded';

export function modeForWidth(widthVp: number): PanelMode {
  if (widthVp < 520) {
    return 'compact';
  }
  if (widthVp < 840) {
    return 'medium';
  }
  return 'expanded';
}

const cases: Array<[number, PanelMode]> = [
  [0, 'compact'],
  [519, 'compact'],
  [520, 'medium'],
  [839, 'medium'],
  [840, 'expanded'],
  [1440, 'expanded']
];

cases.forEach(([width, expected]) => {
  const actual = modeForWidth(width);
  if (actual !== expected) {
    throw new Error('width=' + width + ', actual=' + actual);
  }
});

这段测试对应 breakpointConfig 的左闭右开规则。只要产品调整断点，就先改同一份规则和测试，不要让设计稿、ArkUI 代码、测试用例各自保存一套数字。

验收不要只看“能切换”

我会把验收拆成五项：

验收项	操作	通过标准
连续缩放	1280vp 拖到 480vp 再返回	无闪白、无重叠、无状态丢失
断点边界	停在 519/520、839/840	每个边界只进入一个布局区间
多实例	主区和侧栏各放一张卡片	两张卡片独立切换，不互相污染
前后台	缩放后切后台再返回	保持当前数据与布局状态
性能	录制拖拽过程 Trace	主线程无 IO，断点切换无明显长帧

还要补一个容易忽略的检查：自由窗口有标题栏，可绘制区域不等于物理屏幕尺寸。使用屏幕宽高计算组件布局，会把标题栏、侧栏和分屏占用都漏掉。

版本与兼容策略

ContainerReader 从 API 26 开始提供。项目如果还要兼容更低 API，不能只写一套代码然后假设能力存在。可行的工程方案是：API 26 组件走 ContainerReader；低版本保留页面级断点组件；两套实现共用同一个 PanelMode 和内容 Builder，避免复制业务逻辑。

官方参考：

• ContainerReader（文档更新时间 2026-08-29）：https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-layout-development-container-reader
• 自由窗口简介（文档更新时间 2026-06-27）：https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/freeform-window-overview
• 窗口布局与尺寸监听：https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/window-layout

最后总结

自由窗口适配最容易犯的错误，是拿“整个窗口还能放下”替代“这个组件真的放得下”。ContainerReader 把判断依据下沉到容器本身，尤其适合 API 26 的鸿蒙电脑、平板自由窗口和复杂分栏。

真正能改善体验的组合是：页面骨架看窗口，复用组件看容器；断点变化只改布局，不重新加载数据；边界规则写成纯函数并覆盖临界值；最后用 Trace 检查拖拽过程，而不是只截一张最终效果图。