add vitepress docs

2026-09-21 16:05:14 +08:00
parent b435bf992e
commit 37cf38fe27
73 changed files with 7003 additions and 802 deletions
@@ -0,0 +1,122 @@
+# 演示与文档约定
+
+本站的演示与 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，但也别把它当作服务端渲染能力的验证。