Vant-cli 有赞出品 Vue 组件库构建工具 - 文章教程

Vant-cli 有赞出品 Vue 组件库构建工具

发布于 2021-09-20 字数 16665 浏览 1074 评论 0

Vant Cli 是一个 Vue 组件库构建工具,通过 Vant Cli 可以快速搭建一套功能完备的 Vue 组件库。

特性

  • 提供丰富的命令,涵盖从开发测试到构建发布的完整流程
  • 基于约定的目录结构,自动生成优雅的文档站点和组件示例
  • 内置 ESlint、Stylelint 校验规则,提交代码时自动执行校验
  • 构建后的组件库默认支持按需引入、主题定制、Tree Shaking

快速上手

执行以下命令可以快速创建一个基于 Vant Cli 的项目:

yarn create vant-cli-app

手动安装

# 通过 npm 安装
npm i @vant/cli -D

# 通过 yarn 安装
yarn add @vant/cli --dev

安装完成后,请将以下配置添加到 package.json 文件中

{
  "scripts": {
    "dev": "vant-cli dev",
    "test": "vant-cli test",
    "lint": "vant-cli lint",
    "build": "vant-cli build",
    "prepare": "husky install",
    "release": "vant-cli release",
    "build-site": "vant-cli build-site"
  },
  "lint-staged": {
    "*.md": "prettier --write",
    "*.{ts,tsx,js,vue,less,scss}": "prettier --write",
    "*.{ts,tsx,js,vue}": "eslint --fix",
    "*.{vue,css,less,scss}": "stylelint --fix"
  },
  "eslintConfig": {
    "root": true,
    "extends": ["@vant"]
  },
  "stylelint": {
    "extends": ["@vant/stylelint-config"]
  },
  "prettier": {
    "singleQuote": true
  },
  "browserslist": ["Chrome >= 51", "iOS >= 10"]
}

命令

Vant Cli 中内置了一系列的命令,可以将命令添加到 npm scripts 中进行使用。

// package.json
{
  "scripts": {
    "dev": "vant-cli dev",
    "test": "vant-cli test",
    "lint": "vant-cli lint",
    "release": "vant-cli release",
    "build-site": "vant-cli build-site"
  }
}

也可以通过 npm 自带的 npx 直接执行某个命令:

npx vant-cli dev

dev

运行本地开发环境。

运行 dev 命令时,Vant Cli 会通过 webpack-dev-server 启动一个本地服务器,用于在开发过程中对文档和示例进行预览。

build

构建组件库。

运行 build 命令会在 eslib 目录下生成可用于生产环境的组件代码,详见 目录结构

发布 npm 时,请将以下配置加入到 package.json 中,使 npm 包能被正确识别:

// package.json
{
  "main": "lib/index.js",
  "module": "es/index.js",
  "files": ["es", "lib"]
}

build-site

构建文档站点,在 site 目录生成可用于生产环境的文档站点代码。

release

发布组件库,发布前会自动执行 build 和 changelog 命令,并通过 release-it 发布 npm 包。

changelog

基于 commit 记录生成更新日志,基于 conventional-changelog 实现。

commit-lint

校验 commit message 的格式是否符合规范,需要配合 husky 在提交 commit 时触发。

npx husky add .husky/commit-msg 'npx --no-install vant-cli commit-lint $1'

配置指南

vant.config.js

vant.config.js中包含了vant-cli的打包配置和文档站点配置,请创建此文件并置于项目根目录下。下面是一份基本配置的示例:

module.exports = {
  // 组件库名称
  name: 'demo-ui',
  // 构建配置
  build: {
    site: {
      publicPath: '/demo-ui/',
    },
  },
  // 文档站点配置
  site: {
    // 标题
    title: 'Demo UI',
    // 图标
    logo: 'https://img.yzcdn.cn/vant/logo.png',
    // 描述
    description: '示例组件库',
    // 左侧导航
    nav: [
      {
        title: '开发指南',
        items: [
          {
            path: 'home',
            title: '介绍',
          },
        ],
      },
      {
        title: '基础组件',
        items: [
          {
            path: 'my-button',
            title: 'MyButton 按钮',
          },
        ],
      },
    ],
  },
};

name

  • Type: string
  • Default: ''

组件库名称,建议使用中划线分割,如demo-ui

build.css

  • Type: object
  • Default: { preprocessor: 'less' }

CSS 预处理器配置,目前支持lesssass两种预处理器,默认使用less

module.exports = {
  build: {
    css: {
      preprocessor: 'sass',
    },
  },
};

build.site.publicPath

  • Type: string
  • Default: /

等价于 vite 的 build.outDir 配置。

一般来说,我们的文档网站会部署在一个域名的子路径上,如 https://my.github.io/demo-ui/,这时候 publicPath 需要跟子路径保持一致,即 /demo-ui/

module.exports = {
  build: {
    site: {
      publicPath: '/demo-ui/',
    },
  },
};

build.srcDir

  • Type: string
  • Default: src
module.exports = {
  build: {
    srcDir: 'myDir',
  },
};

build.namedExport

  • Type: boolean
  • Default: false

是否通过 Named Export 对组件进行导出。

未开启此选项时,会通过 export default from 'xxx' 导出组件内部的默认模块。

开启此选项后,会通过 export * from 'xxx' 导出组件内部的所有模块、类型定义。

site.title

  • Type: string
  • Default: ''

文档站点的标题。

site.logo

  • Type: string
  • Default: ''

文档站点的 Logo。

site.description

  • Type: string
  • Default: ''

标题下方的描述文案。

site.nav

  • Type: object[]
  • Default: undefined

文档站点的左侧导航,数组中的每个对象表示一个导航分组。

module.exports = {
  site: {
    nav: [
      {
        // 分组标题
        title: '开发指南',
        // 导航项
        items: [
          {
            // 导航项路由
            path: 'home',
            // 导航项文案
            title: '介绍',
            // 是否隐藏当前页右侧的手机模拟器(默认不隐藏)
            hideSimulator: true,
          },
        ],
      },
    ],
  },
};

site.versions

  • Type: object[]
  • Default: undefined

文档站点多版本配置,当组件库存在多个版本的文档时,可以通过site.versions在顶部导航配置一个版本切换按钮。

module.exports = {
  site: {
    versions: [
      {
        label: 'v1',
        link: 'https://youzan.github.io/vant/v1/',
      },
    ],
  },
};

site.baiduAnalytics

  • Type: object
  • Default: undefied

文档网站的百度统计配置,添加这项配置后,会自动在构建文档网站时加载百度统计的脚本。

module.exports = {
  site: {
    baiduAnalytics: {
      // 打开百度统计 ->『管理』->『代码获取』
      // 找到下面这串 URL: "https://hm.baidu.com/hm.js?xxxxx"
      // 将 `xxxxx` 填写在 seed 中即可
      seed: 'xxxxx',
    },
  },
};

site.searchConfig

  • Type: object
  • Default: undefined

文档网站的搜索配置,基于 algolia 提供的 docsearch 服务实现。

配置内容参见 docsearch

site.hideSimulator

  • Type: boolean
  • Default: false

是否隐藏所有页面右侧的手机模拟器,默认不隐藏

site.simulator.url

  • Type: string
  • Default: –

自定义手机模拟器的 iframe URL 地址。

site.htmlMeta

  • Type: Record<string, string>
  • Default: undefined

配置 HTML 中的 meta 标签,对象的 key 为 name,value 为 content。

site.enableVConsole

  • Type: boolean
  • Default: false

是否在 dev 时开启 vConsole 调试,用于移动端 debug。

Babel

通过根目录下的babel.config.js文件可以对 Babel 进行配置。

默认配置

推荐使用vant-cli内置的 preset,配置如下:

module.exports = {
  presets: ['@vant/cli/preset'],
};

@vant/cli/preset中默认包含了以下插件:

  • @babel/preset-env(不含 core-js)
  • @babel/preset-typescript
  • @babel/plugin-transform-object-assign
  • @babel/plugin-proposal-optional-chaining
  • @babel/plugin-proposal-nullish-coalescing-operator
  • @vue/babel-preset-jsx

Postcss

通过根目录下的postcss.config.js文件可以对 Postcss 进行配置。

默认配置

vant-cli中默认的 Postcss 配置如下:

module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

browserslist

推荐在package.json文件里添加 browserslist 字段,这个值会被@babel/preset-envautoprefixer用来确定目标浏览器的版本,保证编译后代码的兼容性。

在移动端浏览器中使用,可以添加如下配置:

{
  "browserslist": ["Chrome >= 51", "iOS >= 10"]
}

目录结构

源代码目录

基于 Vant Cli 搭建的组件库的基本目录结构如下所示:

project
├─ src                # 组件源代码
│   ├─ button        # button 组件源代码
│   └─ dialog        # dialog 组件源代码
│
├─ docs               # 静态文档目录
│   ├─ home.md       # 文档首页
│   └─ changelog.md  # 更新日志
│
├─ babel.config.js    # Babel 配置文件
├─ vant.config.js     # Vant Cli 配置文件
├─ package.json
└─ README.md

单个组件的目录如下:

button
├─ demo             # 示例目录
│   └─ index.vue   # 组件示例
├─ index.vue        # 组件源码
└─ README.md        # 组件文档

使用 .vue 文件编写组件时,编译后会生成对应的 JS 和 CSS 文件,且 JS 文件中会自动引入 CSS 文件。

如果需要将 JS 和 CSS 解耦,实现主题定制等功能,在编写代码时就要使用独立的 JS 和 CSS 文件,如下所示:

button
├─ demo             # 组件示例
│   └─ index.vue   # 组件示例入口
├─ index.js         # 组件入口
├─ index.less       # 组件样式,可以为 less 或 scss
└─ README.md        # 组件文档

采用这种目录结构时,组件的使用者需要分别引入 JS 和 CSS 文件,也可以通过 babel-plugin-import 自动引入样式。

通过引入样式源文件(less 或 scss)并修改样式变量,可以实现主题定制功能。

构建结果目录

运行 build 命令会在 eslib 目录下生成可用于生产环境的组件代码,结构如下:

project
├─ es                   # es 目录下的代码遵循 esmodule 规范
│   ├─ button          # button 组件编译后的代码目录
│   ├─ dialog          # dialog 组件编译后的代码目录
│   └─ index.js        # 引入所有组件的入口 (ESModule)
│
└─ lib                  # lib 目录下的代码遵循 commonjs 规范
    ├─ button           # button 组件编译后的代码目录
    ├─ dialog           # dialog 组件编译后的代码目录
    ├─ index.js         # 引入所有组件的入口
    ├─ index.less       # 所有组件未编译的样式入口
    ├─ index.css        # 打包后的组件样式,用于 CDN 引入
    ├─ [name].js        # 打包后的组件脚本,UMD 格式
    ├─ [name].es.js     # 打包后的组件脚本,ESModule 格式
    ├─ [name].min.js    # 打包和压缩后的组件脚本,UMD 格式
    └─ [name].es.min.js # 打包和压缩后的组件脚本,ESModule 格式

单个组件编译后的目录如下:

button
├─ index.js         # 组件编译后的 JS 文件
├─ index.css        # 组件编译后的 CSS 文件
├─ index.less       # 组件编译前的 CSS 文件,可以为 less 或 scss
└─ style            # 按需引入样式的入口
    ├─ index.js     # 按需引入编译后的样式
    └─ less.js      # 按需引入未编译的样式,可用于主题定制

生成类型声明

当组件库使用 TS 编写,且根目录下存在 tsconfig.declaration.json 文件,Vant Cli 会自动生成 .d.ts 类型声明文件。

tsconfig.declaration.json 的参考格式如下:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "declarationDir": ".",
    "emitDeclarationOnly": true
  },
  "include": ["es/**/*", "lib/**/*"],
  "exclude": ["node_modules", "**/test/**/*", "**/demo/**/*"]
}

成功生成类型声明后,请在 package.json 中添加类型入口声明:

{
  "typings": "lib/index.d.ts"
}

关于桌面端组件

Vant Cli 也支持预览桌面端组件,你可以在组件的 demo 目录下新建一个 .vue 文件,并在组件的 README 中按如下格式声明要预览的组件:

<demo-code>./demo/MyDemo.vue</demo-code>

demo-code 标签中间的文本为 READMEdemo 文件的相对路径。

button
├─ demo             # 组件示例
│   └─ MyDemo.vue   # 要预览的 demo 文件
├─ index.js         # 组件入口
├─ index.less       # 组件样式
└─ README.md        # 组件文档

Vant-cli 有赞出品 Vue 组件库构建工具

demo-code 标签支持以下属性:

名称 类型 描述
compact boolean 紧凑模式
transform boolean 防止预览区内 fixed 定位的元素飞出预览区
inline boolean 只显示组件本身,不显示预览区边框和代码

compact

<demo-code compact>./demo/MyDemo.vue</demo-code>

Vant-cli 有赞出品 Vue 组件库构建工具

transform

<demo-code transform>./demo/MyDemo.vue</demo-code>

Vant-cli 有赞出品 Vue 组件库构建工具

inline

<demo-code inline>./demo/MyDemo.vue</demo-code>

Vant-cli 有赞出品 Vue 组件库构建工具

去除手机模拟器

对于 PC 端的组件,如果不需要右侧的手机模拟器,可以在 vant.config.js 文件中设置 site.hideSimulatortrue,这样在所有页面都会隐藏手机模拟器,也可以只针对具体页面设置。

module.exports = {
  site: {
    defaultLang: 'zh-CN',
    hideSimulator: true, // 所有页面都不显示
    locales: {
      'zh-CN': {
        title: 'Vant',
        description: '轻量、可靠的移动端 Vue 组件库',
        hideSimulator: true, // 中文下所有页面都不显示
        nav: [
          {
            title: '基础组件',
            items: [
              {
                path: 'button',
                title: 'Button 按钮',
                hideSimulator: true, // 只针对某个页面不显示
              },
            ],
          },
        ],
      },
    },
  },
};

项目地址:https://github.com/youzan/vant/blob/dev/packages/vant-cli

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2512 文章
30 评论
83580 人气
更多

推荐作者

魏剑帆

文章 0 评论 0

yanggwq

文章 0 评论 0

qq_c2gI5

文章 0 评论 0

qq_iQVWB

文章 0 评论 0