技术综合

文档编写指北

[TOC]

文档编写指北

整体结构

  • 目录（如果内容多的话）
    • 可以用- [目录名](#目录名) 的写法
  • 前言
    • 适用条件，如：iOS 10.3及以上、Android 5.0及以上系统版本可以使用
    • 有啥兼容性问题，如：由于MSE当前的兼容性在移动端受限，建议在PC-WEB下使用该组件
    • 在一些场景下是否建议用其他组件，如：移动端建议使用：@music/activity-audio
    • 想明确列一下支持功能，可以用这种写法：✔︎ 支持绑定音频、视频播放器播放
  • 快速开始
    • 下载和安装
    • 快速使用
      • 准备工作和配置
      • hello world 代码示例
    • 核心概念简介
  • 详细内容
    • 各组件属性和方法的定义
    • 场景用例
      • 场景 1
        1. 描述下场景需求
        2. 放个图 ![xxx](xxx)
        3. 写下关键代码 ``` xxx ```
      • 场景 2 …
    • 其他概念介绍，如生命周期、渲染方式、覆盖场景等等
  • 后记
    • 版本更迭（如果已有 CHANGELOG.md 可以省去）
    • 功能展望，可以列出 P0、P1 优先级
    • 联系我们

示例

组件定义

这边是该组件的简单介绍

Attributes（属性）

参数 说明 类型 可选值 默认值 版本
value 绑定值 string | number / / /
size 尺寸 string? ‘small’ | ‘medium’ | ‘large’ ‘medium’ 1.0.1
someObject 某个对象类型属性 CustomType? / { } /

注意：注意文本可以加粗处理来起强调作用

  • 还有一些详细信息可以在这里说，比如：内置了 `async-validator` 组件校验，校验规则使用该组件的语法，具体[参考这里](xxx)
  • 类型 的定义类似于 Typescript，可选参数是后面带?
  • 可选值 是出现枚举值是才需要填写，如没有可以不加
  • 版本 是涉及到版本改动才需要填写，正常是不加的
  • 一般属性按照常用 className、style、children 放最前面或省略，其他属性按照 boolean、number、string、object 类型排序
CustomType（自定义数据结构）

这边是组件中某个特定类型结构的定义，写法同上（简化版），如上述例子中的 CustomType

参数 说明 类型 默认值
xxx 属性 1 string /
yyy 属性 2 number /

Events（回调方法）

这边是回调触发方法的定义

方法名 说明 参数
onChange 变化回调 (value: string | number) => void
onBlur 失去焦点回调 (value: string | number) => void

Methods（主动调用方法）

这边是组件实例的主动触发方法的定义，使用方式有别于回调方法，最好分开展示，让用户感到清晰

方法名 说明 参数
focus 使获得焦点 () => void
对象或函数的简单定义

这边可以具体解释下某个方法中的参数，比如 onChange(value)：

参数 说明 类型
value 当前值 string | number
  • 如果是参数对象的写法比如 onChange({ value })，同样可以用上述写法
  • 如果比较复杂，建议用下文函数定义的写法

其他组件定义

当一个仓库还有其他组件时，可以在同层级增加定义

函数定义

这边是在需要详细介绍一个函数定义的时候采用的写法，比如 abbrAmount：

1
abbrAmount(count, isRound)

对一个数字 count 进行缩略，大数缩略成以 w 或 亿 为结尾。（这边是功能说明）

参数

  1. count (string | number) 需要被缩略的数字。（这边是解释下每个参数的变量名、类型、定义，变量名最好加下``，类型最好用斜体区分）
  2. isRount = false (boolean) 是代表四舍五入，否代表向下取整。（这边如果有默认值直接就写在等号后面）

返回值

(string) 返回缩略后的字符串（这边是返回值的类型和定义）

例子

1
2
3
4
5
6
abbrAmount(14500); // '1.4w'
abbrAmount(14500, true); // '1.5w'
abbrAmount(10005000); // '1000w'
abbrAmount(10005000, true); // '1001w'
abbrAmount(100500000); // '1亿'
abbrAmount(100500000, true); // '1.01亿'

CSS 变量

这边是补充一些在样式文件中定义的变量，比如 LESS 变量：

变量名 说明 默认值
@base_input_color 字体颜色 #000

常见命名

名称 说明
className 自定义类名
xxxClassName 其他自定义类名
style 自定义样式
value 绑定值
placeholder 占位提示
onChange 值变化时的回调
onClick 点击回调
close 主动触发关闭