feat: Implement Canvas rendering system and VitePress exporter plugin
- Add Canvas rendering implementation in `notes/render-canvas.md` - Create VitePress exporter plugin in `src/main.ts` with commands for exporting notes - Implement settings management for the plugin in `src/settings.ts` - Add CSS file for potential styling needs - Create version bump script in `version-bump.mjs` for managing versioning - Initialize version tracking in `versions.json`
This commit is contained in:
397
notes/render-canvas.md
Normal file
397
notes/render-canvas.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# Canvas 渲染系统实现
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **渲染方式**: Obsidian Canvas 内部 API (`takeScreenshot`)
|
||||
- **缩放控制**: `canvas.zoom` 属性（对数刻度）
|
||||
- **语言**: TypeScript
|
||||
|
||||
## 核心实现
|
||||
|
||||
### 1. Canvas 捕获流程
|
||||
|
||||
```typescript
|
||||
async renderCanvas(canvasFile: TFile): Promise<Uint8Array | null> {
|
||||
// 1. 获取活动 leaf
|
||||
const activeLeaf = this.app.workspace.getLeaf();
|
||||
if (!activeLeaf) return null;
|
||||
|
||||
// 2. 打开 Canvas 文件
|
||||
await activeLeaf.openFile(canvasFile);
|
||||
|
||||
// 3. 获取 Canvas 对象
|
||||
const canvas = activeLeaf.view.canvas;
|
||||
if (!canvas) return null;
|
||||
|
||||
// 4. 使用内部 API 导出
|
||||
return await this.exportCanvasWithInternalAPI(canvas, canvasFile);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用 Canvas 内部 API
|
||||
|
||||
```typescript
|
||||
async exportCanvasWithInternalAPI(
|
||||
canvas: any,
|
||||
canvasFile: TFile
|
||||
): Promise<Uint8Array | null> {
|
||||
try {
|
||||
// 1. 获取边界框
|
||||
const bbox = canvas.getViewportBBox();
|
||||
const contentWidth = bbox.maxX - bbox.minX;
|
||||
const contentHeight = bbox.maxY - bbox.minY;
|
||||
|
||||
// 2. 设置 zoom = 0 (100% 缩放)
|
||||
const oldZoom = canvas.zoom;
|
||||
canvas.zoom = 0; // 对数刻度：2^0 = 1.0 (100%)
|
||||
|
||||
// 3. 请求重绘
|
||||
canvas.requestFrame();
|
||||
await new Promise(resolve => setTimeout(resolve, 100));
|
||||
await new Promise(resolve => requestAnimationFrame(resolve));
|
||||
|
||||
// 4. 生成文件路径
|
||||
const tempFileName = `temp_canvas_${Date.now()}.png`;
|
||||
const finalFileName = canvasFile.name.replace(".canvas", ".png");
|
||||
const finalPath = `${this.settings.assetsPath}/${finalFileName}`;
|
||||
|
||||
// 5. 获取 vault 绝对路径
|
||||
const vaultBasePath = vault.adapter.basePath;
|
||||
const tempFullPath = `${vaultBasePath}/${tempFileName}`;
|
||||
|
||||
// 6. 调用 takeScreenshot（需要绝对路径）
|
||||
await canvas.takeScreenshot(tempFullPath, false);
|
||||
|
||||
// 7. 等待文件写入完成
|
||||
await new Promise(resolve => setTimeout(resolve, 100));
|
||||
|
||||
// 8. 读取临时文件（使用相对路径）
|
||||
const imageBuffer = await vault.adapter.readBinary(tempFileName);
|
||||
|
||||
if (!imageBuffer || imageBuffer.byteLength === 0) {
|
||||
console.error("Failed to read temporary file");
|
||||
return null;
|
||||
}
|
||||
|
||||
// 9. 删除临时文件
|
||||
await vault.adapter.remove(tempFileName);
|
||||
|
||||
// 10. 写入到最终位置
|
||||
await vault.adapter.writeBinary(finalPath, imageBuffer);
|
||||
|
||||
// 11. 返回 Uint8Array
|
||||
return new Uint8Array(imageBuffer);
|
||||
|
||||
} catch (error) {
|
||||
console.error("exportCanvasWithInternalAPI failed:", error);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Canvas Zoom 对数刻度
|
||||
|
||||
**关键发现**：`canvas.zoom` 使用对数刻度（base 2）
|
||||
|
||||
| zoom 值 | 缩放比例 | 说明 |
|
||||
|---------|----------|------|
|
||||
| 0 | 100% (2^0) | 原始尺寸，我们要设置的值 |
|
||||
| 1 | 200% (2^1) | 放大 2 倍 |
|
||||
| -1 | 50% (2^-1) | 缩小一半 |
|
||||
| -1.76 | ~30% | Obsidian 默认缩放 |
|
||||
|
||||
**重要**：不要设置 `zoom = 1.0`，这会让 Canvas 放大到 200%！应该设置 `zoom = 0`。
|
||||
|
||||
### 4. 链接更新
|
||||
|
||||
Canvas 引用会被转换为 Viewer 组件：
|
||||
|
||||
```typescript
|
||||
updateCanvasLinksInContent(content: string, canvasFile: TFile, canvasPath: string, imageFileName: string): string {
|
||||
// 支持多种路径格式
|
||||
const possiblePaths = [
|
||||
canvasPath, // 完整路径
|
||||
canvasPath.substring(sourceDir.length + 1), // 相对路径
|
||||
encodeURI(canvasPath), // URL 编码
|
||||
canvasFile.name, // 文件名
|
||||
canvasFile.name.replace('.canvas', ''), // 不带扩展名
|
||||
];
|
||||
|
||||
// 替换 Markdown 格式
|
||||
const markdownRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
|
||||
content = content.replace(markdownRegex, (match, alt, path) => {
|
||||
if (path匹配) {
|
||||
const relativePath = this.settings.assetsPath.replace('docs/', '');
|
||||
return `<Viewer src="${relativePath}/${imageFileName}" />`;
|
||||
}
|
||||
return match;
|
||||
});
|
||||
|
||||
// 替换 Wikilink 格式
|
||||
const wikilinkRegex = /!\[\[([^\]]+)\]\]/g;
|
||||
content = content.replace(wikilinkRegex, (match, link) => {
|
||||
if (link匹配) {
|
||||
const relativePath = this.settings.assetsPath.replace('docs/', '');
|
||||
return `<Viewer src="${relativePath}/${imageFileName}" />`;
|
||||
}
|
||||
return match;
|
||||
});
|
||||
|
||||
return content;
|
||||
}
|
||||
```
|
||||
|
||||
## 渲染流程
|
||||
|
||||
```
|
||||
1. 打开 Canvas 文件
|
||||
└─> activeLeaf.openFile(canvasFile)
|
||||
|
||||
2. 获取 Canvas 对象
|
||||
└─> activeLeaf.view.canvas
|
||||
|
||||
3. 调用 exportCanvasWithInternalAPI
|
||||
├─> 获取视口边界框
|
||||
├─> 设置 zoom = 0 (100%)
|
||||
├─> 请求重绘
|
||||
├─> 等待 100ms + requestAnimationFrame
|
||||
├─> 调用 takeScreenshot(绝对路径)
|
||||
├─> 读取临时文件
|
||||
├─> 删除临时文件
|
||||
└─> 写入到 docs/assets/
|
||||
|
||||
4. 更新内容中的链接
|
||||
└─> 转换为 <Viewer src="assets/xxx.png" />
|
||||
```
|
||||
|
||||
## 在资源处理中的集成
|
||||
|
||||
Canvas 渲染是资源处理流程的一部分：
|
||||
|
||||
```typescript
|
||||
async processAssets(content: string, sourceFile: TFile): Promise<string> {
|
||||
const cache = metadataCache.getCache(sourceFile.path);
|
||||
const canvasFiles = new Set<string>();
|
||||
|
||||
// 1. 收集 Canvas 文件
|
||||
if (cache.embeds) {
|
||||
for (const embed of cache.embeds) {
|
||||
const resolvedLink = metadataCache.getFirstLinkpathDest(embed.link, sourceFile.path);
|
||||
if (resolvedLink?.extension === 'canvas') {
|
||||
canvasFiles.add(resolvedLink.path);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 渲染每个 Canvas
|
||||
for (const canvasPath of canvasFiles) {
|
||||
try {
|
||||
const canvasFile = vault.getAbstractFileByPath(canvasPath);
|
||||
if (canvasFile instanceof TFile) {
|
||||
const renderedImage = await this.captureCanvas(canvasFile);
|
||||
if (renderedImage) {
|
||||
const imageFileName = canvasFile.name.replace('.canvas', '.png');
|
||||
const imagePath = `${this.settings.assetsPath}/${imageFileName}`;
|
||||
|
||||
// 确保 assets 目录存在
|
||||
await vault.adapter.mkdir(this.settings.assetsPath);
|
||||
|
||||
// 写入渲染的图片
|
||||
await vault.adapter.writeBinary(imagePath, renderedImage.buffer);
|
||||
|
||||
// 更新内容中的 canvas 引用
|
||||
content = this.updateCanvasLinksInContent(content, canvasFile, canvasPath, imageFileName);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(`Failed to render canvas ${canvasPath}:`, error);
|
||||
}
|
||||
}
|
||||
|
||||
return content;
|
||||
}
|
||||
```
|
||||
|
||||
## 优势
|
||||
|
||||
1. **完全使用 Obsidian 内部 API**
|
||||
- 不依赖第三方库（html-to-image）
|
||||
- 兼容性好，Obsidian 升级时应该能正常工作
|
||||
- 代码简洁，维护方便
|
||||
|
||||
2. **正确的缩放控制**
|
||||
- 使用对数刻度的 `zoom` 属性
|
||||
- 设置 `zoom = 0` 获得准确的 100% 缩放
|
||||
- 每个元素都是原始尺寸
|
||||
|
||||
3. **路径处理灵活**
|
||||
- 支持多种路径格式（绝对、相对、URL 编码）
|
||||
- 自动转换为正确的相对路径
|
||||
- 支持 Markdown 和 Wikilink 两种格式
|
||||
|
||||
4. **错误隔离**
|
||||
- 单个 Canvas 渲染失败不影响其他文件
|
||||
- 在控制台输出详细错误信息
|
||||
- 继续处理后续资源
|
||||
|
||||
## 测试方法
|
||||
|
||||
### 1. 基本功能测试
|
||||
|
||||
创建测试 Canvas 文件：
|
||||
- 小尺寸: 800x600
|
||||
- 大尺寸: 4000x3000
|
||||
- 包含多个节点和连接
|
||||
|
||||
### 2. 验证步骤
|
||||
|
||||
1. **创建测试笔记**，包含 Canvas 引用
|
||||
```markdown
|
||||
# 测试笔记
|
||||
|
||||
这是一个 Canvas：
|
||||
![[test.canvas]]
|
||||
```
|
||||
|
||||
2. **执行导出命令**
|
||||
|
||||
3. **检查控制台输出**：
|
||||
```
|
||||
Processing assets for file: test.md
|
||||
Canvas files to render: ['test.canvas']
|
||||
Successfully rendered canvas: test.canvas -> docs/assets/test.png
|
||||
```
|
||||
|
||||
4. **检查输出文件**：
|
||||
- 图片位置：`docs/assets/test.png`
|
||||
- 图片尺寸应该等于 Canvas 的实际内容尺寸
|
||||
- 文字清晰，没有缩水
|
||||
- 导出后的笔记内容被更新
|
||||
|
||||
### 3. 路径格式测试
|
||||
|
||||
测试各种路径格式的 Canvas 引用：
|
||||
|
||||
```markdown
|
||||
![[test.canvas]] # 文件名
|
||||
![[folder/test.canvas]] # 相对路径
|
||||
 # Markdown 格式
|
||||
 # Markdown 相对路径
|
||||
![[test.canvas|别名]] # 带别名
|
||||
 # URL 编码
|
||||
```
|
||||
|
||||
所有格式都应该被正确识别和转换。
|
||||
|
||||
## API 参考
|
||||
|
||||
### Canvas 内部方法
|
||||
|
||||
| 方法 | 参数 | 返回值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `getViewportBBox()` | - | `{minX, minY, maxX, maxY}` | 获取视口边界框 |
|
||||
| `takeScreenshot(path, privacy)` | `path: string`, `privacy: boolean` | `Promise<void>` | 截图并保存到文件 |
|
||||
| `requestFrame()` | - | - | 请求重绘 |
|
||||
| `zoom` 属性 | - | `number` | 对数刻度缩放（0 = 100%） |
|
||||
|
||||
### Workspace API
|
||||
|
||||
| 方法 | 参数 | 返回值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `getLeaf()` | - | `WorkspaceLeaf` | 获取活动 leaf |
|
||||
| `openFile(file)` | `TFile` | `Promise<void>` | 打开文件 |
|
||||
|
||||
### Vault API
|
||||
|
||||
| 方法 | 参数 | 返回值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `adapter.readBinary(path)` | `string` | `Promise<ArrayBuffer>` | 读取二进制文件 |
|
||||
| `adapter.writeBinary(path, data)` | `string, ArrayBuffer` | `Promise<void>` | 写入二进制文件 |
|
||||
| `adapter.mkdir(path)` | `string` | `Promise<void>` | 创建目录 |
|
||||
| `adapter.remove(path)` | `string` | `Promise<void>` | 删除文件 |
|
||||
|
||||
### 重要常量
|
||||
|
||||
- `zoom = 0` → 100% 缩放
|
||||
- `zoom = 1` → 200% 缩放
|
||||
- `zoom = -1` → 50% 缩放
|
||||
- `zoom = Math.log2(scale)` → zoom 和缩放的转换公式
|
||||
|
||||
## 已知问题
|
||||
|
||||
1. **临时文件处理**
|
||||
- `takeScreenshot` 需要**绝对文件系统路径**
|
||||
- 必须先保存到临时文件，然后读取并移动
|
||||
- 临时文件会自动清理
|
||||
|
||||
2. **路径获取**
|
||||
- 使用 `vault.adapter.basePath` 获取 vault 的完整路径
|
||||
- 这是 Obsidian 的内部 API，可能在未来版本中变化
|
||||
|
||||
3. **同步问题**
|
||||
- 需要等待 `takeScreenshot` 完成
|
||||
- 使用 `setTimeout` 和 `requestAnimationFrame` 确保渲染完成
|
||||
- 时间可能需要根据实际情况调整
|
||||
|
||||
## 故障排除
|
||||
|
||||
### Canvas 渲染失败
|
||||
|
||||
**问题**：Canvas 没有被渲染成图片
|
||||
|
||||
**可能原因**：
|
||||
1. Canvas 文件路径不正确
|
||||
2. Canvas 对象获取失败
|
||||
3. `takeScreenshot` 调用失败
|
||||
4. 临时文件读写权限问题
|
||||
|
||||
**解决方法**：
|
||||
- 检查控制台日志
|
||||
- 确认 Canvas 文件存在且可打开
|
||||
- 检查文件系统权限
|
||||
|
||||
### 图片质量差
|
||||
|
||||
**问题**：渲染的图片模糊或尺寸不正确
|
||||
|
||||
**可能原因**：
|
||||
- zoom 值设置不正确
|
||||
- Canvas 节点被折叠
|
||||
|
||||
**解决方法**：
|
||||
- 确认 `zoom = 0`（100%）
|
||||
- 检查 Canvas 是否有折叠的节点
|
||||
- 增加等待时间确保完全渲染
|
||||
|
||||
### 链接没有更新
|
||||
|
||||
**问题**：导出后 Canvas 引用没有被替换
|
||||
|
||||
**可能原因**：
|
||||
- 路径格式不支持
|
||||
- 正则表达式不匹配
|
||||
|
||||
**解决方法**：
|
||||
- 检查链接格式（Markdown vs Wikilink）
|
||||
- 查看控制台日志确认路径匹配
|
||||
- 添加更多路径格式支持
|
||||
|
||||
## 未来改进
|
||||
|
||||
1. **进度反馈**
|
||||
- 添加渲染进度提示
|
||||
- 显示 Canvas 尺寸和预计时间
|
||||
|
||||
2. **错误处理**
|
||||
- 更详细的错误信息
|
||||
- 降级方案（如果 takeScreenshot 不可用）
|
||||
|
||||
3. **性能优化**
|
||||
- 缓存已渲染的 Canvas
|
||||
- 避免重复截图
|
||||
- 并行处理多个 Canvas
|
||||
|
||||
4. **更多格式**
|
||||
- 支持 JPEG、WebP 等格式
|
||||
- 可配置的图片质量
|
||||
- 可配置的分辨率
|
||||
Reference in New Issue
Block a user