一个用于隔离开发UI组件并自动捕获其快照的库。

Playbook #

Playbook 是一个提供沙箱环境的库，用于构建UI组件时无需担心应用程序特定的依赖项。它深受JavaScript前端开发工具Storybook的启发。

通过使用Playbook构建的组件可以生成独立的应用程序作为动态样式指南。这不仅可以让您快速审查UI，还可以通过将业务逻辑从组件中分离出来交付更健壮的设计。

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

对于复杂的现代应用程序开发来说，在敏感地捕捉UI更改并更快地改进它们方面至关重要。有了Playbook，您无需费力准备数据，也不必花费人力资源进行手动测试。

Playbook #

Playbook 组件以场景的形式唯一存储。一个Scenario定义了组件的布局方式。

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