将 AnimationSheetBuilder.display 替换为 collate

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

AnimationSheetBuilder 是一个测试实用工具类，它会记录动画 widget 的帧，然后将这些帧组合成一个单独的动画表，用于黄金测试。旧的组合方式涉及使用 display 将图像列入类似表格的 widget，使用 sheetSize 调整测试表面，并捕获表格 widget 进行比较。新增的 collate 方法可以直接将帧组合成一张图像用于比较，这样可以减少样板代码，并输出一张尺寸更小但质量不受影响的图像。因此，旧方法的 API 已被弃用。

collate 输出的图像尺寸更小，是因为旧方法在像素比例为 3.0 的测试表面上进行捕获，这意味着它会使用 3x3 的相同颜色像素块来表示 1 个实际像素，导致图像尺寸比实际需要的大 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

概述

背景

变更说明

迁移指南

推导每行的单元格数

迁移代码

时间线

参考资料