探索組件庫設計的無限可能性

作者：何彪 2023-10-27 14:25:26

目前,ZjDesign業務組件庫正在不斷豐富中。我們努力開發具有高擴展性和低上手成本的組件。并且組件庫已有多個新項目接入,整體開發效率明顯提升,減少了重復開發。

1. 前言

當前端開發團隊面臨業務的不斷增長和項目數量的持續增加時,兩個主要問題逐漸凸顯：1.業務組件復用的挑戰；2. 代碼一致性和質量維護問題。前端團隊為了解決這些問題,通常會選擇構建業務組件庫。其主要目標是：

提高開發效率：開發人員可以在不同項目中復用組件,從而減少重復工作,提高開發效率。
保持一致的代碼實現：可以確保在不同項目中使用相同的代碼實現,避免了風格不一致和質量差異。
質量保障：組件庫中的組件經過嚴格驗證和測試,能夠提供高質量的代碼。
易于維護和升級：作為獨立的模塊,業務組件庫更容易進行維護和升級,使開發人員能夠更專注于組件庫本身的質量。
知識共享和技術積累：組件庫可以成為團隊共享技術知識和經驗的平臺,幫助提升整體的技術水平。

因此,構建業務組件庫有助于解決業務組件復用、代碼統一性和質量維護等問題,為不斷發展的業務環境提供了高效、統一和可維護的開發流程。

2. 實現分析

在構建業務組件庫時,需要深入調研和選擇適當的技術方案,驗證方案的可行性,最終將各個解決方案集成到一起,以實現高效的組件庫開發和維護。下面我們將通過整體架構、構建、質量監控、站點搭建、組件質量、組件SOP這六大模塊對我們的業務組件庫進行分析。

圖片

3. 整體架構設計

對于業務組件庫的整體架構設計而言,核心問題是業務組件庫的代碼時如何來組織和管理。首先,我們把代碼倉庫建好。業界一般會把同一類組件庫用單個倉庫的形式維護,并且把組件開發成NPM包的形式,這里的重點是,你要考慮把所有的組件打包成一個大的NPM包,還是分割是一個個獨立的小NPM包。不要小看這個問題,這兩種選擇會使倉庫的目錄結構有不小的差異,進一步又會影響到后面組件的開發,構建,發布,實現的技術設計。

業界組件庫的架構常見單包和多包兩種。單包適合簡單場景,組件集中在一個庫中。多包則將組件分成獨立包,適應多項目需求,增強靈活性和復用性。

3.1單包是什么

把所有的組件看成一個整體,一起打包發布。單個倉庫,單個包,統一維護統一管理。

? 優點

可以通過相對路徑實現組件與組件之間的引用,公共代碼之間的引用
維護成本低,只維護一套package.json配置

? 缺點

組件完全耦合,必須把它作為一個整體統一發包,就算只改一個非常小的功能,都要對整個包發布更新
搭建場景重復打包

比如說Antd,它就是作為一個整體的包來盡進行管理的。選擇使用單包架構的話,那么你就必須提供按需加載的能力,以降低使用者的成本,你可以考慮支持ESModules的Treeshaking的功能來實現按需加載的能力。當然你也可以選擇另外一種方案,叫做"多包架構"。

3.2多包是什么

每個組件彼此獨立,單獨打包發布,單個倉庫多個包,統一維護單獨管理。

? 優點

組件發布靈活,并且大然支持按需使用

? 缺點

維護成本高,每個組件都需要一套package配置。
組件與組件之間物理隔離,對于相互依賴,公共代碼抽象等場景,就只能通過NPM包引用的方式來實現。
多依賴多版本問題
常用邏輯片段/各個組件都需要的依賴和邏輯

在這些場景下的開發統一發布,相對來說沒那么方便,多包架構在業界稱之為"Monorepo"。

圖片

3.3結論

ZjDesign組件庫使用場景比較特殊,組件之間的依賴關系比較強,互相會組合形式新的組件,所以在這里選用的單包開發模式進行開發。單包開發模式可以減少我們開發維護成本,開發工作量的減少,提升組件之間的引用效率。

4. 組件庫構建

當你確定了整體架構之后,就可以開始具體的功能點實現了。業務組件庫要求整體框架提供基礎的技術能力。

4.1項目打包

提到構建工具,大家肯定一下會想到很多一堆工具：webapck、gulp、rollup等。網上有很多文章分析它們分別更適合哪些場景,webpack更適合打包組件庫、應用程序之類的應用,而rollup更適合打包純js的類庫。下面我們來對比一下webpack和rollup兩者的區別。

?rollup使用流程

無需考慮瀏覽器兼容問題,開發者寫esm代碼 -> rollup通過入口,遞歸識別esm模塊 -> 最終打包成一個或多個bundle.js -> 瀏覽器直接可以支持引入
需考慮瀏覽器兼容問題,可能會比較復雜,需要用額外的polyfill庫,或結合webpack使用

打包成npm包：

開發者寫esm代碼 -> rollup通過入口,遞歸識別esm模塊 -> （可以支持配置輸出多種格式的模塊,如esm、cjs、umd、amd）最終打包成一個或多個bundle.js
（開發者要寫cjs也可以,需要插件@rollup/plugin-commonjs）初步看來
很明顯,rollup 比較適合打包js庫（react、vue等的源代碼庫都是rollup打包的）或高版本無需往下兼容的瀏覽器應用程序（現在2022年了,時間越往后,遷移到rollup會越多,猜測）
這樣打包出來的庫,可以充分使用上esm的tree shaking,使源庫體積最小

?webpack和rollup打包比對

let foo = () => {

 let x = 1;

 if (false) {

 console.log("never reached");

 }

 let a = 3;

 return a;

};

let baz = () => {

 var x = 1;

 console.log(x);

 post();

 function unused() {

 return 5;

 }

 return x;

 let c = x + 3;

 return c;

};

baz();

測試對比兩個打包工具對Dead Code的打包結果

打包對比結果：中間是源代碼,左邊是rollup打包結果,右邊是webpack打包結果對比。

圖片

webpack打包效果（有很多注入代碼）

實際上,我們自己寫的代碼在最下面。上面注入的大段代碼都是webpack自己的兼容代碼,目的是自己實現require,modules.exports,export,讓瀏覽器可以兼容cjs和esm語法
可以理解為,webpack自己實現polyfill支持模塊語法,rollup是利用高版本瀏覽器原生支持esm(所以rollup無需代碼注入)

具體細節rollup和webapck的源碼實現差異在這里不做過多贅述,大家可以自己深入研究。

? 構建出 esm、cjs 格式

選擇Rollup來打包組件庫,需要有幾點注意：

配置包格式為 esm、cjs、umd
external 掉vue,組件庫不建議將 Vue 打包進去

rollup 配置如下：

{
    input: file,
    output: {
      compact: true,
      file:  `lib/index.js`,
      format: 'es',
      name,
      sourcemap: false,
      globals: {
        echarts: 'echarts',
        vue: 'Vue'
      }
    },
    external: [
      'echarts', 'vue'
    ],
    plugins: [
      replace({
        'process.env.NODE_ENV': JSON.stringify('production')
      }),
      vue({
        css: false,
        template: {
          isProduction: true
        },
        modules: true,
        styles: {
          scoped: true,
          trim: true
        }
      }),
      postcss({
        extract: true,
        modules: false,
        scoped: true,
        sourceMap: false,
        autoModules: true,
        plugins: [
          simplevars(),
          nested(),
          cssnano(),
          base64({
            extensions: ['.png', '.jpeg', '.jpg', '.gif'],
            root: './assets/'
          }),
          autoprefixer({
            add: true
          })
        ],
        extensions: ['.css', '.less'],
        use: {
          less: {
            javascriptEnabled: true
          }
        }
      }),
      babel({
        runtimeHelpers: true,
        exclude: 'node_modules/**',
        plugins: [
          ['@babel/plugin-proposal-optional-chaining', { loose: false }]
        ],
        presets: [
          ['@babel/preset-env', { targets: '> 0.25%, not dead' }]
        ]
      }),
      url({
        limit: 10 * 1024,
        emitFiles: true
      }),
      progress(),
      buble({
        transforms: { forOf: false }
      }),
      uglify({
        ie8: true
      })
    ]
}

4.2 版本控制

組件庫發布版本號的管理是很重要的,如何來維護我們的版本號？只能動手在package.json中修改嗎？其實可以在打包執行命令的時候,通過命令及參數幫助我們實現自動升級版本號的目的。比如我們在打測試環境包的時候可以使用（cross-env用來指定變量NODE_ENV的值）。

"scripts": {
  "test": "npm version patch && cross-env NODE_ENV=testing node build/build.js"
}

下面我們來看看npm version命令具體的使用方式：npm采用了semver規范作為依賴版本管理方案。semver約定一個包的版本號必須包含3個數字。

MAJOR.MINOR.PATCH 意思是主版本號.小版本號.修訂版本號

MAJOR 對應大的版本號迭代,做了不兼容舊版的修改時要更新MAJOR版本號

MINOR 對應小版本迭代,發生兼容舊版API的修改或功能更新時,更新MINOR版本號

PATCH 對應修訂版本號,一般針對修復BUG的版本號

當我們每次發布包的時候都需要升級版本號：

"scripts": {
    "rollup": "rollup -c rollup.config.js",
    "publish:major": "npm version major && npm publish",
    "publish:minor": "npm version minor && npm publish",
    "publish:patch": "npm version patch && npm publish",
    "publish:beta": "npm version prerelease --preid=beta && npm publish --tag=beta"
  },

4.3發布

npm包發布使用之家npm進行發布,發布流程如下：

1. 首先需要配置私有包，配置一次即可
$ npm config set @auto:ZjDesign http://xxxx.com/


2. 使用如下命令在私有倉庫中添加用戶（配置一次即可）
npm adduser --registry http://xxxx.com/


3. 執行打包命令
npm run rollup


4.私有包發布
npm publish --registry http://xxxx.com/

5. 組件搭建實例

首先看一下我們單個組件UI設計圖。從圖中可以看出,每個組件實例demo可以看成抽象五大模塊。1.組件的title+subtitle、2.組件描述、3.多個組件形態展示、4.設計原則與頁面布局、5.單個組件形態的代碼示例。

圖片

5.1組件demo整體目錄

圖片

index.zh-CN.md：作為靜態數據的快速輸出,包含組件名稱、描述、設計原則和API。從.md格式文件中可以使用插件md(vite插件)解析出組件需要的數據,這個在后面單獨講解實現細節。

圖片

單個組件類型文件：包含組件排序,title,描述,html。這個通過docs進行數據的解析,具體解析后面進行詳細講解。

圖片

5.2Docs插件

作用：將單例中的.vue文件中docs標簽數據進行格式處理,docs插件流程圖。

圖片

實現代碼：

export default (options: Options = {}): Plugin => {
  const { root, markdown } = options
  const vueToMarkdown = createVueToMarkdownRenderFn(root)
  const markdownToVue = createMarkdownToVueRenderFn(root, markdown)
  return {
    name: 'vueToMdToVue',
    async transform(code, id) {
      if (id.endsWith('.vue') && id.indexOf('/demo/') > -1 && id.indexOf('index.vue') === -1) {
        const res = vueToMarkdown(code, id)
        return {
          code: res.ignore ? res.vueSrc : (await markdownToVue(res.vueSrc, id)).vueSrc,
          map: null
        }
      }
    }
  }
}

vueToMarkdown函數實現：這里面使用了lru-cache進行緩存處理,對于已經解析完成的文件進行跟蹤,這樣可以加快文檔展示。通過fetchCode方法對自定義標簽內容進行獲取。

5.3 MarkDown插件

作用：將markdown文檔格式數據轉化成我們想要的vue格式化數據。

這里主要通過對第三方markdown-it,依據UI設計的要求進行定制化的修改。可以支持輸入emoji,anchor,toc分別使用markdown-it-emoji、markdown-it-anchor、markdown-it-table-of-contents插件。

? md插件實現流程

1、定義插件導出,基于vite的Plugin進行封裝：

import { createMarkdownToVueRenderFn } from './markdownToVue';
import type { MarkdownOptions } from './markdown/markdown';
import type { Plugin } from 'vite';


interface Options {
  root?: string;
  markdown?: MarkdownOptions;
}


export default (options: Options = {}): Plugin => {
  const { root, markdown } = options;
  const markdownToVue = createMarkdownToVueRenderFn(root, markdown);
  return {
    name: 'mdToVue',
    async transform(code, id) {
      if (id.endsWith('.md')) {
        // transform .md files into vueSrc so plugin-vue can handle it
        return { code: (await markdownToVue(code, id)).vueSrc, map: null };
      }
    },
  };
};

2、markdownToVue核心思想實現：

通過lru-cache進行解析文檔的緩存處理,使用gray-matter對docs格式數據的解析,最后生成demo-box組件格式的vue文件。

export function createMarkdownToVueRenderFn(root: string = process.cwd(), options: MarkdownOptions = {}) {
  const md = createMarkdownRenderer(options)
  return async (src: string, file: string): Promise=> {
    const relativePath = slash(path.relative(root, file))
    const cached = cache.get(src)
    if (cached) {
      debug(`[cache hit] ${relativePath}`)
      return cached
    }
    const start = Date.now()
    const { content, data: frontmatter } = matter(src)
    // eslint-disable-next-line prefer-const
    let { html, data } = md.render(content)
    // avoid env variables being replaced by vite
    html = html.replace(/import\.meta/g, 'import.meta').replace(/process\.env/g, 'process.env')
    // TODO validate data.links?
    const pageData: PageData = {
      title: inferTitle(frontmatter, content),
      description: inferDescription(frontmatter),
      frontmatter,
      headers: data.headers,
      relativePath,
      content: escapeHtml(content),
      html,
      // TODO use git timestamp?
    lastUpdated: Math.round(fs.statSync(file).mtimeMs)
    }
    const newContent = data.vueCode
      ? await genComponentCode(md, data, pageData)
      : `${html}${fetchCode(content, 'style')}`
    debug(`[render] ${file} in ${Date.now() - start}ms.`)
    const result = {
      vueSrc: newContent?.trim(),
      pageData
    }
    cache.set(src, result)
    return result
  }
}

6. 組件沉淀-SOP

在開發組件并將其沉淀為組件庫時,建立合適的SOP機制可以提高開發效率、保持一致性,并促進團隊合作。以下是從組件設計到溝通、開發、沉淀為組件庫的SOP機制：

圖片

? 組件設計：

設計同學進行界面設計,定義組件統一規范。根據多個業務方進行公共組件的提取,確定組件的用途、功能。

?評審：

設計同學和研發同學進行組件設計UI的評審,研發同學定義組件的輸入和輸出,以及可能的配置項。并且進行編寫組件的詳細需求文檔,包括示例代碼和用法示例。

? 開發階段：

根據組件設計和需求文檔,進行組件的開發。使用規范的編碼風格和最佳實踐。在開發過程中進行單元測試和集成測試,確保組件的穩定性和正確性。

? 文檔編寫：

編寫組件的文檔,包括組件的用途、API文檔、示例代碼等。提供詳細的使用說明,幫助其他開發人員使用組件。

? CODE-REVIEW：

使用版本管理工具（如Git）來管理組件的代碼。進行代碼審查,確保代碼質量和一致性。

? 測試與驗收：

在真實項目中測試組件,確認其在不同場景下的穩定性和可用性。進行驗收測試,確保組件滿足預期要求。設計同學進行UI驗收。

? 發布：

根據版本號規則,發布組件庫的新版本。定期更新組件庫,修復bug、添加新功能等。

7. 總結

目前,ZjDesign業務組件庫正在不斷豐富中。我們努力開發具有高擴展性和低上手成本的組件。并且組件庫已有多個新項目接入,整體開發效率明顯提升,減少了重復開發。組件庫的搭建為團隊提供了一個統一的技術平臺,促進了知識分享和合作。這一系列改進加速了產品交付,并推動了整體開發流程的提升。

作者簡介

何彪

■ 主機廠事業部-技術部-數科技術團隊

■2023年2月加入汽車之家，目前任職于主機廠事業部-技術部-數科技術團隊，主要負責數科前端業務，組件庫搭建等工作。

責任編輯：武曉燕來源：之家技術

組件庫無限可能性