文档编写指北

文档

 2021/01/27 

[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 或 亿 为结尾。（这边是功能说明）

参数

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

返回值

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

例子

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	主动触发关闭

原文作者：Yizhou Shen

原文链接：http://shenyizhou.github.io/2021/01/27/2021-01-27-%E6%96%87%E6%A1%A3%E7%BC%96%E5%86%99/

发表日期：January 27th 2021, 10:40:01 am

更新日期：March 5th 2024, 10:56:37 pm

Next Post

今生必读的武侠小说列表
Previous Post

自动批量请求（2）—— TS 化和代码逻辑优化

CATALOG

1. 文档编写指北