ContainerReader 容器断点：告别全局 BreakpointModel，实现组件级自适应布局

一、为什么需要容器断点

在 HarmonyOS 5.0 时代，实现多设备适配主要依赖全局断点方案——通过 BreakpointModel 监听窗口尺寸变化，将设备分为 sm/md/lg 三个断点，然后在整个页面中根据全局断点调整布局。这种方案的局限性在于：所有组件共享同一个断点值，无法根据自身容器尺寸独立适配。

以我们的 MainPage 为例，首页包含功能入口 Grid（5 个图标）和练习模式 2x2 卡片两个区域。在折叠屏展开状态下，页面宽度从 360vp 变为 720vp，此时功能入口 Grid 应该从 3 列变为 5 列，但练习卡片区域可能仍然保持 2x2 布局。全局断点无法区分这两个区域的差异——要么都变，要么都不变。

HarmonyOS 6.0 的 ContainerReader 组件解决了这个问题。它将断点的判断粒度从"窗口级"降低到"容器级"，每个容器组件可以独立监听自身尺寸变化、触发对应的断点回调，从而实现精细化的自适应布局。

二、ContainerReader 的创建与监听

ContainerReader 是一个容器组件，它包裹一个子组件，并在子组件的尺寸变化时触发回调。使用方式非常简洁：

ContainerReader({ onContainerChange: (width: number, height: number) => {
  if (width >= 600) {
    this.gridColumns = 4;
  } else if (width >= 400) {
    this.gridColumns = 3;
  } else {
    this.gridColumns = 2;
  }
}}) {
  Grid() {
    // 根据 gridColumns 渲染不同列数
  }
  .columnsTemplate('1fr '.repeat(this.gridColumns));
}

ContainerReader 的回调在以下时机触发：

• 组件首次渲染时：获取初始尺寸，设置默认断点。
• 容器尺寸变化时：如窗口缩放、分屏切换、折叠屏展开/折叠。
• 父容器布局变化时：如父容器从 Row 变为 Column，影响了子容器的可用宽度。

ContainerReader 的回调是同步的，这意味着在回调中修改状态变量、触发布局更新时，会在同一帧内完成，不会产生额外的布局抖动。

三、BreakpointType 对接 ContainerReader

项目中已有的 BreakpointModel 和 BreakpointUtils 是基于窗口断点的方案。通过 BreakpointType 可以方便地为不同断点设置不同的值。在适配 ContainerReader 时，我们可以保留 BreakpointType 的数据结构，但将其关联的断点值从窗口断点改为容器断点。

// 已有的 BreakpointType 定义（在 BreakpointUtils.ets 中）
export class BreakpointType<T> {
  sm: T;
  md: T;
  lg: T;

  constructor(sm: T, md: T, lg: T) {
    this.sm = sm;
    this.md = md;
    this.lg = lg;
  }

  getValue(breakpoint: string): T {
    switch (breakpoint) {
      case 'sm': return this.sm;
      case 'md': return this.md;
      case 'lg': return this.lg;
      default: return this.sm;
    }
  }
}

在 ContainerReader 场景中，我们可以将容器宽度映射为 sm/md/lg 断点：

ContainerReader({ onContainerChange: (width: number) => {
  if (width >= 600) {
    this.containerBreakpoint = 'lg';
  } else if (width >= 380) {
    this.containerBreakpoint = 'md';
  } else {
    this.containerBreakpoint = 'sm';
  }
}}) {
  // 使用 BreakpointType 获取对应值
  let columns = new BreakpointType<number>(2, 3, 4).getValue(this.containerBreakpoint);
  Grid().columnsTemplate('1fr '.repeat(columns));
}

这种方式既复用了已有的 BreakpointType 工具类，又实现了断点维度的升级——从窗口级到容器级。

四、首页 Grid 功能入口按容器宽度决定列数

在 MainPage 中，功能入口区域展示 5 个核心功能图标（搜单词、易错词、生词本、笔记、学习报告）。原始实现使用固定的 5 列 Grid 布局，在窄屏设备上图标拥挤，在宽屏设备上又浪费空间。

使用 ContainerReader 改造后，Grid 的列数根据容器实际宽度动态调整：

@Local containerBreakpoint: string = 'sm';
@Local gridColumns: number = 3;

build() {
  Column() {
    // ... 其他内容
    ContainerReader({ onContainerChange: (width: number) => {
      if (width >= 500) {
        this.gridColumns = 5;
      } else if (width >= 350) {
        this.gridColumns = 3;
      } else {
        this.gridColumns = 2;
      }
    }}) {
      Grid() {
        ForEach(this.functions, (item: CourseCoreBar) => {
          GridItem() {
            // 功能图标组件
          }
        })
      }
      .columnsTemplate('1fr '.repeat(this.gridColumns))
      .rowsGap(12)
      .columnsGap(12)
    }
    // ... 其他内容
  }
}

在折叠屏展开场景下，MainPage 的根 Column 宽度翻倍，功能入口 Grid 容器的宽度随之增大，ContainerReader 自动触发断点切换，Grid 列数从 3 列变为 5 列，图标从"拥挤"变为"舒展"，无需任何额外的窗口监听逻辑。

五、单词卡片区域的按高度自适应

ContainerReader 不仅能监听宽度，还能监听高度变化。这在单词卡片应用场景中很有价值——当卡片区域高度充足时，展示完整的例句和翻译；当高度受限时，只展示单词和音标，例句折叠起来。

在 CourseHomePage 中，单词卡片下方有一个区域用于展示详细例句。通过 ContainerReader 监听卡片容器的高度变化：

@Local showDetailedExample: boolean = false;

ContainerReader({ onContainerChange: (width: number, height: number) => {
  this.showDetailedExample = height >= 400;
}}) {
  Column() {
    Text(this.currentWord().word).fontSize(32);
    Text(this.currentWord().phonetic).fontSize(16);
    if (this.showDetailedExample) {
      Text(this.currentWord().example).fontSize(14).margin({ top: 16 });
      Text(this.currentWord().exampleTranslation).fontSize(14).opacity(0.7);
    }
  }
}

这种按高度自适应的能力在平板分屏或多窗口场景中尤其有用——用户可以将 App 拖放到屏幕一侧，窄窗口依然能根据可用高度智能调整信息密度。

六、多容器独立断点的布局灵活性

ContainerReader 的真正威力在于"多容器独立断点"。一个页面中可以有多个 ContainerReader，各自独立监听、独立响应。这在复杂的仪表盘页面中价值巨大。

以 DashboardPage（学习统计仪表盘）为例，页面中包含多个统计卡片区域：

• 左侧"学习概览"区域（窄，可能仅 300vp 宽）：展示核心数字（已学词数、连续天数）。
• 右侧"详细统计"区域（宽，可能 600vp 宽）：展示各题型正确率柱状图。

两个区域使用各自的 ContainerReader，左侧在 300vp 宽度下采用垂直排列，右侧在 600vp 宽度下展示完整图表。如果使用全局断点，宽屏下的全局断点 md/lg 会同时影响两个区域，导致左侧也试图展示完整图表，布局反而失调。

七、实践建议：新组件优先使用 ContainerReader

在推广 ContainerReader 时，建议采用"新组件直接使用，存量组件逐步迁移"的策略：

1. 新功能组件：所有新增的页面和组件优先使用 ContainerReader 实现自适应布局，不再依赖全局 BreakpointModel。
2. 高流量组件：优先迁移首页 MainPage 的功能入口 Grid 和练习模式区域，用户感知最明显。
3. 复杂页面：如 DashboardPage 等包含多个独立区域的页面，使用多 ContainerReader 实现区域级布局。
4. 替代而非共存：当某个组件的 ContainerReader 改造完成后，移除该组件中对全局 BreakpointModel 的依赖。

八、总结

ContainerReader 是 HarmonyOS 6.0 中布局能力的重大升级。它将响应式布局的判断粒度从窗口级精确到容器级，使得同一页面中的不同区域可以根据自身尺寸独立适配。从首页 Grid 的按宽变列、到单词卡片区域的按高展句，ContainerReader 让"一处适配、处处灵活"成为现实。