詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

豬不樂意發表於2018-10-08
Vue模式元件NPM

市面上目前已有各種各樣的UI元件庫，比如 Element 和 iView，他們的強大毋庸置疑。但是我們面臨的情況是需求越來越複雜，當它們不能再滿足我們需求的時候，這個時候就有必要開發一套屬於自己團隊的元件庫了。

所以本文的目的就是讓讀者能通過此文，小能做一個簡單的外掛供人使用，大能架構和維護一個元件庫不在話下。

以下一個簡單的顏色選擇器外掛vColorPicker講述從開發到上線到npm的流程。

vColorPicker 外掛 DEMO

一、技術棧

如何通過新版腳手架建立專案，這裡就不提了，自行看官方文件。

  • Vue-cli3: 新版腳手架的庫模式，可以讓我們很輕鬆的建立打包一個庫
  • npm：元件庫將存放在npm
  • webpack：修改配置需要一點 webapck 的知識。

二、大綱

想要搭建一個元件庫，我們必須先要有一個大概的思路。

  1. 規劃目錄結構
  2. 配置專案以支援目錄結構
  3. 編寫元件
  4. 編寫示例
  5. 配置使用庫模式打包編譯
  6. 釋出到npm

三、規劃目錄結構

1、建立專案

在指定目錄中使用命令建立一個預設的專案，或者根據自己需要自己選擇。

$ vue create .
複製程式碼

2、調整目錄

我們需要一個目錄存放元件，一個目錄存放示例，按照以下方式對目錄進行改造。

.
...
|-- examples      // 原 src 目錄，改成 examples 用作示例展示
|-- packages      // 新增 packages 用於編寫存放元件
...
. 
複製程式碼

詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

四、配置專案以支援新的目錄結構

我們通過上一步的目錄改造後，會遇到兩個問題。

  1. src目錄更名為examples，導致專案無法執行
  2. 新增packages目錄，該目錄未加入webpack編譯

注：cli3 提供一個可選的 vue.config.js 配置檔案。如果這個檔案存在則他會被自動載入，所有的對專案和webpack的配置，都在這個檔案中。

1、重新配置入口，修改配置中的 pages 選項

新版 Vue CLI 支援使用 vue.config.js 中的 pages 選項構建一個多頁面的應用。

這裡使用 pages 修改入口到 examples

module.exports = {
  // 修改 src 目錄 為 examples 目錄
  pages: {
    index: {
      entry: 'examples/main.js',
      template: 'public/index.html',
      filename: 'index.html'
    }
  }
}
複製程式碼

2、支援對 packages 目錄的處理，修改配置中的 chainWebpack 選項

packages 是我們新增的一個目錄，預設是不被 webpack 處理的，所以需要新增配置對該目錄的支援。

chainWebpack 是一個函式，會接收一個基於 webpack-chain 的 ChainableConfig 例項。允許對內部的 webpack 配置進行更細粒度的修改。

module.exports = {
  // 修改 src 為 examples
  pages: {
    index: {
      entry: 'examples/main.js',
      template: 'public/index.html',
      filename: 'index.html'
    }
  },
  // 擴充套件 webpack 配置，使 packages 加入編譯
  chainWebpack: config => {
    config.module
      .rule('js')
      .include
        .add('/packages')
        .end()
      .use('babel')
        .loader('babel-loader')
        .tap(options => {
          // 修改它的選項...
          return options
        })
  }
}
複製程式碼

鏈式操作

webpack-chain

五、編寫元件

以上我們已配置好對新目錄架構的支援，接下來我們嘗試編寫元件。以下我們以一個已釋出到 npm 的小外掛作為示例。

GitHub - 顏色選擇器：vcolorpicker

1. 建立一個新元件

  1. 在 packages 目錄下，所有的單個元件都以資料夾的形式儲存，所有這裡建立一個目錄 color-picker/
  2. 在 color-picker/ 目錄下建立 src/ 目錄儲存元件原始碼
  3. 在 /color-picker 目錄下建立 index.js 檔案對外提供對元件的引用。

詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

修改 /packages/color-picker/index.js檔案，對外提供引用。

# /packages/color-picker/index.js
// 匯入元件，元件必須宣告 name
import colorPicker from './src/color-picker.vue'

// 為元件提供 install 安裝方法，供按需引入
colorPicker.install = function (Vue) {
  Vue.component(colorPicker.name, colorPicker)
}

// 預設匯出元件
export default colorPicker
複製程式碼

2. 整合所有的元件，對外匯出，即一個完整的元件庫

修改 /packages/index.js 檔案，對整個元件庫進行匯出。

// 匯入顏色選擇器元件
import colorPicker from './color-picker'

// 儲存元件列表
const components = [
  colorPicker
]

// 定義 install 方法，接收 Vue 作為引數。如果使用 use 註冊外掛，則所有的元件都將被註冊
const install = function (Vue) {
  // 判斷是否安裝
  if (install.installed) return
  // 遍歷註冊全域性元件
  components.map(component => Vue.component(component.name, component))
}

// 判斷是否是直接引入檔案
if (typeof window !== 'undefined' && window.Vue) {
  install(window.Vue)
}

export default {
  // 匯出的物件必須具有 install，才能被 Vue.use() 方法安裝
  install,
  // 以下是具體的元件列表
  colorPicker
}
複製程式碼

六、編寫示例

1、在示例中匯入元件庫

import Vue from 'vue'
import App from './App.vue'

// 匯入元件庫
import ColorPicker from './../packages/index'
// 註冊元件庫
Vue.use(ColorPicker)

Vue.config.productionTip = false

new Vue({
  render: h => h(App)
}).$mount('#app')

複製程式碼

2、在示例中使用元件庫中的元件

在上一步用使用 Vue.use() 全域性註冊後，即可在任意頁面直接使用了，而不需另外引入。當然也可以按需引入。

<template>
	<colorPicker v-model="color" v-on:change="headleChangeColor"></colorPicker>
</template>

<script>
export default {
	data () {
		return {
			color: '#ff0000'
		}
	},
	methods: {
		headleChangeColor () {
			console.log('顏色改變')
		}
	}
}
</script>
複製程式碼

七、釋出到 npm，方便直接在專案中引用

到此為止我們一個完整的元件庫已經開發完成了，接下來就是釋出到 npm 以供後期使用。

1、package.json 中新增一條編譯為庫的命令

在庫模式中，Vue是外接的，這意味著即使在程式碼中引入了 Vue，打包後的檔案也是不包含Vue的。

Vue Cli3 構建目標：庫

以下我們在 scripts 中新增一條命令 npm run lib

  • --target: 構建目標，預設為應用模式。這裡修改為 lib 啟用庫模式。
  • --dest : 輸出目錄，預設 dist。這裡我們改成 lib
  • [entry]: 最後一個引數為入口檔案，預設為 src/App.vue。這裡我們指定編譯 packages/ 元件庫目錄。
"scripts": {
	// ...
	"lib": "vue-cli-service build --target lib --name vcolorpicker --dest lib packages/index.js"
}
複製程式碼

執行編譯庫命令

$ npm run lib
複製程式碼

詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

2、配置 package.json 檔案中釋出到 npm 的欄位

  • name: 包名，該名字是唯一的。可在 npm 官網搜尋名字，如果存在則需換個名字。
  • version: 版本號，每次釋出至 npm 需要修改版本號，不能和歷史版本號相同。
  • description: 描述。
  • main: 入口檔案，該欄位需指向我們最終編譯後的包檔案。
  • keyword：關鍵字，以空格分離希望使用者最終搜尋的詞。
  • author：作者
  • private：是否私有，需要修改為 false 才能釋出到 npm
  • license： 開源協議

以下為參考設定

{
  "name": "vcolorpicker",
  "version": "0.1.5",
  "description": "基於 Vue 的顏色選擇器",
  "main": "lib/vcolorpicker.umd.min.js",
  "keyword": "vcolorpicker colorpicker color-picker",
  "private": false
 }
複製程式碼

3、新增 .npmignore 檔案，設定忽略釋出檔案

我們釋出到 npm 中，只有編譯後的 lib 目錄、package.json、README.md才是需要被髮布的。所以我們需要設定忽略目錄和檔案。

和 .gitignore 的語法一樣，具體需要提交什麼檔案，看各自的實際情況。

# 忽略目錄
examples/
packages/
public/

# 忽略指定檔案
vue.config.js
babel.config.js
*.map

複製程式碼

4、登入到 npm

首先需要到 npm 上註冊一個賬號，註冊過程略。

如果配置了淘寶映象，先設定回npm映象：

$ npm config set registry http://registry.npmjs.org 
複製程式碼

然後在終端執行登入命令，輸入使用者名稱、密碼、郵箱即可登入。

$ npm login
複製程式碼

詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

5、釋出到 npm

執行釋出命令，釋出元件到 npm

$ npm publish
複製程式碼

詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

6、釋出成功

釋出成功後稍等幾分鐘，即可在 npm 官網搜尋到。以下是剛提交的 vcolorpicker

詳解：Vue cli3 庫模式搭建元件庫併發布到 npm

7、使用新發布的元件庫

安裝

$ npm install vcolorpicker -S
複製程式碼

使用

# 在 main.js 引入並註冊
import vcolorpicker from 'vcolorpicker'
Vue.use(vcolorpicker)

# 在元件中使用
<template>
  <colorPicker v-model="color" />
</template>
<script>
  export default {
    data () {
      return {
        color: '#ff0000'
      }
    }
  }
</script>
複製程式碼

八、專案地址

Github 地址：https://github.com/zuley/vue-color-picker

npm 地址：https://www.npmjs.com/package/vcolorpicker

DEMO 演示：http://vue-color-picker.rxshc.com

九、參考文章

從零開始搭建Vue元件庫 VV-UI

相關文章