【von-ui】组件库规范用例的styleguide使用注意事项

记录学习的轨迹：2022-4-18
故事背景：由本人主导的组件库 von-ui 的建立，已经有部分基础组件和业务组件使用styleguide生成可见文档，但是Example用例的说明太多，文档编写在VSCode上面很麻烦，直接挂链接导到CSDN吧。

一、文件夹名设置

主组件文件名需要和文件夹名称保持一致，或者主组件文件名取名为index

比如现在需要创建一个名为：VonExample 的组件，那么组件文件夹名称为 Example ，主组件文件为 Example.vue 或者 index.vue

二、组件名称的设置

使用关键字 @displayName
外部使用组件需要 Von 开头
PS：@displayName 必须在 export default 上面，如果需要imput，imput需要在 @displayName 上面

注解：
AA：基础、业务、特殊（只给例子用）
aa [v.1.0.1已废除]：Basic、Business、*（只给例子用）、children（子组件用，详情参照Address组件）

<script>
/**
 * AA组件：组件注释 // 或者 AA组件-子组件
 * @displayName [aa] VonExample
 */
export default {}

三、props规范

1. 正确规范赋值

Array类型和Object类型的数据，在prop进行默认赋值的时候，必须进行规范的自定义赋值，因为在生成文档校验是否规范，如果不规范，则会进行报错提醒

// 正确规范赋值
attrsYes: {
  type: Object,
  default: () => {}
  // type: Array,
  // default: () => []
},
// 不规范赋值
attrsNo: {
  type: Object,
  default: {}

2. props组件暴露字段显示

• @values 表示当前属性存在几个值
• @model 此属性将用在页面的v-model中 标识后该值在文档里显示为v-model，但原参数仍然可以使用
• @author 当前的作者 在旧组件里创建新参数时，写下自己的名字，详情可见 Example 组件
• @since 当前的设置版本 在旧组件里创建新参数时，标名版本号，详情可见 Example 组件
• @see 设置当前提示链接 详情可见 Icon 组件
• @ignore 设置后将忽略此属性生成文档 在极少数情况下，想从styleguide文档中删除该prop，同时将其保留在代码中时，可以使用

四、events 事件暴露

在组件中向外暴露的事件，通过$emit的事件

如果事件是显式指定的，或者是什么常量，可以不标记@event
如果事件名称来自某个对象，请精确标记@event

• 在 template 中暴露事件

<!--
  在页面中进行emit的事件
    @event trigger
    @property {Boolean} on - true 为打开
    @property {Boolean} on - false 为关闭
-->
<button @click="$emit('trigger', on)"></button>

• 在methods中暴露事件，记得写在emit上面，写在方法里，而不是方法上

/**
 * 操作控件时返回的状态
 * @event trigger
 * @property {Boolean} on  true 表示打开
 * @property {Boolean} on  false 表示关闭
 */
this.$emit('trigger', this.on)

五、slot的显示

静态插槽由 styleguidist 自动记录，要添加说明和注释时就需要这个，这边要求写明注释，也就是说这是必填的

• @slot 插槽标识 插槽的名字(注解)
• @binding 插槽中绑定的参数

<!--
  @slot 显示内容
  @binding {Boolean} bool 插槽自定义参数
-->
<slot name="label" :bool="value">{{ label }}</slot>

六、公共方法暴露

在组件中存在一些重要的方法，可能需要给用户的使用进行查看，因此需要进行一定的方法暴露
一般是使用this.$refs.example.getSomething(text,obj,nma)

/**
 * 向外暴露的函数
 * @public
 * @param {string} text 字符串参数
 * @arg {Object} obj 对象参数（第一种写法）
 * @argument {object} nma 对象参数（第二种写法）
 */
getSomething(text,obj,nma) {}

七、style

1. 使用less语言，写scoped
2. 基础组件使用 &__wrapper
3. 业务组件使用 &__container
4. 组件内类名除去引入的文件，其余内容均需要以 von-xxx 开头

<style lang="less" scoped>
// 基础组件使用 &__wrapper 
.von-example {
  &__wrapper {}
 }
 
// 基础组件使用 &__container
.von-example {
  &__container{}
 }
</style>

八、总结

此文档需配合组件库生成的styleguidist网页进行使用。

学习借鉴：

1. vue-styleguidist的官方文档
2. vue组件库自动生成文档-vue-styleguidist(二)【作者：MFYNGUFD】