123 lines
4.1 KiB
Markdown
123 lines
4.1 KiB
Markdown
# 演示与文档约定
|
|
|
|
本站的演示与 API 文档都由源码驱动，新增组件时只需按下面的顺序补齐三处内容。
|
|
|
|
## 目录结构
|
|
|
|
```text
|
|
docs/
|
|
├── .vitepress/
|
|
│ ├── components.ts # 组件元数据清单（唯一数据源）
|
|
│ ├── config.ts # 站点配置、侧边栏、markdown 插件
|
|
│ ├── plugins/
|
|
│ │ ├── docgen.ts # vue-docgen-api 解析，产出虚拟模块
|
|
│ │ └── ssr-stub.ts # SSR 阶段替换 timi-web
|
|
│ └── theme/
|
|
│ ├── index.ts # 主题入口，注册 TDesign Mobile 与自定义组件
|
|
│ ├── containers/ # :::preview 的预览容器
|
|
│ └── components/ # api-table 等文档组件
|
|
├── demos/ # 演示组件，按组件名分目录
|
|
│ ├── ai/ # AI 演示共用的假流
|
|
│ └── scenarios/ # 跨组件的组合场景演示
|
|
├── components/ # 组件文档页
|
|
└── scenarios/ # 组合场景文档页
|
|
```
|
|
|
|
单组件文档只回答「这个组件怎么用」，跨组件的协作方式放在 `scenarios/` 下。
|
|
|
|
## 新增一个组件
|
|
|
|
### 1. 登记元数据
|
|
|
|
在 `docs/.vitepress/components.ts` 的 `COMPONENT_LIST` 中追加一项。侧边栏导航、API 数据解析都从这里读取：
|
|
|
|
```ts
|
|
{
|
|
name: "CodeEditor", // 必须与组件 defineOptions 的 name 一致
|
|
title: "CodeEditor 代码编辑器",
|
|
description: "带行号、语法高亮与查找替换的代码输入框。",
|
|
category: "编辑器组件",
|
|
entry: "src/components/code-editor/index.vue"
|
|
}
|
|
```
|
|
|
|
### 2. 编写演示
|
|
|
|
演示组件放在 `docs/demos/<文档路径>/` 下。演示直接引用 `src` 源码，改组件会即时热更新：
|
|
|
|
```vue
|
|
<script lang="ts" setup>
|
|
import { ref } from "vue";
|
|
import { CodeEditor } from "timi-tdesign-mobile";
|
|
|
|
const code = ref("");
|
|
</script>
|
|
|
|
<template>
|
|
<code-editor v-model="code" />
|
|
</template>
|
|
```
|
|
|
|
### 3. 编写文档页
|
|
|
|
在 `docs/components/` 下建立同名 markdown，用 `:::preview` 容器引用演示：
|
|
|
|
````md
|
|
# CodeEditor 代码编辑器
|
|
|
|
带行号、语法高亮与查找替换的代码输入框。
|
|
|
|
## 基础用法
|
|
|
|
:::preview 基础用法 || 通过 v-model 双向绑定内容
|
|
|
|
demo-preview=../demos/code-editor/basic.vue
|
|
|
|
:::
|
|
|
|
## API
|
|
|
|
<api-table name="CodeEditor" />
|
|
````
|
|
|
|
路径以 markdown 文件所在位置为基准，因此 `docs/components/` 下的页面统一使用 `../demos/`。
|
|
|
|
## 文档路径的来历
|
|
|
|
`index.vue` 取所在**目录名**，具名文件取**文件名**——`ai` 目录下有多个组件，只靠目录名会全部撞成 `ai`。两者都会再转成短横线形式，`AiChatComposer` 得到 `ai-chat-composer`。需要特殊路径时用元数据里的 `slug` 覆盖。
|
|
|
|
## API 表从哪来
|
|
|
|
`<api-table>` 的数据由 `vue-docgen-api` 在构建期解析组件源码得到，通过虚拟模块 `virtual:timi-api` 交给页面渲染。因此不需要手写 props / events / slots 表格，改源码后文档自动更新。
|
|
|
|
想让说明出现在表里，就在 props 类型上写 JSDoc 注释：
|
|
|
|
```ts
|
|
const props = withDefaults(defineProps<{
|
|
/** 距离底部小于等于该值时触发 */
|
|
distance?: number;
|
|
}>(), {
|
|
distance: 120
|
|
});
|
|
```
|
|
|
|
某个组件解析失败时只会让该组件的 API 区降级为空，不会影响整站构建；构建日志里会打出对应的组件名。
|
|
|
|
## 演示统一放在手机视口里
|
|
|
|
这是移动端组件库，按桌面宽度铺开会失去真实形态。容器把演示收在 `26rem` 宽的视口内，宽度可以通过 CSS 变量调整：
|
|
|
|
```less
|
|
.tui-demo {
|
|
--tui-demo-viewport: 30rem;
|
|
}
|
|
```
|
|
|
|
需要全宽的演示（如整页骨架）可以在自己的样式里覆盖这个变量。
|
|
|
|
## 关于 SSR
|
|
|
|
`timi-web` 的构建产物在模块顶层访问 `window`，无法在 Node 中加载，而主题必须静态引入它来注册 `v-popup` 指令。因此 SSR 阶段由 `ssr-stub.ts` 提供空实现。
|
|
|
|
演示组件本身以 `clientOnly` 延迟渲染，不需要额外处理 SSR，但也别把它当作服务端渲染能力的验证。
|