update at 2025-10-09 12:39:24

docs/XIAOHONGSHU_PREVIEW_GUIDE.md

@@ -0,0 +1,357 @@
+# 小红书分页预览和切图功能使用指南
+
+## 功能概述
+
+小红书模式提供了专门优化的预览和切图体验：
+- ✅ 按切图比例自动分页显示
+- ✅ 确保表格和图片不跨页
+- ✅ 实时预览每一页的效果
+- ✅ 支持单页/全部页切图
+- ✅ 字体、字号、主题可调整
+
+## 使用步骤
+
+### 1. 切换到小红书平台
+
+1. 打开笔记预览面板
+2. 在顶部"发布平台"下拉框中选择"小红书"
+3. 界面会自动切换到小红书预览模式
+
+### 2. 用户界面
+
+小红书预览视图由四部分组成：
+
+### 2.1 顶部工具栏
+
+#### 第一行：操作按钮
+```
++------------------------------------------------------------+
+| [刷新] [发布到小红书]                                      |
++------------------------------------------------------------+
+```
+
+功能说明：
+- **刷新**：重新加载自定义CSS和样式，刷新预览内容
+- **发布到小红书**：将当前文档发布到小红书平台
+
+#### 第二行：样式控制
+```
++------------------------------------------------------------+
+| 模板 [▼] | 主题 [▼] | 字体 [▼] | 字体大小 [-][16][+]      |
++------------------------------------------------------------+
+```
+
+功能说明：
+- **模板选择**：选择不同的页面模板（默认/简约/杂志，目前为占位功能）
+- **主题选择**：选择文章样式主题（同微信公众号的主题）
+- **字体选择**：选择文章字体（系统默认/宋体/黑体/楷体/仿宋）
+- **字体大小**：调整文章字号（12-24px，默认16px）
+
+#### 主题选择
+- 与插件设置中的主题列表同步
+- 可选择不同的文章样式主题
+- 实时切换预览效果
+
+#### 字体选择
+- 系统默认
+- 宋体
+- 黑体
+- 楷体
+- 仿宋
+
+#### 字号调整
+- 点击 `-` 减小字号（最小 12px）
+- 点击 `+` 增大字号（最大 24px）
+- 默认 16px
+- 所有文本同步调整
+
+### 2.4 预览区域
+
+显示当前页面的渲染内容，包含：
+- 应用选定的主题样式
+- 应用选定的字体
+- 应用调整后的字号
+- 按照切图比例渲染的页面
+
+### 2.5 分页导航
+```
++------------------------------------------------------------+
+|              [←]      1/5      [→]                         |
++------------------------------------------------------------+
+```
+
+功能说明：
+- **左箭头 (←)**：切换到上一页
+- **页码显示**：显示当前页码和总页数
+- **右箭头 (→)**：切换到下一页
+
+### 2.6 底部操作栏
+```
++------------------------------------------------------------+
+|         [⬇ 当前页切图]    [⬇⬇ 全部页切图]                |
++------------------------------------------------------------+
+```
+
+功能说明：
+- **当前页切图**：将当前显示的页面保存为图片
+- **全部页切图**：批量保存所有页面为图片
+
+## 3. 使用流程
+
+### 3.1 基本使用
+1. 打开一个 Markdown 笔记
+2. 在预览面板点击"发布平台"下拉框
+3. 选择"小红书"
+4. 界面自动切换到小红书预览模式
+5. 系统自动分页并显示第一页
+
+### 3.2 调整样式
+1. 在第二行工具栏选择主题、字体
+2. 使用 `+` `-` 按钮调整字号
+3. 预览区实时更新
+
+### 3.3 浏览页面
+1. 使用分页导航的左右箭头切换页面
+2. 查看页码了解总页数
+3. 检查每一页的内容完整性
+
+### 3.4 刷新预览
+1. 修改文档内容后
+2. 点击"刷新"按钮
+3. 系统重新渲染并分页
+
+### 3.5 切图导出
+1. 浏览到需要导出的页面
+2. 点击"当前页切图"保存该页
+3. 或点击"全部页切图"批量保存所有页面
+4. 图片保存在配置的路径（默认：`/Users/gavin/note2mp/images/xhs`）
+
+### 3.6 发布到小红书
+1. 确认内容无误
+2. 点击"发布到小红书"按钮
+3. 系统自动上传内容和图片
+
+## 4. 分页规则
+
+系统会根据以下规则自动分页：
+
+1. **页面高度计算**
+   - 页面高度 = 切图宽度 × (比例高 / 比例宽)
+   - 例如：1080px × (4/3) = 1440px
+
+2. **智能分页**
+   - 普通段落：允许跨页（10% 溢出容差）
+   - 表格：不跨页，整体显示在一页
+   - 图片：不跨页，整体显示在一页
+   - 代码块：不跨页
+   - 公式：不跨页
+
+3. **分页导航**
+   - 点击 `←` 上一页
+   - 点击 `→` 下一页
+   - 显示当前页码 / 总页数
+
+## 5. 切图操作
+
+#### 当前页切图
+1. 浏览到想要切图的页面
+2. 点击"⬇ 当前页切图"按钮
+3. 等待处理完成
+4. 查看保存路径
+
+**文件命名：** `{slug}_1.png`（页码从 1 开始）
+
+#### 全部页切图
+1. 点击"⇓ 全部页切图"按钮
+2. 系统会依次处理每一页
+3. 显示进度提示
+4. 全部完成后提示
+
+**文件命名：** `{slug}_1.png`, `{slug}_2.png`, `{slug}_3.png` ...
+
+### 6. Frontmatter 配置
+
+在笔记的 frontmatter 中添加：
+
+```yaml
+---
+title: 我的小红书笔记
+slug: xiaohongshu-demo
+---
+```
+
+- **title**: 笔记标题（可选）
+- **slug**: 文件名标识符（必需，用于切图文件命名）
+
+*如果未设置 `slug`，将使用文件名（不含扩展名）*
+
+### 7. 切图配置
+
+在插件设置 → 切图配置中：
+
+- **切图保存路径**: `/Users/gavin/note2mp/images/xhs`
+- **切图宽度**: `1080` px
+- **切图横竖比例**: `3:4`（小红书推荐）
+
+## 技术细节
+
+### 分页算法
+
+1. **测量高度**
+   - 创建临时隐藏容器
+   - 按目标宽度渲染每个元素
+   - 测量实际高度
+
+2. **累计判断**
+   - 逐个元素累加高度
+   - 判断是否超出页面高度
+   - 不可分割元素单独处理
+
+3. **页面包装**
+   - 每页内容独立包装
+   - 应用统一样式
+   - 确保渲染一致
+
+### 切图流程
+
+1. **临时调整宽度**
+   ```typescript
+   pageElement.style.width = '1080px';
+   ```
+
+2. **渲染为图片**
+   ```typescript
+   await toPng(pageElement, {
+       width: 1080,
+       pixelRatio: 1,
+       cacheBust: true
+   });
+   ```
+
+3. **保存文件**
+   ```typescript
+   fs.writeFileSync(filepath, buffer);
+   ```
+
+4. **恢复样式**
+   ```typescript
+   pageElement.style.width = originalWidth;
+   ```
+
+## 常见问题
+
+### Q: 为什么分页后内容看起来不连续？
+A: 这是正常的。系统按页面高度自动分割内容，每页是独立的截图单元。如果需要更连续的效果，可以调整切图比例使页面更高。
+
+### Q: 表格被截断了？
+A: 表格应该不会跨页。如果出现截断，可能是表格本身高度超过单页限制。建议：
+- 拆分大表格
+- 调整比例使页面更高
+- 使用横向比例（如 4:3）
+
+### Q: 字体设置不生效？
+A: 确保：
+1. 已选择具体字体（不是"系统默认"）
+2. 切换页面后重新预览
+3. 系统中已安装该字体
+
+### Q: 切图后图片模糊？
+A: 检查：
+1. 切图宽度设置（建议 1080 或更高）
+2. 浏览器缩放比例（建议 100%）
+3. 原始内容清晰度
+
+### Q: 如何调整页面内边距？
+A: 当前版本内边距固定为 40px。如需自定义，可修改 `paginator.ts` 中的 `renderPage` 函数：
+
+```typescript
+padding: 40px;  // 改为需要的值
+```
+
+## 最佳实践
+
+### 📝 内容编写建议
+
+1. **段落长度**
+   - 避免过长的段落
+   - 适当使用小标题分割
+   - 利于阅读和分页
+
+2. **图片使用**
+   - 图片宽度不要超过 1000px
+   - 高度控制在 1200px 以内
+   - 避免超高图片影响分页
+
+3. **表格设计**
+   - 表格高度控制在单页范围内
+   - 复杂表格考虑拆分
+   - 使用简洁的表格样式
+
+### 🎨 样式调整建议
+
+1. **字号选择**
+   - 正文：16px（默认）
+   - 引用/注释：14-15px
+   - 标题：18-20px
+
+2. **字体搭配**
+   - 正文：宋体/黑体（清晰）
+   - 标题：黑体（醒目）
+   - 代码：系统默认（等宽）
+
+3. **主题选择**
+   - 小红书风格：简约、清新主题
+   - 避免过于花哨的样式
+   - 保持视觉一致性
+
+### 💡 切图技巧
+
+1. **批量处理**
+   - 多篇笔记：使用"全部页切图"
+   - 检查预览：先看每一页效果
+   - 按需调整：修改后重新切图
+
+2. **文件管理**
+   - 使用有意义的 slug
+   - 按主题组织目录
+   - 定期清理旧文件
+
+3. **质量保证**
+   - 切图前检查预览
+   - 确认分页合理
+   - 验证文件命名
+
+## 示例配置
+
+### 小红书竖图（推荐）
+```
+宽度：1080px
+比例：3:4
+页面高度：1440px
+```
+
+### 小红书方图
+```
+宽度：1080px
+比例：1:1
+页面高度：1080px
+```
+
+### 高清竖图
+```
+宽度：1440px
+比例：9:16
+页面高度：2560px
+```
+
+---
+
+**提示**: 
+- 首次使用建议先用短笔记测试分页效果
+- 调整好配置后再处理长篇内容
+- 保存好配置以便下次使用
+
+**已知限制**:
+- 移动端不支持（需要 Node.js fs API）
+- 模板功能暂为占位（后续版本实现）
+- 主题切换需要重新刷新预览