update at 2025-10-08 09:18:20

2025-10-08 09:18:20 +08:00
parent a49e389fe2
commit 584d4151fc
67 changed files with 5363 additions and 892 deletions
--- a/SLICE_IMAGE_GUIDE.md
+++ b/SLICE_IMAGE_GUIDE.md
@@ -0,0 +1,137 @@
+# 切图功能使用指南
+
+## 功能说明
+
+切图功能可以将 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
+```
+
+---
+
+**提示**：首次使用建议先用小文档测试，确认配置符合预期后再处理长文档。