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

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编写简介

  1. 为什么Induction会的顺序会排在组件stories前面?
    main.ts中的stoires属性值,既声明了需要加载的文件,也声明了加载顺序。
ts 复制代码
const config: StorybookConfig = {
    stories: ['./**/*.mdx', './stories/**/*.@(js|jsx|mjs|ts|tsx)'],
    ...
};
  1. 如何在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等服务器自行部署文件,没有这个问题。

相关推荐
Myli_ing37 分钟前
HTML的自动定义倒计时,这个配色存一下
前端·javascript·html
dr李四维1 小时前
iOS构建版本以及Hbuilder打iOS的ipa包全流程
前端·笔记·ios·产品运营·产品经理·xcode
雯0609~1 小时前
网页F12:缓存的使用(设值、取值、删除)
前端·缓存
℘团子এ1 小时前
vue3中如何上传文件到腾讯云的桶(cosbrowser)
前端·javascript·腾讯云
学习前端的小z1 小时前
【前端】深入理解 JavaScript 逻辑运算符的优先级与短路求值机制
开发语言·前端·javascript
彭世瑜2 小时前
ts: TypeScript跳过检查/忽略类型检查
前端·javascript·typescript
FØund4042 小时前
antd form.setFieldsValue问题总结
前端·react.js·typescript·html
Backstroke fish2 小时前
Token刷新机制
前端·javascript·vue.js·typescript·vue
小五Five2 小时前
TypeScript项目中Axios的封装
开发语言·前端·javascript
小曲程序2 小时前
vue3 封装request请求
java·前端·typescript·vue