从今年2月份开源以来,有不少朋友给我们 TinyVue 组件库提了文档优化的建议,这些建议都非常中肯,我们也在持续对文档进行优化,并且从中总结出了大家对于文档优化的一些共性问题,形成了一份
《组件 demo 和 api 文档编写规范》
为了提升开发者阅读文档的体验,从9月份至今,我们花了整整三个月时间对组件的 demo / api 文档进行全面的优化。
开源不易,请给 TinyVue 点个 Star ⭐ 鼓励下,感谢你对我们 OpenTiny 的大力支持
源码:github.com/opentiny/ti…
我们来看下优化前后的对比效果吧。
以 DatePicker 组件为例。
优化前组件的 props / events / methods / slots 排列比较乱,没有规律,不方便寻找。
优化后按照字典顺序排列,符合预期,查找方便。
优化前组件 props / events 等的类型不够细致,要了解组件的使用方式,还得跳转到 Demo 里面查看代码才知道怎么使用,不太方便,而且 Demo 里面可能没有覆盖到这个 API 的所有用法。
比如 picker-options 这个属性,API 表格里的类型是 Object,具体可以配置什么需要到 Demo 里才知道,而 Demo 里也只显示了 firstDayOfWeek
和 shortcuts
两个配置项的用法,其中的 shortcuts
也只演示了 text
和 onClick
两个配置项的用法。
优化后每个 props / events 都补充了详细的类型定义。
'left' | 'center' | 'right'
我们来看下 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
}[]
}
是不是非常清晰。
优化前:
优化后:
详细的类型定义:
组织良好的演示 Demo 可以方便开发者快速上手使用我们的组件,因此我们花了很多时间讨论和优化组件 Demo 的组织方式,主要包含:
我们还是以 DatePicker 组件为例。
优化前,相似特性的 Demo 较为分散,很难查找。
优化后,将分散在多个 Demo 中的单选
、多选
、范围选择
组织成三个 Demo,比之前更加清晰,更容易查找。
除了以上几个优化点之外,我们还对组件的文档做了大量的优化,欢迎朋友们到 TinyVue 官网进行体验。
TinyVue 官网:opentiny.design/tiny-vue
如果你在体验过程中,发现有描述不清楚、不合理、不美观之处,也希望你能给我们提交 Issue 进行反馈
github.com/opentiny/ti…
感谢你对 TinyVue 开源组件库的大力支持。
OpenTiny 是一套企业级 Web 前端开发解决方案,提供跨端、跨框架、跨版本的 TinyVue 组件库,包含基于 Angular+TypeScript 的 TinyNG 组件库,拥有灵活扩展的低代码引擎 TinyEngine,具备主题配置系统TinyTheme / 中后台模板 TinyPro/ TinyCLI 命令行等丰富的效率提升工具,可帮助开发者高效开发 Web 应用。
欢迎加入 OpenTiny 开源社区。添加微信小助手:opentiny-official 一起参与交流前端技术~更多视频内容也可关注B站、抖音、小红书、视频号
OpenTiny 也在持续招募贡献者,欢迎一起共建
OpenTiny 官网:https://opentiny.design/
OpenTiny 代码仓库:https://github.com/opentiny/
TinyVue 源码:https://github.com/opentiny/tiny-vue
TinyEngine 源码: https://github.com/opentiny/tiny-engine
欢迎进入代码仓库 StarTinyEngine、TinyVue、TinyNG、TinyCLI~
如果你也想要共建,可以进入代码仓库,找到 good first issue标签,一起参与开源贡献~