drawio-to-png

Draw.io 转 PNG 转换器

使用 draw.io 桌面版命令行界面或无头浏览器自动化，将 draw.io 图表文件转换为高分辨率 PNG 图像。

概述

此技能提供将 draw.io 格式文件（.drawio、.dio、.xml）转换为高质量 PNG 图像的指导。支持批量转换、自定义分辨率设置、透明背景，以及多页图表的页面选择。

适用场景

在以下情况下使用此技能：

• 将 draw.io 图表转换为 PNG，用于文档
• 导出图表，用于演示文稿或文章
• 从 draw.io 文件生成图像，用于网络发布
• 批量处理多个图表文件
• 创建用于印刷材料的高 DPI 图像

触发短语

• “将 drawio 转换为 png”
• “导出 drawio 图表”
• “从 drawio 生成 png”
• “drawio导出png”
• “转换drawio图片”
• “drawio转图片”
• “生成高清drawio图片”
• “批量导出drawio”

转换方法

方法 1：使用 draw.io 桌面版 CLI（推荐）

官方 draw.io 桌面应用提供用于转换的命令行界面。

安装：

# macOS
brew install --cask drawio

# Or download from: https://github.com/jgraph/drawio-desktop/releases

基本转换：

# Convert single file
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -o output.png input.drawio

# With custom scale (higher DPI)
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -s 2 -o output.png input.drawio

# Transparent background
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png --transparent -o output.png input.drawio

# Export specific page (for multi-page diagrams)
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -p 0 -o output.png input.drawio

参数：

• -x：导出模式
• -f png：输出格式（png）
• -o：输出文件路径
• -s <scale>：缩放比例（1.0 = 100%，2.0 = 200% 等）
• --transparent：透明背景
• -p <page>：多页图表的页面索引（从 0 开始）
• -w <width>：自定义宽度，单位为像素
• -h <height>：自定义高度，单位为像素
• --border <size>：边框大小，单位为像素

方法 2：使用 Puppeteer 和 draw.io 网页版

使用无头浏览器自动化，通过 draw.io 网页界面渲染图表。

安装：

npm install puppeteer

转换脚本（参见 scripts/convert-with-puppeteer.js）：

const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');

async function convertDrawioToPng(inputPath, outputPath, options = {}) {
  const {
    scale = 2,
    transparent = true,
    page = 0
  } = options;

  const browser = await puppeteer.launch();
  const browserPage = await browser.newPage();
  
  // Set viewport for high DPI
  await browserPage.setViewport({
    width: 1920,
    height: 1080,
    deviceScaleFactor: scale
  });

  // Read drawio file
  const drawioContent = fs.readFileSync(inputPath, 'utf8');
  const encoded = encodeURIComponent(drawioContent);
  
  // Load in draw.io viewer
  await browserPage.goto(`https://viewer.diagrams.net/?lightbox=1&edit=_blank#R${encoded}`);
  
  // Wait for diagram to render
  await browserPage.waitForSelector('.geDiagramContainer', { timeout: 10000 });
  await browserPage.waitForTimeout(1000);

  // Take screenshot
  const element = await browserPage.$('.geDiagramContainer');
  await element.screenshot({
    path: outputPath,
    omitBackground: transparent
  });

  await browser.close();
}

方法 3：使用 @diagram.net/drawio-cli（Docker）

官方基于 Docker 的 CLI 工具。

安装：

docker pull rlespinasse/drawio-cli

转换：

docker run --rm -v "$(pwd):/data" rlespinasse/drawio-cli \
  -x -f png -s 2 -o /data/output.png /data/input.drawio

工作流

单文件转换

1. 检测 draw.io 文件格式

   • 检查文件是否存在且有效（.drawio、.dio、.xml）
   • 确认文件为 XML 格式且包含 draw.io 结构

2. 确定输出路径

   • 默认：使用相同目录和文件名，并将扩展名设为 .png
   • 如需自定义输出路径，询问用户

3. 配置选项

   • 缩放比例（默认值：2，适用于高 DPI）
   • 透明背景（默认值：true）
   • 页面选择（如果是多页图表）

4. 执行转换

   • 优先使用 draw.io CLI（方法 1）
   • 如果 CLI 不可用，则使用 Puppeteer

5. 验证输出

   • 检查 PNG 文件是否已创建
   • 验证文件大小是否合理
   • 向用户显示输出路径

批量转换

1. 扫描目录中的 draw.io 文件

   find . -type f \( -name "*.drawio" -o -name "*.dio" -o -name "*.xml" \)
   

2. 筛选有效的 draw.io 文件

   • 排除非图表 XML 文件
   • 检查文件内容是否包含 draw.io 结构

3. 处理每个文件

   • 使用相同的命名约定（将扩展名替换为 .png）
   • 应用一致的导出设置
   • 记录每个文件的成功或失败情况

4. 报告结果

   • 列出已成功转换的文件
   • 说明失败及其原因
   • 显示总数和输出位置

常见用例

用于文档

# Export with border for better visibility
drawio -x -f png -s 2 --border 10 -o docs/images/architecture.png architecture.drawio

用于演示文稿幻灯片

# High resolution with transparent background
drawio -x -f png -s 3 --transparent -o slides/diagram.png diagram.drawio

用于网络发布

# Moderate resolution to balance quality and file size
drawio -x -f png -s 1.5 -o public/images/flowchart.png flowchart.drawio

多页图表

# Export all pages
for i in {0..4}; do
  drawio -x -f png -s 2 -p $i -o "output-page-$i.png" multi-page.drawio
done

质量设置

缩放比例指南

• 1.0：标准分辨率（72-96 DPI）——网页缩略图
• 2.0：高分辨率（144-192 DPI）——标准导出（推荐）
• 3.0：超高分辨率（216-288 DPI）——演示文稿
• 4.0：印刷质量（288-384 DPI）——专业印刷

文件大小注意事项

• 缩放比例越高，文件越大
• 透明背景会略微增加文件大小
• 包含大量形状的复杂图表会生成较大的文件
• 网页使用时可考虑压缩

错误处理

常见问题

1. 找不到 draw.io CLI

   • 检查是否已安装 draw.io 桌面版
   • 验证路径：/Applications/draw.io.app/Contents/MacOS/draw.io（macOS）
   • 尝试其他方法（Puppeteer 或 Docker）

2. draw.io 文件无效

   • 确认文件为 XML 格式
   • 检查文件内容是否损坏
   • 在 draw.io 桌面版中打开并验证

3. 导出失败但没有报错

   • 检查磁盘空间
   • 确认输出目录具有写入权限
   • 尝试使用更简单的图表，以定位问题

4. 输出为空白或不完整

   • 复杂图表可增加等待时间
   • 检查是否引用了外部图片
   • 确认所需字体均可用

最佳实践

1. 版本控制

   • 将 .drawio 源文件纳入版本控制
   • 按需重新生成 PNG 文件（不要提交）
   • 使用 CI/CD 自动生成图片

2. 命名约定

   • .drawio 和 .png 文件使用相同名称
   • 为不同缩放比例添加后缀：diagram-2x.png、diagram-3x.png
   • 多页文件包含页码：flow-page-1.png

3. 自动化

   • 创建 npm 脚本或 Makefile 以进行批量转换
   • 监视文件变更并自动重新生成
   • 集成到文档构建流程中

4. 优化

   • 根据使用场景选择合适的缩放比例
   • 使用 pngquant 或 optipng 等工具压缩 PNG 文件
   • 考虑导出为 SVG 格式以用于网页（文件更小且可缩放）

其他格式

虽然此技能侧重于导出 PNG，draw.io 也支持：

• SVG：矢量格式，可缩放，文件更小
• PDF：适合打印，可保留画质
• JPEG：文件更小，不支持透明，采用有损压缩

使用 scripts/convert.sh 灵活选择格式。

参考资料

参见 references/ 目录：

• cli-reference.md：完整的 draw.io CLI 文档
• quality-guide.md：详细的画质和 DPI 指南
• automation-examples.md：用于 CI/CD 集成的脚本

示例

参见 examples/ 目录：

• single-file.sh：单文件转换示例
• batch-convert.sh：批量转换脚本
• watch-and-convert.sh：用于自动转换的文件监视器