Docz 用 MDX 寫 React UI 元件文件
前言
為了提升開發效率,建立一套 UI 元件庫是一種較為有效的方式之一:可以減少重複工作、提高可複用,所以現在越來越多團隊開始建立自己的 UI 元件庫。較早的 Twitter 的 Bootstrap 雖然只能稱為 UI 庫,但也大大提升了開發效率。後面 MVVM
大行其道 ,前端終於可以把 HTML、CSS、JS 放在一起開發包含 UI 、互動真正意義上的元件了,現在有基於 React
的 Material-UI、國內阿里金服基於 React
的 Ant Design、餓了麼基於 Vue.js
的 Element、TalkingData 基於 Vue.js
的 iView 等。有了這些 UI 元件,讓前端開發變得前所未有的方便,完成一個專案就像是拿一塊塊的積木(元件)堆成一個完整專案。
考慮到前期開發 UI 元件的工作量及後期維護成本,我認為在大廠開源 UI 元件庫的基礎上個性化色彩(一般都提供顏色定製)、增加團隊的個性化需求元件、減少不需要的元件是個不錯的主意。
有了團隊的 UI 元件庫就少不了使用文件,畢竟文件還是比口口相傳要靠譜的多。這裡介紹一個可以快速建立 React UI 元件庫使用、演示文件的專案:Docz。Docz 的特色是零配置、簡單、快速,它使用 Markdown
語法的擴充套件 MDX (在 Markdown 裡引入 React 元件並渲染出元件)來書寫文件,對於熟悉 Markdown
的開發者是可以直接上手的。下面貼一張官方的圖看看有多簡單:
左邊是建立的MDX
文件,右邊是 Docz 渲染出的元件及元件程式碼。
是不是很方便?那下面簡單介紹一下使用步驟。
使用
1. 在你的專案裡安裝 Docz:
yarn add docz --dev 或者 npm install docz --save-dev
2. 建立 .mdx
檔案並輸入:
--- name: Button --- import { Playground, PropsTable } from 'docz' import Button from './' # Button <PropsTable of={Button} /> ## Basic usage <Playground> <Button>Click me</Button> <Button kind="secondary">Click me</Button> </Playground>
3. 執行:
yarn docz dev
然後就完成了一個簡單的 Button 元件的演示、使用文件。
配置
零配置方便是方便,但有時想介面個性化點還是很費事的(官方提供 Themes 支援,但現僅有一套官方的預設主題),下面分享一個通過引入本地 CSS 的方式來改變預設主題的配置。
1. 建立配置檔案 doczrc.js
,增加 htmlContext 內容。
export default {
htmlContext: {
head: {
links: [
{ rel: 'stylesheet', href: '/base.css' }
]
}
}
}
2. .docz
目錄下建立 public
資料夾並建立 base.css
,在 base.css
裡寫自己的樣式覆蓋預設的即可。
最後
- Docz 簡單好用,但現在只支援 React。
-
Storybook 是一個更強大的集元件開發、檢視、測試的文件工具,支援:
- React
- React Native
- Vue
- Angular
- Polymer
- Mithril
- Marko
- HTML
- Svelte
- Riot