跨端 UI 一致性：从断点策略到容器查询的响应式工程体系

一、同一设计稿，三种断裂——跨端适配的还原度困境

响应式设计的理想状态是：一套代码，在手机、平板和桌面上都呈现出设计师预期的视觉效果。但现实往往是：桌面端完美还原，平板端布局挤压，手机端元素重叠。这不是媒体查询写少了，而是断点策略本身存在结构性缺陷。

生产中的典型断裂：某电商产品详情页，桌面端三栏布局（商品图 / 信息 / 推荐），平板端两栏（商品图+信息 / 推荐），手机端单栏。设计师在 Figma 中定义了三个断点：768px、1024px、1440px。开发实现后，在 iPad Mini（744px 宽）上，页面使用了手机端布局，但 iPad Mini 的屏幕高度足够显示两栏内容。问题出在断点只考虑了宽度，没有考虑视口的宽高比。

更深层的矛盾：媒体查询基于视口宽度（Viewport Width），但组件的适配需求基于自身容器的宽度。一个侧边栏中的卡片，在桌面端侧边栏宽度为 300px 时应该使用紧凑布局，但媒体查询只知道视口宽度是 1440px，无法感知容器的实际宽度。这导致组件无法独立于页面上下文进行自适应。

二、从视口断点到容器查询——响应式策略的范式转移

CSS Container Queries 的出现，改变了响应式设计的根本范式：从"视口多大"变为"容器多大"。组件不再依赖全局视口宽度来决定布局，而是根据自身容器的可用空间自适应调整。

flowchart LR
    subgraph Old["传统媒体查询模式"]
        A1[视口宽度 1440px] --> B1[全局断点判断<br>@media min-width: 1024px]
        B1 --> C1[所有组件使用桌面布局]
    end

    subgraph New["容器查询模式"]
        A2[视口宽度 1440px] --> B2[侧边栏容器 300px]
        A2 --> B3[主内容容器 1100px]
        B2 --> C2[卡片使用紧凑布局<br>@container min-width: 280px]
        B3 --> C3[卡片使用标准布局<br>@container min-width: 600px]
    end

    Old -->|问题| D[侧边栏中的卡片<br>被迫使用桌面布局]
    New -->|解决| E[每个容器内的组件<br>独立适配]

/*
 * 容器查询实战：可自适应的卡片组件
 * 卡片根据容器宽度自动切换水平/垂直布局
 * 不依赖视口宽度，可放置在页面任意位置
 */

/* 步骤1：声明容器查询的上下文 */
.card-container {
  container-type: inline-size;  /* 只监听容器宽度变化 */
  container-name: card;         /* 命名容器，供 @container 引用 */
}

/* 步骤2：默认布局（窄容器）——垂直堆叠 */
.product-card {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-3);       /* 12px 间距 */
  padding: var(--spacing-4);   /* 16px 内边距 */
  border-radius: var(--radius-lg); /* 12px 圆角 */
  background: var(--color-bg-surface);
}

.product-card__image {
  width: 100%;
  aspect-ratio: 4 / 3;        /* 图片固定宽高比，避免布局抖动 */
  border-radius: var(--radius-md); /* 8px 圆角 */
  object-fit: cover;
}

.product-card__title {
  font-size: 16px;             /* 窄容器下标题 16px */
  font-weight: 600;
  line-height: 1.4;            /* 行高 1.4，保证可读性 */
  color: var(--color-text-primary);
}

/* 步骤3：宽容器布局——水平排列 */
@container card (min-width: 400px) {
  .product-card {
    flex-direction: row;       /* 切换为水平布局 */
    gap: var(--spacing-4);     /* 16px 间距，比垂直布局更宽 */
  }

  .product-card__image {
    width: 200px;              /* 固定图片宽度，不随容器拉伸 */
    aspect-ratio: 3 / 4;       /* 竖版图片，适合水平布局 */
    flex-shrink: 0;            /* 防止图片被压缩 */
  }

  .product-card__title {
    font-size: 18px;           /* 宽容器下标题放大到 18px */
  }
}

/* 步骤4：更宽容器布局——信息扩展 */
@container card (min-width: 600px) {
  .product-card__image {
    width: 280px;              /* 图片进一步放大 */
  }

  .product-card__title {
    font-size: 20px;           /* 标题 20px，层级更突出 */
    line-height: 1.3;          /* 行高收紧到 1.3，大标题更紧凑 */
  }
}

容器查询的关键约束：container-type: inline-size 只监听行内方向（水平）的尺寸变化。如果同时需要监听高度变化，使用 container-type: size，但这会增加浏览器的计算开销——每次容器尺寸变化都需要重新评估所有 @container 规则。在组件数量较多的页面中，建议只使用 inline-size。

三、跨端一致性保障：Web 与 Flutter 的布局 Token 对齐

响应式布局的跨端一致性，核心在于断点定义和间距体系的对齐。Web 端用 CSS 媒体查询/容器查询，Flutter 端用 MediaQuery 和 LayoutBuilder，但两者必须共享同一套断点值和间距 Token。

/**
 * 跨端布局 Token 定义
 * 断点值和间距值在此统一定义，
 * 通过编译器分别生成 CSS 和 Flutter 代码
 */
const layoutTokens = {
  breakpoints: {
    sm: 640,     /* 手机横屏/小平板 */
    md: 768,     /* 平板竖屏 */
    lg: 1024,    /* 平板横屏/小桌面 */
    xl: 1280,    /* 标准桌面 */
    '2xl': 1536, /* 大桌面 */
  },
  spacing: {
    xs: 4,       /* 图标与文字间距 */
    sm: 8,       /* 紧凑元素内边距 */
    md: 16,      /* 标准内边距 */
    lg: 24,      /* 卡片内边距 */
    xl: 32,      /* 区块间距 */
    '2xl': 48,   /* 大区块间距 */
    '3xl': 64,   /* 页面级间距 */
  },
  grid: {
    columns: {
      sm: 4,     /* 手机端 4 列网格 */
      md: 8,     /* 平板端 8 列网格 */
      lg: 12,    /* 桌面端 12 列网格 */
    },
    gutter: {
      sm: 16,    /* 手机端列间距 16px */
      md: 24,    /* 平板端列间距 24px */
      lg: 32,    /* 桌面端列间距 32px */
    },
  },
};

/**
 * 生成 CSS 断点媒体查询
 * 使用 min-width 策略（Mobile First）
 */
function generateCSSBreakpoints(): string {
  const lines: string[] = ['/* 自动生成的响应式断点 */'];

  for (const [name, value] of Object.entries(layoutTokens.breakpoints)) {
    lines.push(`@custom-media --${name}: (min-width: ${value}px);`);
  }

  return lines.join('\n');
}

/**
 * 生成 Flutter 断点常量
 * Flutter 使用 MediaQuery.of(context).size.width 获取视口宽度
 */
function generateFlutterBreakpoints(): string {
  const lines: string[] = [
    '// 自动生成的响应式断点',
    'class Breakpoints {',
  ];

  for (const [name, value] of Object.entries(layoutTokens.breakpoints)) {
    // 将 sm 转换为 sm (驼峰)，640 转换为 640.0 (Flutter double)
    const dartName = name.replace(/^(\d)/, 'v$1'); // 避免数字开头
    lines.push(`  static const double ${dartName} = ${value}.0;`);
  }

  lines.push('}');
  return lines.join('\n');
}

跨端对齐的工程要点：断点值必须在同一份 JSON/TS 文件中定义，通过编译器生成各端代码。如果 Web 端和 Flutter 端各自定义断点值，即使初始值相同，后续维护中必然出现偏差。实测数据：两个团队独立维护断点值 6 个月后，md 断点在 Web 端为 768px，在 Flutter 端为 800px，导致同一页面在两端呈现不同的布局。

四、容器查询的兼容性与降级策略

容器查询的工程化落地，必须正视兼容性问题：

第一，浏览器支持度。 Container Queries 在 Chrome 105+、Safari 16+、Firefox 110+ 中支持。对于需要兼容旧浏览器的项目，必须提供降级方案。降级策略：使用 @supports 检测容器查询支持，不支持时回退到媒体查询。但回退意味着组件无法根据容器宽度自适应，只能根据视口宽度调整——这回到了传统响应式的老路。

第二，性能开销。 容器查询需要在每次容器尺寸变化时重新评估 CSS 规则。在一个包含 50 个卡片组件的列表页中，窗口缩放时会触发 50 次容器查询评估。实测数据：50 个容器查询的评估耗时约 2ms，对帧率影响可忽略。但如果容器查询中包含复杂的计算（如 calc() 嵌套），评估耗时可能增加到 10ms。

第三，嵌套容器的复杂性。 当一个容器查询组件嵌套在另一个容器查询组件中时，内层容器的尺寸变化可能由外层容器的布局变化引起。这种级联效应使得调试变得困难——某个组件的布局变化，根源可能在三层之外的父容器。

适用场景：组件库中的自适应组件、需要在不同页面上下文中复用的卡片/面板、侧边栏中的可折叠区域。禁用场景：需要兼容 IE11 或旧版移动浏览器的项目、页面级布局（仍应使用媒体查询）、性能预算极低的移动端 H5。

五、总结

跨端 UI 一致性的核心挑战，在于组件的自适应需求与视口断点的全局性之间的矛盾。容器查询通过让组件根据自身容器宽度调整布局，解决了这个矛盾。container-type: inline-size 是性能与功能的平衡点，只监听水平尺寸变化避免了不必要的重计算。跨端布局 Token 的统一定义和编译器生成，确保了 Web 端与 Flutter 端断点值和间距体系的一致性。

落地路线建议：第一步，将现有媒体查询中的组件级断点迁移到容器查询，先从卡片、面板等独立组件开始，验证兼容性和性能；第二步，建立跨端布局 Token 的统一定义文件，通过编译器生成 CSS 和 Flutter 代码，消除手动同步的偏差风险；第三步，在 CI 流水线中加入跨端截图对比，使用相同的布局 Token 和测试数据，自动检测 Web 端与 Flutter 端的布局差异。