将 AnimationSheetBuilder.display 替换为 collate

AnimationSheetBuilder.display 和 sheetSize 方法已弃用，应替换为 AnimationSheetBuilder.collate。

AnimationSheetBuilder 是一个测试实用程序类，用于记录动画 widget 的帧，然后将这些帧组合成单个动画表以进行黄金测试。旧的组合方式涉及使用 display 将图像列出到表格状 widget 中，使用 sheetSize 调整测试表面，并捕获表格 widget 进行比较。一种新的方式 collate 已被添加，它直接将帧组合成图像进行比较，这需要更少的样板代码，并输出更小的图像，同时不影响质量。因此，旧方式的 API 已弃用。

collate 输出更小图像的原因是，旧方式在像素比为 3.0 的测试表面上捕获，这意味着它使用一个 3x3 的同色像素块来表示一个实际像素，使得图像比实际需要大 9 倍（在 PNG 压缩之前）。

对 AnimationSheetBuilder 类进行了以下更改：

'display' 已弃用，不应使用
'sheetSize' 已弃用，不应使用

要迁移到新的 API，请将设置表面大小和显示 widget 的过程更改为 AnimationSheetBuilder.collate。

collate 需要一个显式的 cellsPerRow 参数，它是输出图像中每行的帧数。可以手动计数，也可以按如下方式计算：

查找在构造 AnimationSheetBuilder 时指定的帧宽度。例如，在以下代码片段中是 80

dartfinal AnimationSheetBuilder animationSheet = AnimationSheetBuilder(frameSize: const Size(80, 30));

查找设置表面大小时指定的表面宽度；默认值为 800。例如，在以下代码片段中是 600

dart

tester.binding.setSurfaceSize(animationSheet.sheetSize(600));

每行的帧数应是这两个数字相除的结果，并向下取整。例如，600 / 80 = 7（向下取整），因此

dart

animationSheet.collate(7)

迁移前的代码

dart  testWidgets('Indeterminate CircularProgressIndicator', (WidgetTester tester) async {
    final AnimationSheetBuilder animationSheet = AnimationSheetBuilder(frameSize: const Size(40, 40));

    await tester.pumpFrames(animationSheet.record(
      const Directionality(
        textDirection: TextDirection.ltr,
        child: Padding(
          padding: EdgeInsets.all(4),
          child: CircularProgressIndicator(),
        ),
      ),
    ), const Duration(seconds: 2));

    // The code starting here needs migration.

    tester.binding.setSurfaceSize(animationSheet.sheetSize());

    final Widget display = await animationSheet.display();
    await tester.pumpWidget(display);

    await expectLater(
      find.byWidget(display),
      matchesGoldenFile('material.circular_progress_indicator.indeterminate.png'),
    );
  }, skip: isBrowser); // https://github.com/flutter/flutter/issues/42767

迁移后的代码（cellsPerRow 为 20，由 800 / 40 得出）

dart  testWidgets('Indeterminate CircularProgressIndicator', (WidgetTester tester) async {
    final AnimationSheetBuilder animationSheet = AnimationSheetBuilder(frameSize: const Size(40, 40));

    await tester.pumpFrames(animationSheet.record(
      const Directionality(
        textDirection: TextDirection.ltr,
        child: Padding(
          padding: EdgeInsets.all(4),
          child: CircularProgressIndicator(),
        ),
      ),
    ), const Duration(seconds: 2));

    await expectLater(
      animationSheet.collate(20),
      matchesGoldenFile('material.circular_progress_indicator.indeterminate.png'),
    );
  }, skip: isBrowser); // https://github.com/flutter/flutter/issues/42767

预计相关的黄金测试参考图像将失效，需要全部更新。新图像应与旧图像相同，只是比例为 1/3。

发布版本：v2.3.0-13.0.pre
稳定版本：2.5

API 文档

将 AnimationSheetBuilder.display 替换为 collate

概述

背景

变更说明

迁移指南

推导每行单元格数

迁移代码

时间线

参考资料