发布于 由admin

如何利用 Storybook 或类似工具为 Vue 组件库构建交互式文档和组件展示？

大家好，我是你们的组件宇宙导游，今天咱们来聊聊如何用 Storybook 搭建 Vue 组件库的交互式文档和组件展示平台。这玩意儿就像给你的组件们建个豪华展厅，让大家一目了然，还能动手体验，简直是开发、测试、文档的福音。

第一站：Storybook 是个啥？

简单来说，Storybook 是一个开源的 UI 组件开发环境。它允许你在隔离的环境下开发和展示 UI 组件，不受应用逻辑的干扰。想象一下，你搭了个透明玻璃房，专门展示你的 Vue 组件，还能让大家在里面随便摆弄，看看效果如何。

第二站：准备工作，磨刀不误砍柴工

  1. 安装 Vue CLI (如果还没装的话):

    npm install -g @vue/cli
# 或者
yarn global add @vue/cli

  2. 创建一个 Vue 项目 (如果还没有组件库):

    vue create my-component-library
cd my-component-library

  3. 安装 Storybook:

    npx sb init
# 或者
yarn add @storybook/cli
yarn storybook init

    这个 sb init 命令会自动检测你的项目类型，并安装必要的 Storybook 依赖和配置。它会添加一些示例 stories，让你先睹为快。

第三站：组件登场，编写你的第一个 Story

假设我们有一个简单的 Vue 组件 MyButton.vue:

<template>
  <button :class="classes" @click="$emit('click')">
    {{ label }}
  </button>
</template>

<script>
export default {
  name: 'MyButton',
  props: {
    label: {
      type: String,
      default: 'Click me!'
    },
    primary: {
      type: Boolean,
      default: false
    },
    size: {
      type: String,
      default: 'medium',
      validator: (value) => ['small', 'medium', 'large'].includes(value)
    }
  },
  computed: {
    classes() {
      return [
        'my-button',
        `my-button--${this.size}`,
        { 'my-button--primary': this.primary }
      ];
    }
  }
};
</script>

<style scoped>
.my-button {
  border: none;
  padding: 10px 20px;
  border-radius: 5px;
  cursor: pointer;
}

.my-button--primary {
  background-color: blue;
  color: white;
}

.my-button--small {
  font-size: 0.8em;
  padding: 5px 10px;
}

.my-button--medium {
  font-size: 1em;
  padding: 10px 20px;
}

.my-button--large {
  font-size: 1.2em;
  padding: 15px 30px;
}
</style>

接下来，我们需要为这个组件创建一个 Story。在 src/stories 目录下（或者你自定义的目录），创建一个 MyButton.stories.js 文件：

import MyButton from '../src/components/MyButton.vue'; // 确保路径正确

export default {
  title: 'Components/MyButton', // Storybook 中组件的分类和名称
  component: MyButton, // 关联的 Vue 组件
  argTypes: { // 定义组件的 props 如何在 Storybook 中控制
    label: { control: 'text' },
    primary: { control: 'boolean' },
    size: { control: { type: 'select', options: ['small', 'medium', 'large'] } },
    click: { action: 'clicked' }, // 模拟事件，并在 Storybook 界面中显示触发
  },
};

const Template = (args) => ({
  components: { MyButton },
  setup() {
    return { args };
  },
  template: '<my-button v-bind="args" @click="args.click" />',
});

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Primary Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Secondary Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Small Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Large Button',
};

代码解读：

  • title: 定义了 Storybook 中组件的分类和名称，方便组织和查找。
  • component: 指定了要展示的 Vue 组件。
  • argTypes: 定义了组件的 props 如何在 Storybook 中控制。control 属性指定了控制器的类型，例如 text (文本输入框), boolean (复选框), select (下拉选择框)。action 用于模拟事件，并在 Storybook 界面中显示触发信息。
  • Template: 一个函数，用于渲染组件。它接收 args (参数) 作为输入，并将这些参数绑定到组件的 props 上。
  • Primary, Secondary, Small, Large: 不同的 Story，每个 Story 都是 Template 函数的一个绑定版本，并设置了不同的 args。

第四站：启动 Storybook，看看效果

在你的项目根目录下运行：

npm run storybook
# 或者
yarn storybook

这会启动 Storybook 服务器，并在浏览器中打开一个页面，展示你的组件和 stories。你应该能看到 MyButton 组件，以及 Primary, Secondary, Small, Large 这几个不同的变体。你可以在 Storybook 界面中修改 props 的值，实时查看组件的变化。

第五站：进阶技巧，让你的 Storybook 更上一层楼

  1. 使用 Addons 增强功能:

    Storybook 有很多 Addons 可以扩展其功能，例如：

    • @storybook/addon-knobs: 允许你在 Storybook 界面中动态修改 props 的值。 (已经废弃，推荐使用 argTypes 和 controls)
    • @storybook/addon-viewport: 模拟不同的设备屏幕尺寸。
    • @storybook/addon-docs: 自动生成组件文档。
    • @storybook/addon-a11y: 检查组件的可访问性。
    • @storybook/addon-jest: 集成 Jest 测试。

    安装 Addon 的方法：

    npm install @storybook/addon-viewport
# 或者
yarn add @storybook/addon-viewport

    然后在 .storybook/main.js 文件中注册 Addon:

    module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-viewport', // 注册 viewport addon
    '@storybook/addon-a11y',
    //'@storybook/addon-knobs', // 不推荐使用
  ],
  framework: '@storybook/vue3',
  core: {
    builder: '@storybook/builder-webpack5',
  },
  features: {
    interactionsDebugger: true,
  },
};

  2. 使用 MDX 文档:

    MDX 允许你在 Markdown 文件中编写 Vue 组件，这样你可以将文档和组件展示紧密结合。

    首先，安装 @storybook/addon-docs:

    npm install @storybook/addon-docs
# 或者
yarn add @storybook/addon-docs

    确保 addon-docs 已经添加到 .storybook/main.js 的 addons 数组中。

    然后，创建一个 MyButton.stories.mdx 文件:

    import { Meta, Story } from '@storybook/addon-docs';
import MyButton from '../src/components/MyButton.vue';

<Meta title="Components/MyButton" component={MyButton} />

# MyButton

这是一个按钮组件。

<Story name="Primary">
  <MyButton primary label="Primary Button" />
</Story>

<Story name="Secondary">
  <MyButton label="Secondary Button" />
</Story>

    在 .storybook/main.js 中，确保你的 stories 匹配 MDX 文件:

    module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  // ...
};

  3. 配置 Webpack:

    如果你的组件库使用了特殊的 CSS 预处理器 (例如 Sass, Less) 或需要自定义 Webpack 配置，你可以在 .storybook/main.js 文件中进行配置。

    module.exports = {
  // ...
  webpackFinal: async (config, { configType }) => {
    // `configType` has a value of 'DEVELOPMENT' or 'PRODUCTION'
    // You can change the configuration based on that.
    // 'PRODUCTION' is used when building the static version of storybook.

    // Make whatever fine-grained changes you need
    config.module.rules.push({
      test: /.scss$/,
      use: ['style-loader', 'css-loader', 'sass-loader'],
      include: path.resolve(__dirname, '../'),
    });

    // Return the altered config
    return config;
  },
};

  4. 发布 Storybook:

    你可以将 Storybook 部署到 GitHub Pages, Netlify, Vercel 等平台，方便团队成员和用户查看你的组件库文档。 使用 npm run build-storybook 或者 yarn build-storybook 命令生成静态文件，然后将这些文件部署到你的服务器上。

第六站：最佳实践，让你的组件库更受欢迎

  • 详细的文档: 为每个组件编写清晰、详细的文档，包括 props 的说明、使用示例、注意事项等。
  • 丰富的示例: 提供多种不同的示例，展示组件的各种用法和变体。
  • 可访问性: 确保你的组件符合可访问性标准，让所有用户都能使用。
  • 自动化测试: 集成 Jest 或其他测试框架，编写单元测试和集成测试，确保组件的质量。
  • 定期维护: 定期更新 Storybook 和组件库，修复 bug，添加新功能。

总结：

Storybook 是一个强大的工具，可以帮助你构建、测试和文档化 Vue 组件库。通过合理地使用 Storybook，你可以提高开发效率，改善组件质量，并为用户提供更好的体验。 记住，组件库的建设是一个持续迭代的过程，不断学习和尝试，才能打造出优秀的组件库。

一个表格示例：Props 定义

Prop Name Type Default Description
label String ‘Click me!’ 按钮上显示的文本。
primary Boolean false 是否是主要按钮。如果是，则使用不同的样式。
size String ‘medium’ 按钮的大小。可选值：’small’, ‘medium’, ‘large’。
disabled Boolean false 是否禁用按钮。
icon String null 按钮上显示的图标的名称 (例如 FontAwesome 图标)。

记住，这只是个开始。 Storybook 的世界广阔无垠，还有很多东西值得探索。 祝你的组件宇宙之旅愉快！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注