演示与文档约定

本站的演示与 API 文档都由源码驱动，新增组件时只需按下面的顺序补齐三处内容。

目录结构

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 数据解析都从这里读取：

{
	name: "CodeEditor",              // 必须与组件 defineOptions 的 name 一致
	title: "CodeEditor 代码编辑器",
	description: "带行号、语法高亮与查找替换的代码输入框。",
	category: "编辑器组件",
	entry: "src/components/code-editor/index.vue"
}

2. 编写演示

演示组件放在 docs/demos/<文档路径>/ 下。演示直接引用 src 源码，改组件会即时热更新：

<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 容器引用演示：

# 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 注释：

const props = withDefaults(defineProps<{
	/** 距离底部小于等于该值时触发 */
	distance?: number;
}>(), {
	distance: 120
});

某个组件解析失败时只会让该组件的 API 区降级为空，不会影响整站构建；构建日志里会打出对应的组件名。

演示统一放在手机视口里

这是移动端组件库，按桌面宽度铺开会失去真实形态。容器把演示收在 26rem 宽的视口内，宽度可以通过 CSS 变量调整：

.tui-demo {
	--tui-demo-viewport: 30rem;
}

需要全宽的演示（如整页骨架）可以在自己的样式里覆盖这个变量。

关于 SSR

timi-web 的构建产物在模块顶层访问 window，无法在 Node 中加载，而主题必须静态引入它来注册 v-popup 指令。因此 SSR 阶段由 ssr-stub.ts 提供空实现。

演示组件本身以 clientOnly 延迟渲染，不需要额外处理 SSR，但也别把它当作服务端渲染能力的验证。

4.1 KiB Raw Blame History