197 lines
4.6 KiB
Markdown
197 lines
4.6 KiB
Markdown
# 用户手册生成系统
|
||
|
||
## 快速开始
|
||
|
||
### 一键更新用户手册（推荐）
|
||
|
||
```bash
|
||
pnpm manual:update
|
||
```
|
||
|
||
这个命令会自动完成：
|
||
1. 运行 E2E 测试生成带标注的截图
|
||
2. 自动复制截图到正确位置
|
||
3. 编译 MDX 文档生成 HTML
|
||
|
||
### 分步执行
|
||
|
||
如果需要单独执行某个步骤：
|
||
|
||
```bash
|
||
# 1. 只生成截图（需要开发服务器运行）
|
||
pnpm manual:screenshots
|
||
|
||
# 2. 只编译 HTML（会自动复制 E2E 截图）
|
||
pnpm manual:build
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
docs/user-manual/
|
||
├── config.yaml # 配置文件
|
||
├── content/ # MDX 源文件
|
||
│ ├── index.mdx
|
||
│ ├── basics/
|
||
│ ├── drawing/
|
||
│ ├── ai-generation/
|
||
│ └── advanced/
|
||
└── README.md # 本文档
|
||
|
||
apps/web-e2e/
|
||
├── src/manual-gen/ # 截图生成测试
|
||
│ ├── basics.manual.spec.ts
|
||
│ ├── drawing.manual.spec.ts
|
||
│ ├── ai-generation.manual.spec.ts
|
||
│ └── advanced.manual.spec.ts
|
||
├── src/utils/
|
||
│ └── screenshot-annotations.ts # 标注工具库
|
||
└── test-results/
|
||
└── manual-screenshots/ # 生成的截图（自动复制）
|
||
|
||
apps/web/public/user-manual/ # 最终输出
|
||
├── index.html
|
||
├── *.html # 各页面
|
||
└── screenshots/ # 截图文件
|
||
```
|
||
|
||
## 添加新截图
|
||
|
||
1. 编辑 `apps/web-e2e/src/manual-gen/` 目录下的测试文件
|
||
2. 使用标注工具库添加带标注的截图：
|
||
|
||
```typescript
|
||
import {
|
||
screenshotWithAnnotations,
|
||
circleOnElement,
|
||
highlightElement,
|
||
arrowToElement,
|
||
circle,
|
||
arrow,
|
||
highlight,
|
||
} from '../utils/screenshot-annotations';
|
||
|
||
// 基于元素位置的标注（推荐）
|
||
const btn = page.getByRole('button', { name: /示例/ });
|
||
const annotations = [];
|
||
|
||
// 高亮框 + 标签（标签位置：top/bottom/left/right）
|
||
const highlight = await highlightElement(btn, '按钮说明', 4, undefined, 'right');
|
||
if (highlight) annotations.push(highlight);
|
||
|
||
// 箭头标注（direction: left/right/up/down）
|
||
const arrow = await arrowToElement(btn, '说明文字', 'left', { x: 20 });
|
||
if (arrow) annotations.push(arrow);
|
||
|
||
// 数字圆圈
|
||
const circle = await circleOnElement(btn, 1, { x: -30 });
|
||
if (circle) annotations.push(circle);
|
||
|
||
// 截图
|
||
await screenshotWithAnnotations(
|
||
page,
|
||
'test-results/manual-screenshots/example.png',
|
||
annotations
|
||
);
|
||
```
|
||
|
||
3. 在 MDX 文档中引用截图：
|
||
|
||
```mdx
|
||
<Screenshot id="example" />
|
||
<p class="screenshot-caption">截图说明</p>
|
||
```
|
||
|
||
4. 运行 `pnpm manual:update` 更新
|
||
|
||
## 标注位置策略
|
||
|
||
- **左侧工具栏元素**：使用 `labelPosition='right'` 或 `direction='left'`
|
||
- **右侧面板元素**：使用 `labelPosition='left'` 或 `direction='right'`
|
||
- **对话框/弹窗**：基于对话框 boundingBox 计算相对位置
|
||
- **避免遮挡**：标注放在元素的 tooltip 通常出现的位置
|
||
|
||
## 常见问题
|
||
|
||
### 截图位置不对？
|
||
|
||
检查标注工具的参数：
|
||
- `highlightElement(element, label, padding, color, labelPosition)`
|
||
- `arrowToElement(element, label, direction, offset, color)`
|
||
- `circleOnElement(element, number, offset, color)`
|
||
|
||
### 测试失败？
|
||
|
||
1. 确保开发服务器运行：`pnpm start`
|
||
2. 检查元素选择器是否正确
|
||
3. 添加适当的等待时间：`await page.waitForTimeout(500)`
|
||
|
||
### 需要调试？
|
||
|
||
```bash
|
||
# 显示浏览器运行测试
|
||
cd apps/web-e2e && npx playwright test --project=manual --headed
|
||
|
||
# 查看测试报告
|
||
npx playwright show-report apps/web-e2e/playwright-report
|
||
```
|
||
|
||
## 录制测试代码
|
||
|
||
使用 Playwright Codegen 录制用户操作，自动生成测试代码：
|
||
|
||
```bash
|
||
pnpm manual:record
|
||
```
|
||
|
||
1. 浏览器窗口打开后，进行你想录制的操作
|
||
2. Playwright Inspector 窗口会显示生成的代码
|
||
3. 复制代码到测试文件中
|
||
|
||
## 生成 GIF 动图
|
||
|
||
### 步骤 1：录制视频
|
||
|
||
```bash
|
||
# 运行带视频录制的测试
|
||
pnpm manual:video
|
||
|
||
# 或单独运行某个测试
|
||
cd apps/web-e2e && CI= npx playwright test --project=manual-video -g "测试名称"
|
||
```
|
||
|
||
视频保存在 `apps/web-e2e/test-results/` 目录下（WebM 格式）。
|
||
|
||
### 步骤 2：转换为 GIF
|
||
|
||
需要安装 [ffmpeg](https://ffmpeg.org/)：
|
||
|
||
```bash
|
||
# macOS
|
||
brew install ffmpeg
|
||
|
||
# 转换视频为 GIF（带裁剪）
|
||
node scripts/video-to-gif.js --test "测试名称" --trim 2.9
|
||
```
|
||
|
||
#### 裁剪参数说明
|
||
|
||
```bash
|
||
# 从第 2 秒开始
|
||
node scripts/video-to-gif.js --trim 2
|
||
|
||
# 从第 2 秒开始，取 15 秒
|
||
node scripts/video-to-gif.js --trim 2:15
|
||
```
|
||
|
||
### 一键生成思维导图 GIF
|
||
|
||
```bash
|
||
pnpm manual:gif:mindmap
|
||
```
|
||
|
||
这个命令会自动：
|
||
1. 录制思维导图创建演示视频
|
||
2. 裁剪并转换为 GIF
|
||
3. 重建用户手册
|