Flutter UI组件与样式调试插件dashbook的使用

Dashbook 是一个为Flutter开发的UI开发工具，它既作为项目小部件的开发环境，也作为应用程序中常见小部件的展示平台。Dashbook深受Storybook库的启发，因此对于已经使用过Storybook的人来说，使用Dashbook应该非常容易上手。

如何使用

添加依赖

首先，在pubspec.yaml文件中添加dashbook依赖：

flutter pub add dashbook

创建Dashbook实例

一个Dashbook实例包含了一系列应用的小部件（Stories）及其变体（Chapters）。下面是一个简单的例子：

import 'package:flutter/material.dart';
import 'package:dashbook/dashbook.dart';

void main() {
  final dashbook = Dashbook();

  // Adds the Text widget stories
  dashbook
      .storiesOf('Text')
      .decorator(CenterDecorator())
      .add('default', (ctx) {
        return Container(width: 300, child: Text(
          ctx.textProperty("text", "Text Example"),
          textAlign: ctx.listProperty(
              "text align",
              TextAlign.center,
              TextAlign.values,
          ),
          textDirection: ctx.listProperty(
              "text direction",
              TextDirection.rtl,
              TextDirection.values,
          ),
          style: TextStyle(
              fontWeight: ctx.listProperty(
                  "font weight",
                  FontWeight.normal,
                  FontWeight.values,
              ),
              fontStyle: ctx.listProperty(
                  "font style",
                  FontStyle.normal,
                  FontStyle.values,
              ),
              fontSize: ctx.numberProperty("font size", 20)),
        ));
      });

  dashbook
      .storiesOf('RaisedButton')
      .decorator(CenterDecorator())
      .add('default', (ctx) => ElevatedButton(child: Text('Ok'), onPressed: () {}));

  runApp(dashbook);
}

注意： 在新的Flutter版本中，RaisedButton已经被弃用，推荐使用ElevatedButton。

Actions

Dashbook还提供了一种从其UI调用方法的简单方式，这些回调可以用于需要用户交互的更复杂的示例。 例如，Dialog并不是直接渲染在页面上的东西，而是显示在一个动作之后。以下代码展示了如何在Dashbook中实现一个CustomDialog小部件：

final dashbook = Dashbook();

dashbook
  .storiesOf('CustomDialog')
  .add('default', (ctx) {
    ctx.action('Open dialog', (context) {
      showDialog(
        context: context,
        builder: (_) => CustomDialog(),
      );
    });

    return SizedBox();
  });

示例信息

为了帮助用户更好地理解如何与示例进行互动，可以为示例添加一些指导性文本信息。这可以通过add方法中的info参数来实现：

final dashbook = Dashbook();

dashbook
  .storiesOf('CustomDialog')
  .add('default',
    (ctx) {
      ctx.action('Open dialog', (context) {
        showDialog(
          context: context,
          builder: (_) => CustomDialog(),
        );
      });

      return SizedBox();
    },
    info: 'Use the actions button on the side to show the dialog.',
  );

如果希望直接在预览区域显示信息，可以在add方法中设置pinInfo参数为true。

预览区域

默认情况下，Dashbook会提供整个屏幕区域用于预览。你可以通过设置usePreviewSafeArea参数来改变这种行为，确保控件图标不会覆盖在示例之上。

主题管理

Dashbook提供了三种方式来更改主题：

• 单个主题：使用默认构造函数，并通过可选的theme参数设置主题。
• 双主题：当你的应用程序有两个主题时，可以使用dualTheme构造函数。
• 多主题：当应用程序有多个主题时，可以使用multiTheme构造函数。

可见性控制属性

对于某些复杂的小部件，可能有很多字段，导致属性列表很长，难以理解。通过可见性控制属性API，可以根据其他属性的值来决定某个属性是否显示。

结构建议

虽然没有必须遵循的结构，但推荐的方式是：

• 在项目的根源目录下创建一个名为main_dashbook.dart的文件（例如lib/main_dashbook.dart）。
• 在该文件中创建Dashbook实例，并在最后调用runApp方法。
• 使用命令flutter run -t lib/main_dashbook.dart运行它。

完整示例

这里给出一个完整的示例，包括了文本、按钮、对话框等元素，以及主题切换的功能：

import 'package:dashbook/dashbook.dart';
import 'package:flutter/material.dart';

void main() {
  final dashbook = Dashbook.dualTheme(
    light: ThemeData.light(),
    dark: ThemeData.dark(),
    title: 'Dashbook Example',
    autoPinStoriesOnLargeScreen: true,
  );

  // Adding a simple text story with multiple properties
  dashbook.storiesOf('Text Widget')
      .decorator(CenterDecorator())
      .add('Default', (ctx) {
    return Container(
      width: 300,
      child: Text(
        ctx.textProperty("text", "Hello World"),
        textAlign: ctx.listProperty("text align", TextAlign.left, TextAlign.values),
        textDirection: ctx.listProperty("text direction", TextDirection.ltr, TextDirection.values),
        style: TextStyle(
          fontWeight: ctx.listProperty("font weight", FontWeight.normal, FontWeight.values),
          fontStyle: ctx.listProperty("font style", FontStyle.normal, FontStyle.values),
          fontSize: ctx.numberProperty("font size", 20),
        ),
      ),
    );
  }, info: 'This is an example of how to use the Text widget in Dashbook.');

  // Adding a button story
  dashbook.storiesOf('ElevatedButton')
      .decorator(CenterDecorator())
      .add('Default', (ctx) => ElevatedButton(child: Text('Click me'), onPressed: () {}));

  // Adding a dialog story with action
  dashbook.storiesOf('CustomDialog')
      .add('Default', (ctx) {
    ctx.action('Open dialog', (context) {
      showDialog(
        context: context,
        builder: (_) => AlertDialog(
          title: Text('Alert'),
          content: Text('This is a custom dialog.'),
          actions: [
            TextButton(
              child: Text('OK'),
              onPressed: () => Navigator.of(context).pop(),
            )
          ],
        ),
      );
    });

    return SizedBox();
  }, info: 'Use the actions button on the side to open the dialog.', pinInfo: true);

  runApp(dashbook);
}

这个示例涵盖了基本的文本、按钮和对话框的创建，并且展示了如何使用Dashbook的各种特性来增强开发体验。