drawio-to-png

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io to PNG Converter

Draw.io 转 PNG 转换器

Convert draw.io diagram files to high-resolution PNG images using draw.io desktop command-line interface or headless browser automation.

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

Overview

概述

This skill provides guidance for converting draw.io format files (.drawio, .dio, .xml) to high-quality PNG images. It supports batch conversion, custom resolution settings, transparent backgrounds, and page selection for multi-page diagrams.

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

When to Use

适用场景

Use this skill when:

Converting draw.io diagrams to PNG for documentation
Exporting diagrams for presentations or articles
Generating images from draw.io files for web publishing
Batch processing multiple diagram files
Creating high-DPI images for print materials

在以下场景中使用本工具：

将draw.io图表转换为PNG格式用于文档制作
导出图表用于演示文稿或文章
从drawio生成PNG图片用于网页发布
批量处理多个图表文件
创建高DPI图片用于印刷物料

Trigger Phrases

触发短语

"convert drawio to png"
"export drawio diagram"
"generate png from drawio"
"drawio导出png"
"转换drawio图片"
"drawio转图片"
"生成高清drawio图片"
"批量导出drawio"

"将drawio转换为PNG"
"导出drawio图表"
"从drawio生成PNG"
"drawio导出png"
"转换drawio图片"
"drawio转图片"
"生成高清drawio图片"
"批量导出drawio"

Conversion Methods

转换方法

Method 1: Using draw.io Desktop CLI (Recommended)

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

The official draw.io desktop application provides a command-line interface for conversion.

Installation:

bash

undefined

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

安装：

bash

undefined

macOS

brew install --cask drawio

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

或从以下地址下载：https://github.com/jgraph/drawio-desktop/releases


**Basic Conversion**:
```bash


**基础转换**：
```bash

Convert single file

转换单个文件

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

With custom scale (higher DPI)

自定义缩放比例（更高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


**Parameters**:
- `-x`: Export mode
- `-f png`: Output format (png)
- `-o`: Output file path
- `-s <scale>`: Scale factor (1.0 = 100%, 2.0 = 200%, etc.)
- `--transparent`: Transparent background
- `-p <page>`: Page index (0-based) for multi-page diagrams
- `-w <width>`: Custom width in pixels
- `-h <height>`: Custom height in pixels
- `--border <size>`: Border size in pixels

/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>`: 边框像素大小

Method 2: Using Puppeteer with draw.io Web

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

Use headless browser automation to render diagrams via draw.io web interface.

Installation:

bash

npm install puppeteer

Conversion Script (see

scripts/convert-with-puppeteer.js

javascript

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();
}

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

安装：

bash

npm install puppeteer

转换脚本（详见

scripts/convert-with-puppeteer.js

）：

javascript

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();
  
  // 设置高DPI视口
  await browserPage.setViewport({
    width: 1920,
    height: 1080,
    deviceScaleFactor: scale
  });

  // 读取drawio文件
  const drawioContent = fs.readFileSync(inputPath, 'utf8');
  const encoded = encodeURIComponent(drawioContent);
  
  // 在draw.io查看器中加载
  await browserPage.goto(`https://viewer.diagrams.net/?lightbox=1&edit=_blank#R${encoded}`);
  
  // 等待图表渲染完成
  await browserPage.waitForSelector('.geDiagramContainer', { timeout: 10000 });
  await browserPage.waitForTimeout(1000);

  // 截取屏幕截图
  const element = await browserPage.$('.geDiagramContainer');
  await element.screenshot({
    path: outputPath,
    omitBackground: transparent
  });

  await browser.close();
}

Method 3: Using @diagram.net/drawio-cli (Docker)

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

Official Docker-based CLI tool.

Installation:

bash

docker pull rlespinasse/drawio-cli

Conversion:

bash

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

基于Docker的官方CLI工具。

安装：

bash

docker pull rlespinasse/drawio-cli

转换命令：

bash

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

Workflow

工作流程

Single File Conversion

单个文件转换

Detect draw.io file format
- Check if file exists and is valid (.drawio, .dio, .xml)
- Verify file is XML format and contains draw.io structure
Determine output path
- Default: same directory, same name with .png extension
- Ask user if custom output path is needed
Configure options
- Scale factor (default: 2 for high DPI)
- Transparent background (default: true)
- Page selection (if multi-page)
Execute conversion
- Use draw.io CLI (Method 1) as primary method
- Fall back to Puppeteer if CLI not available
Verify output
- Check PNG file was created
- Validate file size is reasonable
- Show output path to user

检测draw.io文件格式
- 检查文件是否存在且有效（.drawio、.dio、.xml）
- 验证文件为XML格式且包含draw.io结构
确定输出路径
- 默认：与源文件同目录，同名且后缀为.png
- 询问用户是否需要自定义输出路径
配置选项
- 缩放比例（默认：2，对应高DPI）
- 透明背景（默认：开启）
- 页面选择（如果是多页图表）
执行转换
- 优先使用draw.io CLI（方法1）
- 若CLI不可用， fallback到Puppeteer方法
验证输出
- 检查PNG文件是否已创建
- 验证文件大小是否合理
- 向用户展示输出路径

Batch Conversion

批量转换

Scan directory for draw.io files

bash

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

Filter valid draw.io files
- Exclude non-diagram XML files
- Check file content for draw.io structure
Process each file
- Use same naming convention (replace extension with .png)
- Apply consistent export settings
- Track success/failure for each file
Report results
- List successfully converted files
- Report any failures with reasons
- Show total count and output location

扫描目录中的draw.io文件

bash

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

筛选有效的draw.io文件
- 排除非图表类XML文件
- 检查文件内容是否包含draw.io结构
处理每个文件
- 使用相同的命名规则（替换后缀为.png）
- 应用统一的导出设置
- 跟踪每个文件的转换成功/失败状态
报告结果
- 列出转换成功的文件
- 报告转换失败的文件及原因
- 显示总数量和输出位置

Common Use Cases

常见使用场景

For Documentation

用于文档制作

bash

undefined

bash

undefined

Export with border for better visibility

导出带边框的图片以提升可读性

drawio -x -f png -s 2 --border 10 -o docs/images/architecture.png architecture.drawio

undefined

drawio -x -f png -s 2 --border 10 -o docs/images/architecture.png architecture.drawio

undefined

For Presentation Slides

用于演示文稿

bash

undefined

bash

undefined

High resolution with transparent background

高分辨率且带透明背景

drawio -x -f png -s 3 --transparent -o slides/diagram.png diagram.drawio

undefined

drawio -x -f png -s 3 --transparent -o slides/diagram.png diagram.drawio

undefined

For Web Publishing

用于网页发布

bash

undefined

bash

undefined

Moderate resolution to balance quality and file size

中等分辨率，平衡质量与文件大小

drawio -x -f png -s 1.5 -o public/images/flowchart.png flowchart.drawio

undefined

drawio -x -f png -s 1.5 -o public/images/flowchart.png flowchart.drawio

undefined

Multi-page Diagrams

多页图表

bash

undefined

bash

undefined

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

undefined

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

undefined

Quality Settings

质量设置

Scale Factor Guidelines

缩放比例指南

```
1.0
```
: Standard resolution (72-96 DPI) - web thumbnails
```
2.0
```
: High resolution (144-192 DPI) - standard export (recommended)
```
3.0
```
: Very high resolution (216-288 DPI) - presentations
```
4.0
```
: Print quality (288-384 DPI) - professional printing

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

File Size Considerations

文件大小考量

Higher scale = larger file size
Transparent background slightly increases size
Complex diagrams with many shapes = larger files
Consider compression for web use

缩放比例越高，文件体积越大
透明背景会略微增加文件体积
包含大量形状的复杂图表文件体积更大
网页使用时可考虑压缩处理

Error Handling

错误处理

Common Issues

常见问题

draw.io CLI not found
- Check if draw.io desktop is installed
- Verify path:
```
/Applications/draw.io.app/Contents/MacOS/draw.io
```
  (macOS)
- Try alternative methods (Puppeteer or Docker)
Invalid draw.io file
- Verify file is XML format
- Check for corrupted file content
- Open in draw.io desktop to validate
Export fails silently
- Check disk space
- Verify write permissions for output directory
- Try with simpler diagram to isolate issue
Blank or partial output
- Increase wait time for complex diagrams
- Check for external image references
- Verify all fonts are available

draw.io CLI未找到
- 检查是否已安装draw.io桌面端
- 验证路径：macOS系统为
```
/Applications/draw.io.app/Contents/MacOS/draw.io
```
- 尝试替代方法（Puppeteer或Docker）
无效的draw.io文件
- 验证文件是否为XML格式
- 检查文件内容是否损坏
- 在draw.io桌面端打开以验证有效性
导出无提示失败
- 检查磁盘空间
- 验证输出目录的写入权限
- 尝试转换更简单的图表以排查问题
输出空白或不完整
- 为复杂图表增加等待时间
- 检查是否存在外部图片引用
- 验证所有字体是否可用

Best Practices

最佳实践

Version Control
- Keep .drawio source files in version control
- Regenerate PNG files on demand (don't commit)
- Use CI/CD to auto-generate images
Naming Convention
- Use same name for .drawio and .png files
- Add suffix for different scales:
```
diagram-2x.png
```
  ,
```
diagram-3x.png
```
- Include page number for multi-page:
```
flow-page-1.png
```
Automation
- Create npm scripts or Makefile for batch conversion
- Watch for file changes and auto-regenerate
- Integrate with documentation build process
Optimization
- Use appropriate scale for use case
- Compress PNG files with tools like
```
pngquant
```
  or
```
optipng
```
- Consider SVG export for web (smaller, scalable)

版本控制
- 将.draw.io源文件纳入版本控制
- 按需重新生成PNG文件（不要提交到版本库）
- 使用CI/CD自动生成图片
命名规范
- .drawio文件与.png文件使用相同名称
- 为不同缩放比例添加后缀：
```
diagram-2x.png
```
  、
```
diagram-3x.png
```
- 为多页图表添加页码：
```
flow-page-1.png
```
自动化
- 创建npm脚本或Makefile用于批量转换
- 监听文件变化并自动重新生成
- 与文档构建流程集成
优化
- 根据使用场景选择合适的缩放比例
- 使用
```
pngquant
```
  或
```
optipng
```
  等工具压缩PNG文件
- 网页使用时可考虑导出SVG格式（体积更小、可缩放）

Alternative Formats

替代格式

While this skill focuses on PNG export, draw.io also supports:

SVG: Vector format, scalable, smaller file size
PDF: Print-ready, preserves quality
JPEG: Smaller size, no transparency, lossy compression

Use

scripts/convert.sh

for flexible format selection.

虽然本工具专注于PNG导出，但draw.io还支持以下格式：

SVG: 矢量格式，可缩放，文件体积更小
PDF: 印刷就绪，保留质量
JPEG: 体积更小，无透明通道，有损压缩

使用

scripts/convert.sh

可灵活选择输出格式。

References

参考资料

See

references/

directory for:

cli-reference.md: Complete draw.io CLI documentation
quality-guide.md: Detailed quality and DPI guidelines
automation-examples.md: Scripts for CI/CD integration

详见

references/

cli-reference.md: 完整的draw.io CLI文档
quality-guide.md: 详细的质量与DPI指南
automation-examples.md: CI/CD集成脚本示例

Examples

示例

See

examples/

directory for:

single-file.sh: Single file conversion example
batch-convert.sh: Batch conversion script
watch-and-convert.sh: File watcher for auto-conversion

详见

examples/

single-file.sh: 单个文件转换示例
batch-convert.sh: 批量转换脚本
watch-and-convert.sh: 文件监听自动转换脚本