Flutter 复杂布局中文案自动换行的实践总结

场景描述

在 Flutter 开发中，经常会遇到内联布局（inline layout）的需求：文案、图标、徽章等元素混合排列在同一行，当文案过长时自动折行。比如会员卡片的 VIP 标签行：

[VIP图标] Weekly VIP + 5 🎫 Watch Passes

当 VIP 名称 subscriptionInfo.name 很长时，预期行为是自动换行：

[VIP图标] Premium Annual
VIP Subscription + 5 🎫
Watch Passes

问题演进

第一版：Row — 单行不换行

最初用 Row：

Widget vipText = [
  icon,
  ShaderMask(child: Text(name)),
  plusText,
  passesGroup,
].toRow();

问题：Row 始终保持单行，文案过长直接溢出。且 ShaderMask + Text 作为一个不可拆分的子节点，无法在 Row 内换行。

第二版：Wrap — 部分换行但仍然溢出

用 Wrap 替代 Row：

Widget vipText = Wrap(
  children: [
    icon,
    ShaderMask(child: Text(name)),
    plusText,
    [icon5, passesIcon, passesText].toRow(),
  ],
);

问题：虽然 Wrap 支持自动折行，但 [icon5, passesIcon, passesText].toRow() 作为一个整体参与 Wrap 的换行，仍然是不可拆分的最小单元。更重要的是，ShaderMask(child: Text(name)) 作为 Wrap 的直接子节点，Wrap 在约束子节点宽度方面存在局限——当 Text(name) 超过可用宽度时可能直接溢出，而不是自动软换行。

第三版：Expanded + Wrap + 扁平化子节点

最终解法，同时做了两件事：

1. 用 Expanded 给 Wrap 精确的宽度约束

Widget vipText = [
  icon,
  Expanded(
    child: Wrap(...),
  ),
].toRow();

Wrap 放入 Expanded 中，使其获得精确的剩余宽度，内部文字才能正确 softWrap。

2. 扁平化 Wrap 子节点，不嵌套 Row

将所有元素作为 Wrap 的直接子节点：

Widget vipText = [
  icon,
  Expanded(
    child: Wrap(
      crossAxisAlignment: WrapCrossAlignment.center,
      children: [
        ShaderMask(child: Text(name)),   // 独立元素
        plusText,                         // 独立元素
        ShaderMask(child: Text('5')),    // 独立元素
        passesIcon,                       // 独立元素
        ShaderMask(child: Text('Watch Passes')), // 独立元素
      ],
    ),
  ),
].toRow();

每个元素独立参与 Wrap 的换行算法，任何元素都可以在任意位置折到下一行，实现最自然的文案流式换行。

关键原则

1. 需要换行就用 Wrap，不要用 Row — Row 强制单行。
2. Wrap 需要精确宽度约束 — 通过 Expanded 或 SizedBox 提供，否则 Wrap 可能无法正确约束内部 Text 的宽度。
3. 扁平化 Wrap 子节点 — 不要把几个元素捆在一个 Row 里再放进 Wrap，拆开才能让每个元素独立换行。
4. 视觉装饰（ShaderMask、渐变色）不是约束 — ShaderMask 不影响布局，内部的 Text 依然可以通过 softWrap 正常换行。