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，但也别把它当作服务端渲染能力的验证。
@@ -0,0 +1,102 @@
+# 快速开始
+
+`timi-tdesign-mobile` 是面向移动端的 Vue 3 业务组件库，底层复用 `timi-web` 的编辑器与内容渲染能力，UI 基于 TDesign Mobile。
+
+## 安装
+
+```sh
+pnpm add timi-tdesign-mobile tdesign-mobile-vue
+```
+
+## 按需引入
+
+组件在 `<script setup>` 中导入后即可在模板里使用，这是推荐方式：
+
+```vue
+<script lang="ts" setup>
+import { ref } from "vue";
+import { CodeEditor } from "timi-tdesign-mobile";
+
+const code = ref("const answer = 42;");
+</script>
+
+<template>
+	<code-editor v-model="code" language="typescript" />
+</template>
+```
+
+## 全局注册
+
+每个组件都带有 `install` 方法，可以单独注册为全局组件：
+
+```ts
+import { createApp } from "vue";
+import { CodeEditor, TiptapEditor } from "timi-tdesign-mobile";
+
+const app = createApp(App);
+app.use(CodeEditor);
+app.use(TiptapEditor);
+```
+
+## 必须注册 v-popup 指令
+
+富文本工具栏等组件内部使用了 `timi-web` 的 `v-popup` 指令，且用在组件模板里，宿主的应用入口需要注册一次：
+
+```ts
+import TimiWebUI, { VPopup } from "timi-web";
+
+app.use(TimiWebUI);
+app.directive("popup", VPopup);
+```
+
+漏掉这一步不会报错，但工具栏的悬停提示会静默失效。
+
+## 引入样式
+
+```ts
+import "timi-tdesign-mobile/style.css";
+```
+
+该样式入口已包含 TDesign 定制与编辑器正文样式，`timi-web` 的样式也会一并带入。
+
+**另外还需要引入 TDesign Mobile 自己的样式**，注意要引完整包而不是 `es/style/index.css`——后者只含全局 token，不含任何组件类：
+
+```ts
+import "tdesign-mobile-vue/dist/tdesign.css";
+```
+
+## 数据与回调
+
+文章、通知类组件只约束对象的最小字段，业务对象上的其他字段会原样保留。上传与附件地址通过回调注入，库本身不绑定任何接口实现：
+
+```vue
+<article-editor
+	:model-value="article"
+	:upload-image="uploadImage"
+	:upload-video="uploadVideo"
+	:resolve-attachment-url="resolveAttachmentUrl"
+	@update:model-value="article = $event"
+/>
+```
+
+没有附件上传需求时，可以不传上传回调。
+
+## AI 对话
+
+对话能力由 `useAiChat` 组合式函数提供，组件只负责渲染：
+
+```ts
+import { useAiChat } from "timi-tdesign-mobile";
+
+const { messages, isGenerating, sendMessage } = useAiChat({
+	request: ({ message, signal }) => fetchSseReply(message, signal)
+});
+```
+
+详见 [AiChatPanel](/components/ai-chat-panel) 与 [AI 对话场景](/scenarios/ai)。
+
+## 下一步
+
+- 在[组件总览](/components/)中浏览全部组件
+- 看[编辑器能力总览](/scenarios/editor)等场景，了解多个组件如何协作
+- 了解本站的[演示与文档约定](/guide/demo)，向文档站补充新组件