Babel自動生成Attribute文檔實現(xiàn)詳解
更新時間：2022年11月03日 16:36:16 作者：小鑫同學
這篇文章主要為大家介紹了Babel自動生成Attribute文檔實現(xiàn)示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪
1. 前言
利用Babel自動解析源碼屬性上的注釋生成對應Markdown文檔，這個場景的應用主要包括在組件庫文檔對組件屬性的介紹中，這一篇就通過編寫一個Babel插件來實現(xiàn)這個功能~
2. 開發(fā)自動生成屬性文檔插件
2.1 生成Babel插件模板：
- 2.1.1 創(chuàng)建
babel-plugin-auto-attr-doc文件夾； - 2.1.2 安裝
npm i -g yo generator-babel-plugin-x； - 2.1.3 在新建目錄下執(zhí)行
yo babel-plugin-x:v7-ts；
生成的插件模板如下：
babel-plugin-auto-attr-doc ├─ lib │ └─ index.js ├─ src │ └─ index.ts ├─ __tests__ │ ├─ fixtures │ │ └─ example │ │ ├─ actual.ts │ │ └─ expected.ts │ └─ index.js ├─ package-lock.json ├─ package.json ├─ README.md └─ tsconfig.json
2.2 轉換思路詳解：
轉換過程：利用Babel將Typescript腳本解析為AST，通過對AST結構分析抽離對應的注釋部分，再拼接Markdown表格風格的語法；
源碼要求：**我們應該將組件涉及到對外提供的屬性統(tǒng)一到對應的types.ts文件管理，分別導出對應的type字段；
注釋要求：**分別定義字段描述、類型、可選項、默認值4項，由于解析器關鍵詞沖突原因，我們應該盡量避免；
/** * @cDescribe 類型 * @cType string * @cOptions * @cDefault */ export type IType = "primary" | "success" | "warning" | "danger" | "info"; /** * @cDescribe 圖標組件 * @cType string * @cOptions * @cDefault */ export type IIcon = string; /** * @cDescribe 是否為樸素按鈕 * @cType boolean * @cOptions * @cDefault false */ export type IPlain = boolean;
Markdown表格：**展示組件的屬性、描述、類型、可選值和默認值這幾項；
2.3 單元測試用例：
- 準備插件待解析源碼文件
source-code.ts； - 準備實際生成MD后應該顯示的內容文件
actual.md；
| 屬性名 | 說明 | 類型 | 可選值 | 默認值 | | ------ | ---- | ---- | ----- | ----- | | type | 類型 | string | | | | icon | 圖標組件 | string | | | | plain | 是否為樸素按鈕 | boolean | | false |
- 調整單元測試文件讀?。?/li>
it(`should ${caseName.split("-").join(" ")}`, () => {
const actualPath = path.join(fixtureDir, "source-code.ts");
// 對源碼進行加載解析
transformFileSync(actualPath);
// 讀取我們準備好的md文件
const actual = fs
.readFileSync(path.join(fixtureDir, "actual.md"))
.toString();
// 讀取插件解析生成的md文件
const expected = fs
.readFileSync(path.join(fixtureDir, "api-doc.md"))
.toString();
// diff
const diff = diffChars(actual, expected);
diff.length > 1 && _print(diff);
expect(diff.length).toBe(1);
});
2.4 AST分析詳解：
- 通過在AST explorer的源碼分析，我們在Babel中可以通過遍歷
ExportNamedDeclaration（命名導出聲明）； - 在
leadingComments數(shù)組中可以取出所有注釋文本的集合，在Babel處理時我們需要依次處理每一塊注釋后增加標記來避免重復處理； - 在
(path.node.declaration as t.TypeAlias).id.name中取屬性名稱；
將注釋文本通過doctrine模塊解析為對象后和屬性名合并對轉換Markdown所需要的所有數(shù)據(jù)~
2.5 插件開發(fā)過程：
2.5.1 定義Comment、ApiTable類型對象：
type Comment =
| {
describe: string;
type: any;
options?: any;
default?: any;
}
| undefined;
type ApiTable = {
attributeName: any;
attributeDescribe: any;
attributeType: any;
attributeOptions: any;
attributeDefault: any;
};
2.5.2 插件主邏輯分析：
- pre：初始化存放apidoc容器，避免在存放時找不到容器；
- visitor：解析源碼并獲取組織MD內容數(shù)據(jù)暫存到apidoc中；
- post：取出所有的apidoc內容解析并輸出到本地文件中；
export default declare(
(api: BabelAPI, options: Record<string, any>, dirname: string) => {
api.assertVersion(7);
return {
name: "auto-attr-doc",
pre(this: PluginPass, file: BabelFile) {
this.set("api-doc", []);
},
visitor: {
ExportNamedDeclaration(
path: NodePath<t.ExportNamedDeclaration>,
state: PluginPass
) {
const apidoc = state.get("api-doc");
// 處理 path.node.leadingComments 中未處理的數(shù)據(jù)后塞到apidoc中
state.set("api-doc", apidoc);
},
},
post(this: PluginPass, file: BabelFile) {
const apidoc = this.get("api-doc");
const output = generateMD(apidoc);
const root = path.parse(file.opts.filename || "./").dir;
fs.writeFileSync(path.join(root, "api-doc.md"), output, {
encoding: "utf-8",
});
},
} as PluginObj<PluginPass>;
}
);
2.5.3 主邏輯實現(xiàn)：
leadingComments數(shù)組會在依次訪問ExportNamedDeclaration時不停增加，我們在處理掉當前索引的對象后增加一個處理過的標記skip，下次循環(huán)直接跳過；
通過parseComment函數(shù)解析后的對象可以通過tags數(shù)組獲取到所有的注釋項目，通過對應的title得到對應description內容；
在往apidoc存放數(shù)據(jù)時需要處理屬性名稱符合一定的規(guī)則，并將apidoc對象存放到原容器中；
{
ExportNamedDeclaration(
path: NodePath<t.ExportNamedDeclaration>,
state: PluginPass
) {
const apidoc = state.get("api-doc");
let _comment: Comment = undefined;
path.node.leadingComments?.forEach((comment) => {
if (!Reflect.has(comment, "skip")) {
const tags = parseComment(comment.value)?.tags;
_comment = {
describe:
tags?.find((v) => v.title === "cDescribe")?.description || "",
type: tags?.find((v) => v.title === "cType")?.description || "",
options:
tags?.find((v) => v.title === "cOptions")?.description || "",
default:
tags?.find((v) => v.title === "cDefault")?.description || "",
};
Reflect.set(comment, "skip", true);
}
});
apidoc.push({
attributeName: (path.node.declaration as t.TypeAlias).id.name.substr(1).toLocaleLowerCase(),
attributeDescribe: _comment!.describe,
attributeType: _comment!.type,
attributeOptions: _comment!.options,
attributeDefault: _comment!.default,
} as ApiTable);
state.set("api-doc", apidoc);
},
}
2.5.4 注釋解析函數(shù)：
const parseComment = (comment: string) => {
if (!comment) {
return;
}
return doctrine.parse(comment, {
unwrap: true,
});
};
2.5.5 Markdown表格拼裝：
const generateMD = (apidoc: Array<ApiTable>) => {
let raw = `| 屬性名 | 說明 | 類型 | 可選值 | 默認值 |\n| ------ | ---- | ---- | ----- | ----- |\n`;
apidoc.forEach((item) => {
raw += `| ${item.attributeName} | ${item.attributeDescribe} | ${item.attributeType} | ${item.attributeOptions} | ${item.attributeDefault} |\n`;
});
return raw;
};
2.5.6生成結果展示~
3. 總結
插件生成目前基本功能完成，注釋解析可以通過Babel的插件選項來定義作為一個擴展方向，MD文件的生成可以通過對應工具轉換，更多的輸出文件類型也可以作為擴展方向，歡迎喜歡玩轉Babel的小伙伴一起交流交流~
已推送至GitHub https://github.com/OSpoon/awesome-examples
以上就是Babel自動生成Attribute文檔實現(xiàn)詳解的詳細內容，更多關于Babel生成Attribute文檔的資料請關注腳本之家其它相關文章！
相關文章
這篇文章主要介紹了Vue組件中的父子組件使用，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2023-01-01
這篇文章主要為大家詳細介紹了vue實現(xiàn)下拉菜單效果，運用了hover顯示與隱藏以及定位，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2022-09-09
本文給大家詳細介紹了如何使用使用 vue.js腳手架工具vue-cli構建大型單頁應用的方法，非常的實用，有需要的小伙伴可以參考下2018-02-02
這篇文章主要為大家詳細介紹了基于Vue.js實現(xiàn)tab滑塊效果，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2017-07-07
class 與 style 綁定就是專門用來實現(xiàn)動態(tài)樣式效果的技術,如果需要動態(tài)綁定 class 或 style 樣式,可以使用 v-bind 綁定,本文給大家講解Vue 綁定style和class樣式,感興趣的朋友一起看看吧2023-10-10
el-select如何獲取當前選中的對象所有(item)數(shù)據(jù)
在開發(fā)業(yè)務場景中我們通常遇到一些奇怪的需求,下面這篇文章主要給大家介紹了關于el-select如何獲取當前選中的對象所有(item)數(shù)據(jù)的相關資料,文中通過代碼介紹的非常詳細,需要的朋友可以參考下2023-11-11
這篇文章主要介紹了vue數(shù)組中不滿足條件跳出循環(huán)問題，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2023-07-07
這篇文章主要介紹了vue element input如何讓瀏覽器不保存密碼問題,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2024-03-03
這篇文章主要為大家介紹了buildAdmin開源項目引入四種圖標方式詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪2023-02-02
手寫可拖動穿梭框組件CustormTransfer vue實現(xiàn)示例
這篇文章主要為大家介紹了手寫可拖動穿梭框組件CustormTransfer vue實現(xiàn)示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪2022-11-11