瀑布流数据模型设计

瀑布流布局的核心挑战在于动态计算每个卡片在网格中的精确位置，而这一切都建立在可靠的数据模型之上。一个设计良好的数据模型需要回答三个问题：卡片长什么样（数据结构）、高度如何预测（宽高比存储）、内容未就绪时展示什么（占位与加载状态分层）。本章围绕这三个问题，从原理到投产级代码逐一展开。

3.1 图片/卡片数据结构定义

瀑布流卡片的数据结构需要包含渲染必要的布局元数据和内容载荷。以下是一个可用于生产环境的 TypeScript 类型定义：

interface WaterfallCard<T = any> {
  /** 唯一标识符，用于 Diff 更新和 Key 管理 */
  id: string;

  /** 内容类型：图片 / 视频 / 富文本卡片 */
  type: 'image' | 'video' | 'rich';

  /** 宽高比：width/height，预计算值 */
  aspectRatio: number;

  /** 原始图片 URL（可能很大） */
  src: string;

  /** 缩略图 URL（200px 左右，用于占位） */
  thumbnailSrc?: string;

  /** 加载状态，见 3.3 节状态枚举 */
  status: CardStatus;

  /** 内容载荷，由具体业务决定 */
  payload: T;

  /** 布局缓存：计算后的高度（px），-1 表示未计算 */
  _cachedHeight: number;
}

/** 卡片加载状态枚举 */
enum CardStatus {
  /** 仅有 metadata，未开始下载 */
  INIT = 'init',
  /** 正在下载缩略图 */
  LOADING_THUMB = 'loading_thumb',
  /** 缩略图已就绪，原图仍在加载 */
  THUMB_READY = 'thumb_ready',
  /** 原图加载完成 */
  LOADED = 'loaded',
  /** 下载失败 */
  ERROR = 'error',
}

3.2 宽高比字段存储

宽高比（aspect ratio）是瀑布流布局中最关键的元数据，直接决定卡片高度计算的准确性和布局稳定性。常见的存储策略有三种，各有优劣：

在实际项目中，推荐优先使用浮点数。因为瀑布流布局引擎在每次重新布局时需要对数以千计的卡片做高度计算，浮点除法是最快的运算路径。分数格式虽然精确，但在 JavaScript 中除法的误差完全可接受（误差 < 1e-10），不值得为了理论上无误差而牺牲计算性能。

宽高比的获取途径有两种：

1. 服务器预计算：图片上传时由后端解析图片元数据，将宽高比写入数据库字段，API 响应中直接包含。这是最优方案，客户端零计算。
2. 客户端计算：在 onload 事件中读取 naturalWidth / naturalHeight。这种方案存在延迟——只有图片下载完成才能得到宽高比，对于瀑布流布局而言已经太晚，会导致布局抖动。

3.3 占位图与加载状态数据分层

为了实现「即时渲染，渐进增强」的用户体验，数据模型需要有三层结构：

• 骨架层（Skeleton）：数据列表创建时立即生成，卡片只有 id、status: INIT、aspectRatio（来自供应商或默认值），没有可渲染的图片。渲染时展示纯色背景 + 骨架动画。
• 占位层（Placeholder）：当 thumbnailSrc 下载完成后，用模糊缩略图或高斯模糊占位替换纯背景。此时 status 为 THUMB_READY。
• 内容层（Content）：原图加载完成（LOADED），替换缩略图为高清原图。如果失败（ERROR），保留缩略图并展示重试按钮。

这种分层对应的状态流转如下图所示。

3.4 代码实现：数据层的核心函数

以下是一个创建卡片数据实例的工厂函数，以及如何从 API 响应映射到三层数据模型：

function createWaterfallCard(apiItem: ApiImageItem): WaterfallCard {
  return {
    id: apiItem.id,
    type: 'image',
    // 优先使用服务器预计算的宽高比，兜底使用 1:1
    aspectRatio: apiItem.aspectRatio ?? 1,
    src: apiItem.originalUrl,
    thumbnailSrc: apiItem.thumbnailUrl,
    status: apiItem.thumbnailUrl ? CardStatus.LOADING_THUMB : CardStatus.INIT,
    payload: { title: apiItem.title, tags: apiItem.tags },
    _cachedHeight: -1,
  };
}

/** 当缩略图下载完成后，更新状态 */
function onThumbLoaded(card: WaterfallCard): WaterfallCard {
  return { ...card, status: CardStatus.THUMB_READY };
}

/** 当原图下载完成后，更新状态 */
function onFullImageLoaded(card: WaterfallCard): WaterfallCard {
  return { ...card, status: CardStatus.LOADED };
}

3.5 常见数据错误与调试

3.6 性能优化针对数据层

1. 缓存已计算的卡片高度：_cachedHeight 字段在列宽不变时直接复用，避免每次渲染都重新计算。监听窗口 resize 事件时批量清空缓存。
2. 批量状态更新：当一屏卡片同时从 INIT 进入 LOADING_THUMB 时，使用 requestAnimationFrame 合并为一次 React setState / Vue patch，避免触发多次布局重排。
3. 数据结构扁平化：不要嵌套过深的对象层级。扁平的 WaterfallCard 在序列化、比较、不可变更新时性能更优。
4. 预剪裁缩略图宽高比：在缩略图 CDN 层直接输出固定宽高比（如 ?w=200&h=150&fit=crop），避免客户端做缩放运算，省 GPU 渲染成本。