如何開發和釋出一個Vue外掛
阿新 • • 發佈:2020-03-09
# 前言
Vue 專案開發過程中,經常用到外掛,比如原生外掛 `vue-router`、`vuex`,還有 `element-ui` 提供的 `notify`、`message` 等等。這些外掛讓我們的開發變得更簡單更高效。那麼 Vue 外掛是怎麼開發的呢?如何自己開發一個 Vue 外掛然後打包釋出到npm?
本文涉及技術點:
1. Vue 外掛的本質
3. `Vue.extend()` 全域性方法
4. 如何手動掛載 `Vue` 例項
2. `Vue.use()` 的原理
5. 如何打包成 `umd` 格式
6. 釋出前如何測試 `npm` 包
# 一、定義
什麼是Vue外掛,它和Vue元件有什麼區別?來看一下官網的解釋:
> “外掛通常用來為 Vue 新增全域性功能。”
> “元件是可複用的 Vue 例項,且帶有一個名字。”
> —— Vue.js 官網
Emmmm,似乎好像有種朦朧美。。。
我來嘗試解釋一下,其實, `Vue 外掛` 和 `Vue元件` 只是在 `Vue.js` 中包裝的兩個概念而已,不管是外掛還是元件,最終目的都是為了實現邏輯複用。它們的本質都是對程式碼邏輯的封裝,只是封裝方式不同而已。在必要時,元件也可以封裝成外掛,外掛也可以改寫成元件,就看實際哪種封裝更方便使用了。
除此之外,外掛是全域性的,元件可以全域性註冊也可以區域性註冊。
我們今天只聚焦 Vue 外掛。
> 外掛一般有下面幾種:
>- 新增全域性方法或者屬性。如: vue-custom-element
>- 新增全域性資源:指令/過濾器/過渡等。如 vue-touch
>- 通過全域性混入來新增一些元件選項。如 vue-router
>- 新增 Vue 例項方法,通過把它們新增到 Vue.prototype 上實現。
>- 一個庫,提供自己的 API,同時提供上面提到的一個或多個功能。如 vue-router
> —— Vue.js 官網
# 二、外掛的使用
外掛需要通過 `Vue.use()` 方法註冊到全域性,並且需要在呼叫 `new Vue()` 啟動應用之前完成。之後在其他 Vue 例項裡面就可以通過 `this.$xxx` 來呼叫外掛中提供的 API 了。
下面以實現一個簡易的提示框外掛 toast 為例,給大家介紹怎麼一步一步開發和釋出一個 Vue 外掛。
希望達到的效果:
在 main.js 中 use:
```javascript
// src/main.js
import Vue from 'vue'
import toast from '@champyin/toast'
Vue.use(toast)
```
在 App.vue 的生命週期 mounted 方法裡呼叫 this.$toast():
```vue
// src/App.vue
```
執行後在頁面上點選按鈕,彈出 `成功` 的提示,然後3秒後消失。
![how-to-write-a-vue-plugin01.jpg](https://user-gold-cdn.xitu.io/2020/3/9/170be1d839d6331c?w=1224&h=974&f=jpeg&s=77691)
線上體驗地址:http://champyin.com/toast/
# 三、外掛開發
## 1. 編寫 toast 的本體。
在 Vue 專案(你可以使用 Vue-cli 快速生成一個 Vue 專案,也可以自己用 webpack 搭建一個)的 src 目錄下建立 components/Toast/index.vue 檔案。
```vue
// src/components/Toast/index.vue
```
現在 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 檔案:
```javascript
// 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 原始碼](https://github.com/vuejs/vue/blob/dev/src/core/global-api/use.js)也可以看出,Vue.use() 方法所做的事情就是呼叫外掛或者元件的 install 方法,然後把全域性 Vue 傳進去供外掛和元件使用。
```javascript
// 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 例項的方法暴露到全域性。
```javascript
// 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,
};
```
現在外掛就開發完成了,可以在當前專案中本地引用這個外掛了。
```javascript
//在 main.js 中
import toast from src/components/index.js;
Vue.use(toast);
//在 App.vue 中
handleClick(){
this.$toast();
}
```
# 四、釋出到npm
為了方便其他人也可以使用到這個外掛,我們可以把它釋出到 npm 上去。釋出的步驟很簡單,但是釋出之前,需要有一些小配置和一些注意的地方。
## 1. 打包配置
首先我們要把它打包成可以給瀏覽器解析的 UMD 格式的的模組,並且去掉對 Vue.js 的打包,這樣別人在 Vue 專案中使用這個外掛的時候就不會有兩份 Vue 或者出現 Vue 版本衝突的問題,以保證可以更好被獨立引用。
如果你是用 Vue-cli 生成的專案,那隻需要在你的 npm 指令碼中配置一下庫的打包命令:
```json
// 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 等屬性:
```javascript
// 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` 的值是包的入口檔案路徑(相對當前檔案的路徑),一定要填寫正確,否則包無法被引用。
```json
"name": "@champyin/toast",
"main": "lib/toast.js",
```
為了確保包的配置沒有問題,我們可以利用 `npm link` 命令在本地測試一下包的使用情況。使用npm link測試包的使用估計很多人都會,就不贅述了。如果有需要可以看我的另一篇中文章[npm link詳解](https://champyin.com/2019/08/27/npm-link%E8%AF%A6%E8%A7%A3/)。
這個時候,我們其實就可以釋出了,但是為了防止把不必要的檔案釋出出去(比如測試用例和demo)浪費人家下載的流量,我們最好是建一個 `.npmigore` 檔案,語法跟 `.gitignore` 相同。
## 3. 釋出
釋出的方法很簡單(不過首先你要有個 npm 賬號),在 package.json 所在的目錄下執行這兩句就可以了:
```
npm add user
npm publish
```
關於更詳細的釋出教程,我在另一篇文章有專門細說:[如何釋出一個npm模組](https://champyin.com/2018/06/07/%E5%A6%82%E4%BD%95%E5%8F%91%E5%B8%83%E4%B8%80%E4%B8%AAnpm%E6%A8%A1%E5%9D%97/)。
## 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/](http://champyin.com/toast/)
npm 地址:[https://www.npmjs.com/package/@champyin/toast](https://www.npmjs.com/package/@champyin/toast)
歡迎給我提 issue:[https://github.com/yc111/toast/issues](https://github.com/yc111/toast/issues)
Happy coding :)
文章同時發表於公眾號「前端手札」,喜歡的話可以關注一下哦。
![qianduanshouzha-gzh.png](https://user-gold-cdn.xitu.io/2020/3/9/170be1efae4b910a?w=300&h=300&f=png&s=14056)
更多參考:
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
> 本文作者:ChampYin 轉載請註明出處:[http://champyin.com/2020/03/05/開發一個Vue外掛/](http://champyin.com/2020/03/05/開發一個Vue外掛/)
> 本文作者:ChampYin 轉載請註明出處:[http://champyin.com/2020/03/05/開發一個Vue外掛/](http://champyin.com/2020/03/05/開發一個Vue外掛/)