HarmonyOS 7（API 26）Beta2 提供 LazyDynamicLayout 与 LazyLayoutAlgorithm 相关能力，可通过自定义懒加载算法实现任意布局，并仅创建父滚动容器可视区域附近的子组件。本文接口示意需结合当前 ArkUI 文档校对。

瀑布流、时间轴、棋盘、标签云和不规则媒体墙往往无法用固定 List 或 Grid 精确表达。直接一次性创建全部子组件虽然简单，但会拉长首帧、增加内存，并在数据规模上升后出现明显卡顿。自定义懒布局让开发者控制测量与排布，同时保留“只创建可视内容”的性能优势。

能力越灵活，越容易写出不可收敛的测量算法。本文从坐标模型、可视窗口、缓存、锚点恢复和性能验收设计一条安全接入路径。

一、先确认内置布局不够用

如果业务只是规则列表、固定网格或简单瀑布流，优先使用成熟组件。自定义算法适合存在不规则尺寸、动态跨列、特殊对齐或运行时切换布局的场景。

选择前记录需求：是否需要双向滚动、子项尺寸能否预估、是否支持插入删除、是否需要滚动到指定 ID、横竖屏是否切换算法。没有这些约束就开始写 onMeasure，后期很容易推倒重来。

二、建立统一坐标系

算法至少维护内容坐标、视口坐标和滚动偏移。所有测量结果使用同一单位，避免 px 与 vp 混用。

interface ItemLayout {
  id: string
  index: number
  x: number
  y: number
  width: number
  height: number
}

interface LayoutViewport {
  offset: number
  width: number
  height: number
  overscan: number
}

ItemLayout 是算法结果，不包含页面状态；子组件根据稳定 ID 获取自己的业务数据。

三、只计算可视区加预加载区

若视口高度为 900vp，可以在上下各增加约半屏预加载，避免快速滚动时白屏。预加载不是越大越好，过大会恢复成全量创建。

function intersects(item: ItemLayout, viewport: LayoutViewport): boolean {
  const start = viewport.offset - viewport.overscan
  const end = viewport.offset + viewport.height + viewport.overscan
  return item.y + item.height >= start && item.y <= end
}

function visibleItems(all: ItemLayout[], viewport: LayoutViewport): ItemLayout[] {
  return all.filter(item => intersects(item, viewport))
}

真实实现应通过索引快速定位起始项，而不是每次过滤全部数据。

四、尺寸缓存必须版本化

图片加载、字体缩放和多语言会改变子项高度。缓存键至少包含业务 ID、内容版本、容器宽度和字体等级，任何一项变化都应失效。

interface MeasureKey {
  id: string
  version: number
  widthBucket: number
  fontScaleBucket: number
}

class MeasureCache {
  private values = new Map<string, { width: number; height: number }>()
  key(input: MeasureKey) {
    return `${input.id}:${input.version}:${input.widthBucket}:${input.fontScaleBucket}`
  }
}

缓存要有 LRU 或容量上限，数据源切换和账号退出时清空。

五、测量阶段禁止修改业务状态

布局测量可能被系统多次调用，必须是可重复、无外部副作用的计算。不能在 onMeasure 中发网络请求、修改收藏状态或追加数据，否则可能形成重入与无限布局。

class MasonryPlanner {
  plan(items: MediaItem[], width: number, columns: number): ItemLayout[] {
    const gap = 12
    const columnWidth = (width - gap * (columns - 1)) / columns
    const heights = Array(columns).fill(0)
    return items.map((item, index) => {
      const column = heights.indexOf(Math.min(...heights))
      const height = columnWidth / item.aspectRatio
      const result = { id: item.id, index, x: column * (columnWidth + gap), y: heights[column], width: columnWidth, height }
      heights[column] += height + gap
      return result
    })
  }
}

这里的 Planner 是纯函数，便于脱离 UI 运行单元测试。

六、滚动锚点使用稳定 ID

图片异步加载后高度变化，若只保存像素偏移，页面会跳动。保存当前首个可见项 ID 及它相对视口的偏移，重新布局后恢复锚点。

interface ScrollAnchor {
  itemId: string
  offsetInsideViewport: number
}

function restoreOffset(anchor: ScrollAnchor, layouts: ItemLayout[]): number | null {
  const target = layouts.find(x => x.id === anchor.itemId)
  return target ? target.y - anchor.offsetInsideViewport : null
}

删除锚点项时，回退到相邻稳定项或最接近的有效偏移。

七、插入删除不能全量闪烁

数据变化时通过稳定 Key 复用未变化组件。插入头部内容后重新计算受影响区域，但不要把所有组件视为新节点。批量更新合并到一次布局事务，避免每条数据触发一轮测量。

对于实时流，设置批处理窗口和最大等待时间：高频消息每 100ms 合并，用户停留在顶部时自动插入，离开顶部时显示“有新内容”而不是强制跳动。

八、方向与算法可以动态切换

手机竖屏使用单列时间轴，平板横屏使用双列媒体墙。切换算法前保存锚点和子组件业务状态，切换后恢复同一内容，而不是回到第一项。

type LayoutMode = 'timeline' | 'masonry' | 'compact-grid'

function chooseMode(width: number, reduceMotion: boolean): LayoutMode {
  if (width < 600) return 'timeline'
  if (reduceMotion) return 'compact-grid'
  return 'masonry'
}

算法选择应基于容器宽度，而不是设备名称。

九、异常回退

子项尺寸无效、算法抛错或数据缺少宽高比时，使用默认尺寸并记录一次诊断事件。连续异常超过阈值后回退到普通 List/Grid，保证内容仍可访问。

布局错误不能让滚动范围变成负数或无限大。所有坐标进入渲染前检查有限值和上限。

十、性能验收

describe('MasonryPlanner', () => {
  it('keeps all items inside the container', () => {
    const result = planner.plan(fixtures, 1024, 3)
    expect(result.every(x => x.x >= 0 && x.x + x.width <= 1024)).toBe(true)
  })
})

使用 100、1000、10000 条数据测量首帧、滚动帧时间、活跃组件数、峰值内存和跳转到指定 ID 的耗时。还要覆盖字体放大、横竖屏、图片迟到、快速往返滚动和插入删除。

十一、上线清单

• 已确认内置 List/Grid 无法满足需求；
• 坐标系、滚动方向和单位统一；
• 仅计算视口附近并限制预加载范围；
• 尺寸缓存包含宽度、字体和内容版本；
• 测量与布局阶段没有业务副作用；
• 锚点使用稳定 ID，异步尺寸变化不跳页；
• 算法异常时可回退标准布局；
• 低端设备上有首帧、内存和滚动证据。

结语

LazyLayoutAlgorithm 让“不规则布局”与“懒加载”不再二选一。真正可靠的实现依赖纯算法、稳定锚点、版本化尺寸缓存和可回退策略。先把坐标与状态边界设计清楚，再追求视觉自由，才能避免把首帧优化变成新的滚动问题。

官方参考

• LazyLayoutAlgorithm API：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-lazylayoutalgorithm
• 2026 年 7 月开发者月刊：https://developer.huawei.com/consumer/cn/monthly/202607