这是我参与「第五届青训营」伴学笔记创作活动的第 12 天
一、目录结构
编写文档所需要的文件结构
-- site 文档库
-- docs
-- .vitepress
-- utils
-- sidebar.ts # 组件导航配置区
-- components # i18n 中文
-- ${component name}.md # 组件对应的中文文档
-- en-US # i18n 英文
-- components
-- ${component name}.md # 组件对应的英文文档
-- examples # 组件文档演示组件
-- ${component name}
-- *.vue # 用于组件文档引入示例
二、编写文档
-
配置组件导航
找到 sidebar.ts 文件
1）先在 sidebar 对象中的 /components/ 编写配置内容，如下示例（slider 组件）：
"/components/": [
{
text: "Feedback 反馈组件",
items: [{ text: "Tooltip 文字提示", link: "/components/tooltip" }],
items: [{ text: "slider 滑块", link: "/components/slider" }],
},
],
2）在 sidebarEN 对象中的 /en-US/components/ 编写配置内容，如下示例（slider 组件）：
跟上面内容编写一致，但注意这个是英文对象
"/en-US/components/": [
{
text: "Feedback",
items: [{ text: "Tooltip", link: "/components/tooltip" }],
items: [{ text: "slider", link: "/components/slider" }],
},
],
-
在 examples 文件中编写示例组件
例如：slider 组件中所需要使用的示例有 2 个 basic、disperse，名字根据示例标题定就行
在 examples 文件夹中添加 slider 文件夹，用于放置 slider 中英文文档所使用的示例代码
具体每个 vue 文件内容都是展示到页面上的示例代码，先在这个组件写好示例代码，方便后面引入
-
添加中英文组件文档
1）中文文档
在中文文件夹 components 下添加 slider.md 文件，内容编写：
A. 开头先使用 script 引入刚才写好的示例组件代码
<script setup>
import basic from 'exam/slider/basic.vue'
import disperse from 'exam/slider/disperse.vue'
</script>
exam 是提前配置好的文件路径名对应：site/docs/emamples 这个路径
后续开发直接使用就行
B. 下面开始内容编写，这里一定要使用 ::: code slider/basic 这种声明方式使用示例组件
关于 code 后面是路径：[ conponment name ] / [ demo name ]
Components name 就是在 exmples 文件下的组件文件夹名
Demo name 就是 组件文件夹里面的示例组件名
# Slider 滑块
通过拖动滑块在一个固定区间内进行选择
## 基础用法
在拖动滑块时，显示当前值
通过设置绑定值自定义滑块的初始值
::: code slider/basic
<basic></basic>
:::
## 离散值
选项可以是离散的
改变`step`的值可以改变步长， 通过设置 `show-stops` 属性可以显示间断点
::: code slider/disperse
<disperse></disperse>
:::
需要注意的是，你在开发组件的时候，这个组件用什么名字命名的，后面文档之类的所有的名字都要保持一致
例如：data-picker 多单词组件，使用 - 连接，后面关于这个组件的名字都要保持一致
// 用 scrollbar.md 进行示例
<script setup>
import basic from 'exam/scrollbar/basic.vue'
import scrollbarX from 'exam/scrollbar/scrollbar-x.vue'
import maxHeight from 'exam/scrollbar/max-height.vue'
// import from './'
</script>
# Scrollbar 滚动条
用于替换浏览器原生滚动条。
## 基础用法
通过 `height` 属性设置滚动条高度，若不设置则根据父容器高度自适应。
::: code scrollbar/basic
<basic></basic>
:::
## 横向滚动
显示横向滚动条不可设置 `height` 和 `max-height`，当元素宽度大于滚动条宽度时，会显示横向滚动条。
::: code scrollbar/scrollbar-x
<scrollbarX></scrollbarX>
:::
## 最大高度
当元素高度超过最大高度，才会显示滚动条。
::: code scrollbar/max-height
<maxHeight></maxHeight>
:::
2）组件参数文档
接着上面的 slider 组件文档写组件参数和方法文档
编写参数文档推荐使用 typora 进行编写
A. 统一规范
-
开头用 ## API 二级标题起头
-
对参数列都进行 `` 反引号包裹，添加代码块效果
-
可选值或者默认值为空的情况，添加 -- 一条短杠就行，打不出来的去 slider 文档复制（杠一定要一致，不长不短）
-
中文文档都使用中文编写，英文文档使用英文编写，参数内容去 ElementPlus 切换中英文复制
B. 中文示例
使用 typeora 打开 slider.md 文件
开头使用 ## API 这个二级标题起头，后续的参数都使用 ### 三级标题起头
右键空白区域 - 插入 - 表格
快速录入参数小妙招，先点击表格选中，然后按 Ctrl + Enter 创建多点表格
然后打开 ElementPlus 官网，找到对应的组件参数文档，从属性名开始复制然后粘贴
打开 typora 在表格左上角点击得到光标选中，然后粘贴（但需要注意，没有实现的功能就不要粘贴上去了，等实现了在手动加上去）
然后还需要统一的对类型进行 `` 包裹高亮，添加 number 代码块效果，只需要对 类型 那一列添加即可，其他的列不需要加了，描述那列你看情况加就行
实现效果如下所示
B. 英文示例
只需要将中文文档的中文全部替换为英文即可，英文切换 ElementPlus 语言复制去就行，注意参数和方法的描述和标题都是英文的
具体的内容还不了解的话，去打开 en-US/components/slider.md 参考就行
3）英文文档
把中文文档复制到 en-US/components 去就行
在里面的中文全部替换为英文即可，英文切换 ElementPlus 语言复制去就行，注意参数和方法的描述和标题都是英文的
具体的内容还不了解的话，去打开 en-US/components/slider.md 参考就行
4）注意点
自己写的组件文档，中英文和明暗模式都切换下看看，有没有什么问题，发现问题及时解决
明暗模式和中英文例子参考 slider 组件文档
三、相关知识点
-
配置路径别名
先在文件根目录找到 ts.config.json 文件，以 exam 示例：
{
"compilerOptions": {
// ...
"paths": {
"@/*": ["packages/components/src/*"],
"exam/*": ["site/docs/examples/*"]
}
}
}
然后在 site/docs 下的 vite.config.ts 进行如下配置：
import { resolve } from "path";
export default (): UserConfigExport => {
return {
// ...
resolve: {
alias: [
{
find: "exam",
replacement: resolve(__dirname, "./examples"),
},
],
},
};
};
然后就可以在 site 文档库里面使用 exam 这个别名了
在组件库中使用别名，则在 packages/components 下面的 vite.config.ts 进行如下配置：
注意：这个组件库使用别名只是个示例
import { resolve } from "path";
export default (): UserConfigExport => {
return {
// ...
resolve: {
alias: [
{
find: "exam",
replacement: resolve(__dirname, "./examples"),
},
],
},
};
};
-
整个开发流程
开发组件（整理逻辑，开发代码，测试代码，功能是否存在bug，实现明暗模式切换颜色）参考 slider 组件开发
编写文档（示例组件，中文文档，英文文档，文档风格统一）
