1. 选型说明

为什么用storybook来创建组件使用指南？我的需求是：

希望组件能交互，便于使用方直观的了解
希望能用md进行文案书写
开箱即用，不用进行二次开发，能快速搭建使用

storybook很好的满足了我的需求，还有其他的能更好的满足需求的工具吗？暂时不知道还有其他的

2. 编写storybook

项目的vue版本为 2.6.11，开发过程中使用的包管理工具为pnpm

2.1 为项目创建storybook

可用脚手架方式创建

sh 复制代码

npx storybook@latest init --type vue

vue3项目type用vue3

文件目录	新增依赖	新增script

启动storybook development server pnpm stroybook，组件的使用手册如下：

我的项目中，希望把storybook相关内容都放到同一个文件夹下，所以调整了配置。

调整后的目录	调整script	调整main.ts

2.2 创建指南首页

Markdown 是一个格式简单的文本编辑工具，MDX 允许您在 Markdown 内部使用交互式代码（JSX）。Storybook Docs 插件使用 MDX 来帮助开发人员控制文档的最终呈现方式。

MDX 官方文档

使用mdx编写简介

为什么Induction会的顺序会排在组件stories前面？
main.ts中的stoires属性值，既声明了需要加载的文件，也声明了加载顺序。

ts 复制代码

const config: StorybookConfig = {
    stories: ['./**/*.mdx', './stories/**/*.@(js|jsx|mjs|ts|tsx)'],
    ...
};

如何在stroybook内的文件中访问静态文件？比如在Introduction中使用图片

直接在代码中通过相对路径引入文件并使用
使用staticDir，定义静态文件夹

2.3 编写组件stories

2.3.1 组件参数说明

引入组件，storybook能根据组件源码自动推断组件参数

ts 复制代码

import { UiXxxCascader } from '../../src';

import type { Meta, StoryObj } from '@storybook/vue';


const meta: Meta<typeof UiXxxCascader> = {
    title: '级联部门选择(UiXxxCascader)',
    component: UiXxxCascader,
    tags: ['autodocs'],
};

type Story = StoryObj<typeof UiDepartmentCascader>;

export const defaultDemo: Story = {
    render: (args, { argTypes }) => ({
        components: { UiXxxCascader },
        props: Object.keys(argTypes),
        template: '<ui-xxx-cascader />',
    }),
    args: {
        value: [],
    }
};

想要更详细的描述参数，手写props描述
手写events描述
给props设置默认值
参数说明效果图

2.3.2 添加更多使用示例

ts 复制代码

    export const SingleChoice: Story = {
        render: (args, { argTypes }) => ({
            components: { UiXxxCascader },
            props: Object.keys(argTypes),
            template: '<ui-xxx-cascader v-bind="$props"/>',
        }),
        args: {
            value: [],
            multiple: false,
            checkStrictly: false,
        },
    };

如果用例比较多，可以使用自定义Template对象，减少代码

ts 复制代码

const Template = (args, { argTypes }) => ({
    components: { UiXxxCascader },
    props: Object.keys(argTypes),
    template: `<ui-xxx-cascader v-bind="$props"
        @change="onChange" 
        @changeCascaderValue="onChangeCascaderValue"/>`,
    methods: {
        onChange: action('change selected value'),
        onChangeCascaderValue: action('change cascader value'),
    },
    args: {
        value: [],
    },
});

export const defaultDemo: Story = Template.bind({});

export const SingleChoice: Story = Template.bind({});
SingleChoice.args = {
    value: [],
    multiple: false,
    checkStrictly: false,
};

2.3.3 展示组件事件交互过程

安装依赖 @storybook/addon-actions
xx.stories.ts中引入依赖
import { action } from '@storybook/addon-actions';

在story中的添加action函数的监听

ts 复制代码

export const defaultDemo: Story = {
    render: (args, { argTypes }) => ({
        components: { UiXxxCascader },
        props: Object.keys(argTypes),
        template: `<ui-xxx-cascader v-bind="$props"
            @change="onChange" 
            @changeCascaderValue="onChangeCascaderValue"/>`,
        methods: {
            onChange: action('change selected value'),
            onChangeCascaderValue: action('change cascader value'),
        }
    }),
    args: {
        value: [],
    },
};

2.4 storybook页面样式调整

新增manage.ts文件，自定义全局样式

ts 复制代码

   # 需要自行安装这两个依赖
  import { addons } from '@storybook/addons';
  import { create } from '@storybook/theming';

  const theme = create({
      base: 'light',// 主题默认dark
      brandTitle: 'ui-xxx-select',
  });

  addons.setConfig({
      theme
  });

我这里主要是想修改左侧里边的系统title，更多配置点这里

3. 部署storybook

storybook 打包后是一些静态文件，可以简单使用gitlab pages来部署文件。 .gitlab-ci.yml中添加配置

yaml 复制代码

pages:
  stage: deploy
  script:
    - pnpm env use --global 16
    - pnpm install
    - pnpm build-storybook
    # 将打包后的storybook-static文件夹挪动到public文件夹
    - mv storybook-static public
  artifacts:
    paths:
      - public
  rules:
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

如果是使用的这种方式部署，建议不要使用staticDir的方式访问静态文件，因为部署到gitlab后，根路径是ui-xx-select，staticDir对应的静态文件访问路径404。如果自己使用ng等服务器自行部署文件，没有这个问题。

使用storybook创建vue项目组件使用指南

1. 选型说明

2. 编写storybook

2.1 为项目创建storybook

2.2 创建指南首页

2.3 编写组件stories

2.3.1 组件参数说明

2.3.2 添加更多使用示例

2.3.3 展示组件事件交互过程

2.4 storybook页面样式调整

3. 部署storybook