🎉開發者的福音：TinyVue 元件庫文件大最佳化！型別更詳細，描述更清晰！

Kagol發表於2023-12-06
Vue元件型別

你好，我是 Kagol。

前言

從今年2月份開源以來，有不少朋友給我們 TinyVue 元件庫提了文件最佳化的建議，這些建議都非常中肯，我們也在持續對文件進行最佳化，並且從中總結出了大家對於文件最佳化的一些共性問題，形成了一份

《元件 demo 和 api 文件編寫規範》

為了提升開發者閱讀文件的體驗，從9月份至今，我們花了整整三個月時間對元件的 demo / api 文件進行全面的最佳化。

開源不易，請給 TinyVue 點個 Star ⭐ 鼓勵下，感謝你對我們 OpenTiny 的大力支援🌹

原始碼：https://github.com/opentiny/tiny-vue

我們來看下最佳化前後的對比效果吧。

以 DatePicker 元件為例。

1 元件 API 按照字典順序排序

最佳化前元件的 props / events / methods / slots 排列比較亂，沒有規律，不方便尋找。

最佳化後按照字典順序排列，符合預期，查詢方便。

2 更詳細的元件 API 型別

最佳化前元件 props / events 等的型別不夠細緻，要了解元件的使用方式，還得跳轉到 Demo 裡面檢視程式碼才知道怎麼使用，不太方便，而且 Demo 裡面可能沒有覆蓋到這個 API 的所有用法。

比如 picker-options 這個屬性，API 表格裡的型別是 Object，具體可以配置什麼需要到 Demo 裡才知道，而 Demo 裡也只顯示了 firstDayOfWeek 和 shortcuts 兩個配置項的用法，其中的 shortcuts 也只演示了 text 和 onClick 兩個配置項的用法。

最佳化後每個 props / events 都補充了詳細的型別定義。

  • 內容不長的，比如 align，就直接寫在 API 表格裡，'left' | 'center' | 'right'
  • 內容太長的，直接放表格裡影響閱讀，比如 picker-options，就定義一個型別 IPickerOptions，點選可以直接跳轉到具體的型別定義，非常方便

我們來看下 IPickerOptions 的定義。

interface IPickerOptions {
  // 每週的第一天是星期幾，預設值是7，也就是星期天
  firstDayOfWeek: number
  // 實現部分禁用，此時只能選擇一部分日期
  disabledDate: (time: Date) => boolean
  // 選中日期後執行的回撥，需要與 daterange 或 datetimerange 型別配合使用才生效
  onPick: (range: { minDate: Date, maxDate: Date }) => void
  // 快捷選項
  shortcuts: {
    text: string
    onClick: (picker: { $emit: (type: string, date: Date) => void }) => void
    type: 'startFrom' | 'EndAt'
    startDate: Date
    endDate: Date
  }[]
}

是不是非常清晰。

最佳化前：

最佳化後：

詳細的型別定義：

3 更合理的 Demo 組織方式

組織良好的演示 Demo 可以方便開發者快速上手使用我們的元件，因此我們花了很多時間討論和最佳化元件 Demo 的組織方式，主要包含：

  • 對 Demo 的標題進行簡化和統一命名規則
  • 將相似的 Demo 進行合併和精簡
  • 美化 Demo，增加必要的留白，避免太擁擠
  • 移除 Demo 程式碼中多餘的內容，每個 Demo 專注於演示某個特性

我們還是以 DatePicker 元件為例。

最佳化前，相似特性的 Demo 較為分散，很難查詢。

  • 日期單選、周單選、月份單選、年份單選分散在多個 Demo 中，並且年份單選的 Demo 重複
  • 日期範圍選擇、月份範圍選擇、年份範圍選擇分散在多個 Demo 中，年份範圍選擇的 Demo 重複
  • 日期多選和年份多選也分散在兩個 Demo 中

最佳化後，將分散在多個 Demo 中的單選、多選、範圍選擇組織成三個 Demo，比之前更加清晰，更容易查詢。

除了以上幾個最佳化點之外，我們還對元件的文件做了大量的最佳化，歡迎朋友們到 TinyVue 官網進行體驗。

TinyVue 官網：https://opentiny.design/tiny-vue

如果你在體驗過程中，發現有描述不清楚、不合理、不美觀之處，也希望你能給我們提交 Issue 進行反饋

https://github.com/opentiny/tiny-vue/issues

感謝你對 TinyVue 開源元件庫的大力支援。

開源不易，請給 TinyVue 點個 Star ⭐ 鼓勵下，感謝你對我們 OpenTiny 的大力支援🌹

原始碼：https://github.com/opentiny/tiny-vue

我們也非常歡迎你參與到 TinyVue 的貢獻中，幫助我們一起最佳化元件文件，或者修復元件缺陷，給元件增加新特性，你可以根據自己的興趣和能力選擇合適的任務。

新增微信小助手：opentiny-official，一起參與共建！

聯絡我們

GitHub：https://github.com/opentiny/tiny-vue（歡迎 Star ⭐）

官網：https://opentiny.design/tiny-vue

B站：https://space.bilibili.com/15284299

公眾號：OpenTiny

相關文章