如何開發和發佈一個Vue插件

時間 2020-03-11

標籤如何開發發佈一個 vue 插件简体版

原文原文鏈接

前言

Vue 項目開發過程當中，常常用到插件，好比原生插件 vue-router、vuex，還有 element-ui 提供的 notify、message 等等。這些插件讓咱們的開發變得更簡單更高效。那麼 Vue 插件是怎麼開發的呢？如何本身開發一個 Vue 插件而後打包發佈到npm？javascript

本文涉及技術點：css

Vue 插件的本質
Vue.extend() 全局方法
如何手動掛載 Vue 實例
Vue.use() 的原理
如何打包成 umd 格式
發佈前如何測試 npm 包

1、定義

什麼是Vue插件，它和Vue組件有什麼區別？來看一下官網的解釋：html

「插件一般用來爲 Vue 添加全局功能。」
「組件是可複用的 Vue 實例，且帶有一個名字。」
—— Vue.js 官網前端

Emmmm，彷佛好像有種朦朧美。。。vue

我來嘗試解釋一下，其實， Vue 插件 和 Vue組件 只是在 Vue.js 中包裝的兩個概念而已，不論是插件仍是組件，最終目的都是爲了實現邏輯複用。它們的本質都是對代碼邏輯的封裝，只是封裝方式不一樣而已。在必要時，組件也能夠封裝成插件，插件也能夠改寫成組件，就看實際哪一種封裝更方便使用了。java

除此以外，插件是全局的，組件能夠全局註冊也能夠局部註冊。webpack

咱們今天只聚焦 Vue 插件。git

插件通常有下面幾種：github

添加全局方法或者屬性。如: vue-custom-element

添加全局資源：指令/過濾器/過渡等。如 vue-touch

經過全局混入來添加一些組件選項。如 vue-router

添加 Vue 實例方法，經過把它們添加到 Vue.prototype 上實現。

一個庫，提供本身的 API，同時提供上面提到的一個或多個功能。如 vue-router
—— Vue.js 官網

2、插件的使用

插件須要經過 Vue.use() 方法註冊到全局，而且須要在調用 new Vue() 啓動應用以前完成。以後在其餘 Vue 實例裏面就能夠經過 this.$xxx 來調用插件中提供的 API 了。web

下面以實現一個簡易的提示框插件 toast 爲例，給你們介紹怎麼一步一步開發和發佈一個 Vue 插件。

但願達到的效果：
在 main.js 中 use：

// src/main.js
import Vue from 'vue'
import toast from '@champyin/toast'

Vue.use(toast)

在 App.vue 的生命週期 mounted 方法裏調用 this.$toast()： ```vue // src/App.vue <template> <div> <button @click='handleClick'>Toast</button> </div> </template> <script> export default { name: 'demo', methods: { handleClick() { this.$toast({
type: 'success',
msg: '成功',
duration: 3
})
}
}
}

``運行後在頁面上點擊按鈕，彈出成功` 的提示，而後3秒後消失。

在線體驗地址：http://champyin.com/toast/

3、插件開發

1. 編寫 toast 的本體。

在 Vue 項目（你可使用 Vue-cli 快速生成一個 Vue 項目，也能夠本身用 webpack 搭建一個）的 src 目錄下建立 components/Toast/index.vue 文件。

// src/components/Toast/index.vue
<template>
  <transition name='fade'>
    <div class='uco-toast' v-if='isShow'>
      <span :class='iconStyle'></span>
      <span>{{msg}}</span>
    </div>
  </transition>
</template>

<script>
export default {
  data() {
    return {
      isShow: false,
      type: 'success',
      msg: '成功',
      duration: 1,
    };
  },
  computed: {
    iconStyle() {
      return `tfont icon-${this.type} toast-icon`;
    },
  },
  mounted() {
    this.isShow = true;
    setTimeout(() => {
      this.isShow = false;
    }, this.duration * 1000);
  },
};
</script>

<style lang='less' scoped>
// 樣式略
</style>

如今 toast 本體完成了，可是它裏面的數據目前無法改變，由於我沒有給它定義 props 屬性。這不是 bug，而是，插件並非經過 pops 來傳值的。

2. 手動掛載 toast 實例的 dom

爲了給插件傳值，能夠利用基礎 Vue 構造器 Vue.extend() 建立一個「子類」。這個子類至關於一個繼承了 Vue 的 Toast 構造器。而後在 new 這個構造函數的時候，給 Toast 的 data 屬性傳值，而後手動調用這個實例的 $mount() 方法手動掛載，最後使用原生JS的 appendChild 將真實 DOM （經過實例上的 $el 屬性獲取）添加到 body 上。

在 src 目錄下新建 components/Toast/index.js 文件：

// src/components/Toast/index.js
import Vue from 'vue';
import Toast from './index.vue';

// 使用 Vue.extend() 建立 Toast 的構造器
const ToastConstructor = Vue.extend(Toast);

const toast = function(options = {}) {
    // 建立 Toast 實例，經過構造函數傳參，
    // 並調用 Vue 實例上的 $mount() 手動掛載
    const toastInstance = new ToastConstructor({
        data: options
    }).$mount();

    // 手動把真實 dom 掛到 html 的 body 上
    document.body.appendChild(toastInstance.$el);

    return toastInstance;
};

// 導出包裝好的 toast 方法
export default toast;

3. 暴露 install 方法給 Vue.use() 使用。

爲了支持 Vue.use()，Vue.js 的插件應該暴露一個 install 方法。這個方法的第一個參數是 Vue 構造器，第二個參數是一個可選的選項對象。
—— Vue.js 官網

經過 Vue.js 源碼也能夠看出，Vue.use() 方法所作的事情就是調用插件或者組件的 install 方法，而後把全局 Vue 傳進去供插件和組件使用。

// https://github.com/vuejs/vue/blob/dev/src/core/global-api/use.js
/* @flow */

import { toArray } from '../util/index'

export function initUse (Vue: GlobalAPI) {
  Vue.use = function (plugin: Function | Object) {
    const installedPlugins = (this._installedPlugins || (this._installedPlugins = []))
    if (installedPlugins.indexOf(plugin) > -1) {
      return this
    }

    // additional parameters
    const args = toArray(arguments, 1)
    args.unshift(this)
    if (typeof plugin.install === 'function') {
      plugin.install.apply(plugin, args)
    } else if (typeof plugin === 'function') {
      plugin.apply(null, args)
    }
    installedPlugins.push(plugin)
    return this
  }
}

在 src 目錄下新建 components/index.js 文件，定義一個 install 方法，在裏面將 toast 實例放到 Vue.prototype 上做爲 Vue 實例的方法暴露到全局。

// src/components/index.js
import toast from './Toast/index';
import '../icon/iconfont.css';

// 準備好 install 方法 給 Vue.use() 使用
const install = function (Vue) {
  if (install.installed) return;
  install.installed = true;

  // 將包裝好的 toast 掛到Vue的原型上，做爲 Vue 實例上的方法
  Vue.prototype.$toast = toast;
}

// 默認導出 install
export default {
  install,
};

如今插件就開發完成了，能夠在當前項目中本地引用這個插件了。

//在 main.js 中
import toast from src/components/index.js;
Vue.use(toast);

//在 App.vue 中
handleClick(){
  this.$toast();
}

4、發佈到npm

爲了方便其餘人也可使用到這個插件，咱們能夠把它發佈到 npm 上去。發佈的步驟很簡單，可是發佈以前，須要有一些小配置和一些注意的地方。

1. 打包配置

首先咱們要把它打包成能夠給瀏覽器解析的 UMD 格式的的模塊，而且去掉對 Vue.js 的打包，這樣別人在 Vue 項目中使用這個插件的時候就不會有兩份 Vue 或者出現 Vue 版本衝突的問題，以保證能夠更好被獨立引用。

若是你是用 Vue-cli 生成的項目，那隻須要在你的 npm 腳本中配置一下庫的打包命令：

// package.json
"build:lib": "vue-cli-service build --target lib --name toast --dest lib  src/components/index.js"

命令說明：

--target：構建的目標
          targetType 有三個選項：lib | wc | wc-async
          lib：庫
          wc：web component
          wc-async：異步的 web component

--name：庫或組件的名字
          當入口爲單一文件時，name爲庫或組件的文件名
          當入口爲global表達式時，name爲每一個庫或組件文件名字的前綴

[entry]：打包入口
          能夠是.vue文件，也能夠是.js文件
          當註冊多個web component時，入口能夠是一個global表達式，如 components/*.vue

--dest：輸出目錄
          默認爲dist目錄，也能夠修改成自定義的目錄

而後運行 npm run build:lib，便可在 lib 目錄下生成以下文件：

toast.umd.js 一個直接給瀏覽器或者AMD loader 使用的 UMD 包
toast.umd.min.js 一個壓縮版 UMD 構建版本
toast.common.js 一個給打包器用的CommonJS包

若是你是用 webpack 搭建的 Vue 項目，那就須要在 webpck 中配置一下 output.libraryTarget 等屬性：

// build/webpack.lib.conf.js
const path = require('path');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: './src/components/index.js',
  output: {
    path: path.resolve(__dirname, '../lib'),
    filename: 'toast.js',
    library: 'toast',
    libraryTarget: 'umd',
    libraryExport: 'default',
    umdNamedDefine: true,
    globalObject: 'typeof self !== \'undefined\' ? self : this',
  },
  externals: {
    vue: {
      root: 'Vue',
      commonjs: 'vue',
      commonjs2: 'vue',
      amd: 'vue',
    },
  },
  plugins: [
    new CleanWebpackPlugin(),
  ],
};

而後運行 npm run build:lib，便可在 lib 目錄下生成以下文件：

toast.js 直接給瀏覽器或者AMD loader 使用的 UMD 包

2. 發佈前的測試

發佈前，咱們須要配置一下 package.json 裏的 name 和 main 字段：
name 的值是最終包的名字，install 和 import 的就是這個名字（請確保全網惟一）。
main 的值是包的入口文件路徑（相對當前文件的路徑），必定要填寫正確，不然包沒法被引用。

"name": "@champyin/toast",
"main": "lib/toast.js",

爲了確保包的配置沒有問題，咱們能夠利用 npm link 命令在本地測試一下包的使用狀況。使用npm link測試包的使用估計不少人都會，就不贅述了。若是有須要能夠看個人另外一篇中文章npm link詳解。

這個時候，咱們其實就能夠發佈了，可是爲了防止把沒必要要的文件發佈出去（好比測試用例和demo）浪費人家下載的流量，咱們最好是建一個 .npmigore 文件，語法跟 .gitignore 相同。

3. 發佈

發佈的方法很簡單(不過首先你要有個 npm 帳號)，在 package.json 所在的目錄下執行這兩句就能夠了：

npm add user
npm publish

關於更詳細的發佈教程，我在另外一篇文章有專門細說：如何發佈一個npm模塊。

4. 安裝測試

其實到了這一步一99.99%是不會出錯了，安裝一遍只是爲了那 0.01% 的萬一。

在另外一個 Vue 項目裏（注意不能在開發toast的項目裏哈），從 npm 安裝本身剛纔發佈的包：

npm i -D @champyin/toast

而後在項目中使用一下本身的插件，點擊按鈕就會彈出 toast 小提示了。

//在 main.js 中
import toast from '@champyin/toast';
Vue.use(toast);

//在 App.vue 中
handleClick(){
  this.$toast();
}

項目體驗地址：http://champyin.com/toast/
npm 地址：https://www.npmjs.com/package/@champyin/toast
歡迎給我提 issue：https://github.com/yc111/toast/issues

Happy coding :)

文章同時發表於公衆號「前端手札」，喜歡的話能夠關注一下哦。

更多參考：
https://cn.vuejs.org/v2/guide/plugins.html
https://cn.vuejs.org/v2/api/#Vue-extend-options
https://cli.vuejs.org/zh/guide/build-targets.html
https://webpack.js.org/guides/author-libraries/
https://docs.npmjs.com/cli-commands/link.html
https://docs.npmjs.com/cli-commands/pack.html
https://www.npmjs.com/package/@champyin/toast