# 切图功能使用指南

## 功能说明

切图功能可以将 Markdown 预览页面（渲染完成的 HTML）转换为长图，然后按配置的比例自动裁剪为多张 PNG 图片，适合发布到小红书等平台。

## 使用步骤

### 1. 配置切图参数

在插件设置页面的"切图配置"区块中设置：

- **切图保存路径**：切图文件的保存目录
  - 默认：`/Users/gavin/note2mp/images/xhs`
  - 可自定义为任意本地路径

- **切图宽度**：长图及切图的宽度（像素）
  - 默认：`1080`（适合小红书）
  - 最小值：100

- **切图横竖比例**：格式为 `宽:高`
  - 默认：`3:4`（竖图，适合小红书）
  - 示例：`16:9`（横图），`1:1`（方图）

### 2. 在 Frontmatter 中配置

在你的 Markdown 笔记的 frontmatter 中添加：

```yaml
---
title: 我的文章标题
slug: my-article
---
```

- **title**：文章标题（可选，用于显示）
- **slug**：文件名标识符（必需，用于生成切图文件名）
  - 长图命名：`{slug}.png`
  - 切图命名：`{slug}_1.png`, `{slug}_2.png`, `{slug}_3.png` ...

如果未设置 `slug`，将使用文件名（不含扩展名）作为默认值。

### 3. 执行切图

1. 打开要切图的 Markdown 笔记
2. 在右侧预览面板中，点击工具栏的"切图"按钮
3. 等待处理完成，系统会显示：
   - 正在生成长图...
   - 长图生成完成：宽x高
   - 长图已保存：路径
   - 开始切图：共 N 张
   - 已保存：文件名（每张）
   - ✅ 切图完成！

### 4. 查看结果

切图完成后，可在配置的保存路径中找到：

```
/Users/gavin/note2mp/images/xhs/
├── my-article.png       # 完整长图
├── my-article_1.png     # 第1张切图
├── my-article_2.png     # 第2张切图
└── my-article_3.png     # 第3张切图
```

## 技术细节

### 切图算法

1. **生成长图**：使用 `html-to-image` 库将预览区域的 HTML 渲染为 PNG 格式的长图
2. **计算切片数量**：根据长图高度和配置的切图比例，计算需要切多少张
   - 切图高度 = 切图宽度 × (比例高 / 比例宽)
   - 切片数量 = ⌈长图高度 / 切图高度⌉
3. **Canvas 裁剪**：使用 Canvas API 逐个裁剪区域并导出为 PNG
4. **白色填充**：最后一张如果高度不足，底部用白色填充

### 像素精度

- 所有切图操作使用 `pixelRatio: 1` 确保输出尺寸精确匹配配置
- 切图边界对齐到像素，无模糊

### 文件系统

- 使用 Node.js `fs` 模块进行文件操作
- 自动创建不存在的目录
- 支持绝对路径和相对路径（相对于 Obsidian vault）

## 常见问题

### Q: 切图后图片模糊？
A: 检查"切图宽度"配置，建议设置为 1080 或更高。如果预览区域本身分辨率较低，可能影响切图质量。

### Q: 切图比例不对？
A: 确认"切图横竖比例"配置格式正确，必须是 `数字:数字` 格式，例如 `3:4` 或 `16:9`。

### Q: 找不到切图文件？
A: 检查"切图保存路径"是否正确，确保有写入权限。可在终端执行 `ls -la` 查看目录权限。

### Q: 切图按钮点击无反应？
A: 确保：
1. 已打开一个 Markdown 笔记
2. 预览面板已渲染完成
3. 查看控制台是否有错误信息

### Q: 支持移动端吗？
A: 切图功能仅在桌面版（Desktop）Obsidian 中可用，因为依赖 Node.js 的文件系统 API。

## 示例配置

### 小红书竖图（推荐）
```
宽度：1080
比例：3:4
```

### Instagram 方图
```
宽度：1080
比例：1:1
```

### 微博横图
```
宽度：1200
比例：16:9
```

### 自定义高清竖图
```
宽度：1440
比例：9:16
```

---

**提示**：首次使用建议先用小文档测试，确认配置符合预期后再处理长文档。