内容

剪裁行为

内容

摘要
上下文
迁移指南
时间线
参考

Flutter 现在默认情况下不进行剪裁，除了少数专门的 Widget（例如 ClipRect）。若要覆盖不剪裁的默认设置，请在 Widget 构造中显式设置 clipBehavior。

Flutter 过去因为裁剪（clip）操作导致速度缓慢。例如，Flutter Gallery 应用的基准测试显示，在 2018 年 5 月，平均帧光栅化时间约为 35 毫秒，而流畅 60fps 渲染的预算为 16 毫秒。通过移除不必要的裁剪及其相关操作，我们实现了近乎 2 倍的速度提升，从 35 毫秒/帧降至 17.5 毫秒/帧。

当时与裁剪相关的最大成本在于，Flutter 习惯在每次裁剪后添加 saveLayer 调用（除非是简单的轴对齐矩形裁剪），以避免像Issue 18057中描述的边缘锯齿伪影。这种行为在通过 Card、Chip、Button 等小部件的 Material 应用中普遍存在，导致 PhysicalShape 和 PhysicalModel 裁剪其内容。

saveLayer 调用在旧设备上尤其昂贵，因为它会创建一个离屏渲染目标，而渲染目标切换有时可能花费大约 1 毫秒。

即使没有 saveLayer 调用，裁剪仍然很昂贵，因为它会应用于所有后续绘制操作，直到它被恢复。因此，单个裁剪可能会降低数百个绘制操作的性能。

除了性能问题外，Flutter 还存在一些正确性问题，因为裁剪没有在一个地方进行管理和实现。在一些地方，saveLayer 被插入到错误的位置，因此它只会增加性能成本，而不会修复任何边缘锯齿伪影。

因此，我们在这次重大更改中统一了 clipBehavior 控制及其实现。对于大多数小部件，默认 clipBehavior 为 Clip.none 以节省性能，但以下情况除外：

ClipPath 默认值为 Clip.antiAlias
ClipRRect 默认值为 Clip.antiAlias
ClipRect 默认值为 Clip.hardEdge
Stack 默认值为 Clip.hardEdge
EditableText 默认值为 Clip.hardEdge
ListWheelScrollView 默认值为 Clip.hardEdge
SingleChildScrollView 默认值为 Clip.hardEdge
NestedScrollView 默认值为 Clip.hardEdge
ShrinkWrappingViewport 默认值为 Clip.hardEdge

您有 4 种代码迁移选择：

如果您的内容不需要裁剪（例如，没有一个小部件的子元素扩展到其父元素的边界之外），则可以保留代码原样。这可能会对您应用的整体性能产生积极影响。
如果需要裁剪，并且无抗锯齿的裁剪足以满足您（和您的客户）的需求，则添加 clipBehavior: Clip.hardEdge。当您裁剪矩形或具有非常小的弯曲区域（例如圆角矩形的角）的形状时，这是常见情况。
如果需要抗锯齿裁剪，则添加 clipBehavior: Clip.antiAlias。这会在略微更高的成本下为您提供更平滑的边缘。在处理圆形和弧形时，这是常见情况。
如果希望获得与之前（2018 年 5 月）完全相同的行为，则添加 clip.antiAliasWithSaveLayer。请注意，这在性能方面非常昂贵。这可能很少需要。您可能需要这种情况的一种情况是在非常不同的背景颜色上叠加图像。在这些情况下，请考虑您是否可以避免在一个位置重叠多种颜色（例如，仅在图像不存在的地方显示背景颜色）。

具体到 Stack 小部件，如果您之前使用 overflow: Overflow.visible，请将其替换为 clipBehavior: Clip.none。

对于 ListWheelViewport 小部件，如果您之前指定了 clipToSize，请将其替换为相应的 clipBehavior：对于 clipToSize = false 使用 Clip.none，对于 clipToSize = true 使用 Clip.hardEdge。

迁移前的代码

dart    await tester.pumpWidget(
      Directionality(
        textDirection: TextDirection.ltr,
        child: Center(
          child: Stack(
            overflow: Overflow.visible,
            children: const <Widget>[
              SizedBox(
                width: 100,
                height: 100,
              ),
            ],
          ),
        ),
      ),
    );

迁移后的代码

dart    await tester.pumpWidget(
      Directionality(
        textDirection: TextDirection.ltr,
        child: Center(
          child: Stack(
            clipBehavior: Clip.none,
            children: const <Widget>[
              SizedBox(
                width: 100.0,
                height: 100.0,
              ),
            ],
          ),
        ),
      ),
    );

合并版本：不同
稳定版发布：2.0.0

API 文档

Clip

摘要

上下文

迁移指南

时间线

参考