一个用于隔离开发UI组件并自动拍摄快照的库。

Playbook #

Playbook 是一个库，它提供了一个沙箱来构建UI组件，而无需担心应用程序特定的依赖项。这个概念受到了JavaScript在Web前端开发中使用的Storybook的启发。

使用Playbook构建的组件可以生成一个独立的应用程序作为活生生的样式指南。这不仅允许你快速审查UI，还可以通过将业务逻辑与组件分离来交付更健壮的设计。

此外，每个组件的快照可以通过单元测试自动生成，并且可以使用任意第三方工具进行视觉回归测试。

对于复杂的现代应用程序开发，敏感地捕捉UI更改并更快地改进它们是非常重要的。Playbook使你不必费力准备数据和花费人力进行手动测试。

Playbook #

Playbook 组件以场景的形式唯一存储。一个场景描述了组件的布局方式。

Playbook(
  stories: [
    Story(
      'Home',
      scenarios: [
        Scenario(
          'CategoryHome',
          layout: ScenarioLayout.fill(),
          child: CategoryHome(userData: UserData.stub),
        ),
        Scenario(
          'LandmarkList',
          layout: ScenarioLayout.fill(),
          child: Scaffold(
            appBar: AppBar(),
            body: LandmarkList(userData: UserData.stub),
          ),
        ),
        Scenario(
          'Container red',
          layout: ScenarioLayout.fixed(100, 100),
          child: Container(color: Colors.red),
        ),
      ],
    ),
  ],
);

PlaybookUI #

PlaybookUI 提供用户界面来浏览场景列表。

PlaybookGallery

组件的可视化效果被列出并显示。那些显示在顶部屏幕上的场景并不是实际在进行布局，而是运行时高效生成的快照。

浏览器	详情

PlaybookSnapshot #

场景可以通过符合TestTool类的实例进行测试。Snapshot就是其中之一，它可以生成所有场景的快照，并模拟给定设备的屏幕大小和安全区域。

Future<void> main() async {
  testWidgets('Take snapshots', (tester) async {
    await Playbook(
      stories: [
        barStory(),
        fooWidgetStory(),
        assetImageStory(),
        homePageStory(),
        scrollableStory(),
      ],
    ).run(
      Snapshot(
        devices: [SnapshotDevice.iPhoneSE2nd],
      ),
      (widget, device) {
        return MaterialApp(
          debugShowCheckedModeBanner: false,
          theme: ThemeData(
            fontFamily: 'Roboto',
            platform: device.platform,
          ),
          home: widget,
        );
      },
    );
  });
}

配置

pubspec.yaml 可以配置以定义字体文件的位置和快照输出目录路径。

playbook_snapshot:
  fonts:
    - family: Roboto
      fonts:
        - asset: assets/fonts/Roboto-Regular.ttf
  # 默认是/snapshots
  snapshot_dir: iOS
  # 默认为空
  sub_dir: service

根据上述设置，快照将保存在以下目录：

/test/iOS/${DeviceName}/service/${StoryTitle}/${ScenarioTitle}.png

如果你想动态改变路径，可以在Snapshot中使用snapshotDir和subDir参数。

注意事项

Snapshot（内部使用flutter test --update-goldens）需要你自己准备并加载字体。通过在flutter或playbook_snapshot中定义字体文件的位置，并在目录中准备好字体文件，字体文件将自动加载。

flutter:
  fonts:
    - family: Roboto
      fonts:
        - asset: assets/fonts/Roboto-Regular.ttf

或者

playbook_snapshot:
  fonts:
    - family: Roboto
      fonts:
        - asset: assets/fonts/Roboto-Regular.ttf

然后，应准备好字体文件在目录中。

PlaybookGenerator #

支持从任何.dart文件生成故事和场景。

// some_story.dart

const storyTitle = 'Home';

@GenerateScenario(
  layout: ScenarioLayout.fill(),
)
Widget $CategoryHome() => CategoryHome(userData: UserData.stub);

@GenerateScenario(
  layout: ScenarioLayout.fill(),
)
Widget $LandmarkList() => Scaffold(
      appBar: AppBar(),
      body: LandmarkList(userData: UserData.stub),
    );

@GenerateScenario(
  title: 'Container red',
  layout: ScenarioLayout.fixed(100, 100),
)
Widget containerRed() => Container(color: Colors.red);

@GenerateScenario(
  title: 'Device pixel ratio',
  layout: ScenarioLayout.fixed(300, 300),
)
Widget devicePixelRatio(BuildContext context) =>
    Text('Device pixel ratio is ${MediaQuery.of(context).devicePixelRatio}');

你可以引用Playbook实例。

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Playbook Demo',
      theme: ThemeData.light(),
      home: PlaybookGallery(
        title: 'Sample app',
        playbook: playbook,
      ),
    );
  }
}

可以在build.yaml中设置glob以查找资产和输出文件名。默认输入值为lib/**.dart，输出值为generated_playbook.dart。

targets:
  $default:
    builders:
      playbook_generator:stories:
        options:
          input: lib/**.dart
          output: generated_playbook.dart