構建自己的React UI元件庫(三)：文件編寫

ParaSLee發表於2019-03-04
ReactUI元件

序言

該系列文章將跟隨作者的開發進度持續更新。

預計內容如下：

構建自己的React UI元件庫：

（一）：從v0.0.0到 v0.0.1

（二）：構建首頁

（三）：文件編寫 （本文）

（四）：擦乾淨細節

（五）：推廣、宣傳、迭代

<= to be continue =

在這裡可以訪問到我的元件庫： BB-color

以及npm地址: BB-color

約定

  1. 本系列文章儘可能多的涉及到每個步驟、每個檔案和每個更新。
  2. 本系列文章中，整個專案的開始基於官方提供的 creat-react-app 進行react構建，所有內容將使用最新的庫版本進行開發。
    • create-react-app v2.1.1
    • react v16.7.0
    • webpack v4.19.1
    • babel 7+
    • node v10.15.0
    • docz v0.13.7

必備知識

  • 基本掌握 React
  • 會使用 Git
  • JavaScript、CSS等基礎知識

正文開始

起點

UI元件庫必備的內容，就是文件的編寫，而這也是重中之重。我們將會使用docz來輔助我們進行文件開發。

注1：

docz 可以快速建立 React UI 元件庫使用、演示的文件，它使用 Markdown 語法的擴充套件 MDX (在 Markdown 裡引入 React 元件並渲染出元件)來書寫文件，目前只支援react。更多內容可以在 github 及 官方文件 上瀏覽

準備工作

執行以下命令安裝需要的依賴

npm install --save-dev docz docz-theme-default docz-plugin-css @emotion/core
複製程式碼

注2：

docz ：docz核心部分，必須

docz-theme-default ：docz預設主題，必須

docz-plugin-css ： docz中使用CSS時的額外外掛，如果不需要css則非必須

@emotion/core ： 文件依賴，必須

安裝完成後，修改我們的package.json

// package.json

{
    ...
    
    "scripts": {
        ...
        
        "docz:dev": "docz dev", 
        "docz:build": "docz build"
    }
    ...
}
複製程式碼

編寫文件

我們在 src/components 裡建立一個 home.mdx

補充知識點A：

不一定必須要在src裡建立，官方文件中提到:

Note that you don`t need to follow any strict file architecture. You can just create your .mdx files anywhere in your project.

docz能在任何地方識別到.mdx檔案，所以你在哪裡寫文件都可以。你也可以另一起docz資料夾，單獨存放你的文件檔案，但是個人更推薦按照我們元件的目錄結構進行書寫，這樣在後續修改的時候有利於我們直接找到需要的內容。

// src/components/home.mdx

---
name: 首頁
route: /
---

# Hello world

Hello, I`m a mdx file!
複製程式碼

然後在 src/components/button 裡建立 button.mdx

// src/components/button/button.mdx

---
name: Button
route: /button
---

import { Playground, PropsTable } from `docz`
import Button from `./index.js`

# Button

<PropsTable of={Button} />

## Basic usage

<Playground>
 <Button>Click me</Button>
</Playground>
複製程式碼

文件部分的編寫到這裡就結束了，接下來是配置的編寫

在根目錄下建立 doczrc.js

// doczrc.js

import { css } from `docz-plugin-css`

export default {
  title: `BB Color`,
  description: `A Design UI library for React`,
  plugins: [
    css({
      preprocessor: `postcss`
    })
  ]
}
複製程式碼

完成以上操作後，整個專案目錄會變成這樣

構建自己的React UI元件庫(三)：文件編寫

隨後，就像執行 npm start 一樣，我們通過 gitbash 執行 npm run docz:dev

如果沒有問題，你會看見下面的頁面

構建自己的React UI元件庫(三)：文件編寫

恭喜你，你已經成功構建出你自己的文件。 你可以點選左側的 “首頁”、“Button” 檢視具體的內容。

目前我們只做了非常非常基礎的部分，本篇文章也只會講解最基本的內容搭建，具體每一個細節，每一篇文件就交給你和你的創造力共同完成。

*打包匯出(非必須)

打包匯出就比較簡單了，直接 npm run docz:build ，你就能在 .docz/dist 裡找到你的靜態檔案。 如果你想打包到其他資料夾，可以在 doczrc.js 進行配置

你可以在這裡找到相關配置：

www.docz.site/introductio…

這一步我保持原樣，不做處理。

執行打包後，會是這樣

構建自己的React UI元件庫(三)：文件編寫

./.docz/dist 存放的就是我們打包後的檔案

提交程式碼

在提交程式碼之前，修改一下 .gitignore

// .gitignore

...

/.docz

...
複製程式碼

隨後就是正常的提交了

git add .
git commit -m `文件建立`
git push -u origin master
複製程式碼

等等！ 還沒完！

在程式碼提交後，還不能進入到文件頁，我們還需要部署我們的文件程式碼

部署程式碼

我們打包出來的檔案是靜態檔案，我們需要單獨部署。

也許你想到，在docs裡面建立一個doc檔案，將dist裡的檔案放在doc裡面，像首頁一樣，通過github pages直接進入。

但是很不幸的是，這種方法不可行。

這裡有一個問題。 docz打包出來的資原始檔，引用是基於路由根部的絕對路徑。

舉例來說，我在 docs/ 路徑下啟動了一個本地服務，地址為 http://127.0.0.1/ ，我們能正常訪問到 docs/index.html 。當我們訪問文件頁時，地址改為 http://127.0.0.1/doc ，我們也能訪問到 docs/doc/index.html 但是所有的資源都載入不上，因為引用的資源會在啟動伺服器的根目錄(docs)尋找，而不是在相對路徑 ./docs/doc 裡面尋找。

我們通過github pages 生成的網站，地址是這樣：https://bb-color.github.io/BB-color/ 在https://bb-color.github.io 裡是找不到我們需要的靜態檔案。

這裡有2種方法來部署我們的文件程式碼。

  1. 購置一個伺服器、域名，將我們的程式碼推到伺服器上，從域名中訪問。
  2. 使用 Netlify 幫我們部署。

使用 Netlify 部署

Netlify是一個非常棒的簡單工具，允許你通過在幾秒鐘內從分支機構的每次推送執行部署，以自動方式部署你的應用程式，並且它還免費

進入 netlify ，使用github註冊登入

登入成功後，自動跳轉到個人首頁，然後跟著下圖紅色箭頭的指示一起做。

構建自己的React UI元件庫(三)：文件編寫
構建自己的React UI元件庫(三)：文件編寫

然後只需要選擇我們的元件庫檔案即可

構建自己的React UI元件庫(三)：文件編寫

接下來有3個需要設定的地方，

  • 第一個是選擇分支，我們就選Master即可

  • 第二個是輸入構建命令，輸入我們在package.json裡設定的文件構建命令。

  • 第三個是輸入 當執行了文件構建命令後，打包出來的檔案路徑，因為路徑我沒做修改，輸入預設的 .docz/dist 即可，

構建自己的React UI元件庫(三)：文件編寫

然後點選 deploy site 進行部署

在下圖的第一步期間它會自動部署，只需要等待第一步完成即可。

部署完成後，你能在紅色箭頭訪問到部署後的網站。如果你對域名不滿意，你可以在黃色箭頭處配置自己的域名。

構建自己的React UI元件庫(三)：文件編寫

我們只需設定這一次，以後每次我們提交程式碼的時候，Netlify會自動幫我們部署最新的程式碼。

再次提交

提交之前，修改我們的主頁，讓我們的主頁能跳轉到我們的文件頁。

git tag -a `v0.0.3` -m `文件構建`
git push origin v0.0.3
git add .
git commit -m `文件引用`
git push -u origin master
複製程式碼

恭喜你，一個具有首頁與文件說明的UI元件庫就搭好了！！

尾聲

本以為這個系列最重要的3篇會寫很久，沒想到肝得這麼快，畢竟還有其他壓力在迫使我儘快完成這部分內容，23333

之後第四章與第五章屬於附加篇，沒有前三章那麼重要，之後也不會寫得這麼快了。2333

如果有任何不當或缺失的地方，希望能在評論區指出，理性交流。

如需轉載請註明作者與原文地址

作者：ParaSLee

原文：juejin.im/post/5c304b…

相關文章