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

1. 选型说明

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

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

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

2. 编写storybook

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

2.1 为项目创建storybook

可用脚手架方式创建

npx storybook@latest init --type vue

vue3项目type用vue3

文件目录 新增依赖 新增script
使用storybook创建vue项目组件使用指南 使用storybook创建vue项目组件使用指南 使用storybook创建vue项目组件使用指南

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

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

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

调整后的目录 调整script 调整main.ts
使用storybook创建vue项目组件使用指南 使用storybook创建vue项目组件使用指南 使用storybook创建vue项目组件使用指南

2.2 创建指南首页

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

MDX 官方文档

使用mdx编写简介

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

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

  1. 为什么Induction会的顺序会排在组件stories前面?
    main.ts中的stoires属性值,既声明了需要加载的文件,也声明了加载顺序。
const config: StorybookConfig = {
    stories: ['./**/*.mdx', './stories/**/*.@(js|jsx|mjs|ts|tsx)'],
    ...
};
  1. 如何在stroybook内的文件中访问静态文件? 比如在Introduction中使用图片
  • 直接在代码中通过相对路径引入文件并使用
    使用storybook创建vue项目组件使用指南

  • 使用staticDir,定义静态文件夹
    使用storybook创建vue项目组件使用指南

2.3 编写组件stories

2.3.1 组件参数说明

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

    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: [],
        }
    };
    

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

  • 想要更详细的描述参数,手写props描述

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

  • 手写events描述

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

  • 给props设置默认值

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

  • 参数说明效果图
    使用storybook创建vue项目组件使用指南

2.3.2 添加更多使用示例

    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,
        },
    };

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

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

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函数的监听
    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: [],
        },
    };
    

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

2.4 storybook页面样式调整

  • 新增manage.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,更多配置点这里

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

3. 部署storybook

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

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项目组件使用指南

原文链接:https://juejin.cn/post/7346481513541189667 作者:李向维

(0)
上一篇 2024年3月16日 上午10:38
下一篇 2024年3月16日 上午10:49

相关推荐

发表回复

登录后才能评论