快速开始

1. 选择使用方式

不需要全部安装。按你想从哪里调用，选一种即可。

npm 会安装到项目的 node_modules，pip 会安装到当前环境的 site-packages，cargo install 会把 docsvg 放到 ~/.cargo/bin。

cargo install document-svg --locked

npm install document-svg

python -m pip install document-svg

cargo add document-svg

npm 软件包页面 →PyPI 软件包页面 →crates.io 页面 →Rust API 参考（docs.rs） →下载预编译的命令行工具（发布页面） →

2. 转换第一个文件

同样的转换，从哪里调用都一样。每个示例都能照原样运行。

docsvg report.pdf --output output/report
docsvg slides.pptx --output output/slides
docsvg architecture.drawio --output output/diagram --stencils path/to/stencils.xml

docsvg report.pdf --output output/report --jobs 4 --max-pages 100

docsvg reverse output/slides --output slides.pptx
docsvg reverse output/diagram --output diagram.drawio
docsvg reverse output/drawing --output drawing.dxf

docsvg transform diagram.svg --output diagram.min.svg \
  --minify --monochrome "#1e293b" --responsive --precision 1

const { convert } = require('document-svg')

const report = await convert('report.docx', 'output/report', { maxPages: 100 })
const needsReview = report.warnings.length > 0 ||
  report.pages.some((page) => page.warnings.length > 0)

console.log(report.pageCount, needsReview)

import { preview } from 'document-svg'

const report = await preview('slides.pptx', { maxPages: 100 })
for (const page of report.pages) {
  console.log(page.number, page.widthPoints, page.heightPoints)
  // page.svg is the complete SVG XML string
}
console.log('review required:', report.needsReview)

import { createSvgPreviewUrl, revokeSvgPreviewUrl } from 'document-svg/preview-ui'

const url = createSvgPreviewUrl(svgMarkup)
// <img src={url} alt="Office document preview" />

// when replacing the image or disposing of the view:
revokeSvgPreviewUrl(url)

const { reverse } = require('document-svg')

const report = await reverse('output/diagram', 'diagram.drawio')
console.log(report.pageCount, report.warnings)

from document_svg import convert

report = convert("input.pptx", "output/pptx", jobs=1, max_pages=500)
needs_review = bool(report["warnings"]) or any(
    page["warnings"] for page in report["pages"]
)
print(report["page_count"], needs_review)

from document_svg import reverse

report = reverse("output/slides", "slides.pptx")
print(report["page_count"], report["warnings"])

use document_svg::{convert_path, ConvertOptions};

let options = ConvertOptions { jobs: 4, max_pages: 500, ..ConvertOptions::default() };
let report = convert_path("input.pdf", "output/pdf", &options)?;
println!("{} pages", report.page_count);

use document_svg::ir::{IDENTITY, Node, Page, Paint, Stroke};
use document_svg::svg::write_page;

let mut page = Page::new(1, 320.0, 180.0, "custom");
page.nodes.push(Node::Path {
    id: "card".into(),
    d: "M 20 20 H 300 V 160 H 20 Z".into(),
    fill_rule: "nonzero".into(),
    fill: Paint::solid("#E8F1FF"),
    stroke: Stroke { paint: Paint::solid("#246BCE"), width: 2.0, ..Stroke::default() },
    transform: IDENTITY,
    clip_id: None,
    meta: Default::default(),
});
write_page(&mut std::fs::File::create("out.svg")?, &page)?;

use document_svg::{svg_to_document, ReverseOptions};

let report = svg_to_document("output/slides", "slides.pptx", &ReverseOptions::default())?;
println!("{} pages", report.page_count);

3. 检查结果

输出位置请指定一个新的或空的文件夹。里面会生成每页一个 SVG，以及一份转换记录（conversion.json）。

output/slides/
├── page-0001.svg
├── page-0002.svg
└── conversion.json

• 没能原样还原的地方，会以“警告”的形式写进记录。
• 没有报错不代表完美。有警告时，请由人来检查页面。
• 即使没有警告，也不保证和用 Office 打开时逐像素一致。比如文字会使用显示 SVG 的环境中已有的字体。

4. 在应用中显示

请把 SVG 当作图片显示（例如用 img 元素）。不要把 SVG 的内容直接贴进页面的 HTML 里。

附带的显示辅助工具会做一些基本检查，但它并不能让任意 SVG 都变得无害。

5. 从常用工具里使用

GitHub 与 AI 工具的配置步骤 →

6. 遇到问题时

• 我们为 Windows、macOS、Linux 的 x64 和 ARM64 提供了预编译的软件包。
• Alpine Linux 上的 Python 没有预编译的软件包，需要 Rust 和构建工具。
• 用 npm 安装后无法加载时，请确认可选依赖已经安装，并且 Node.js 与机器的 CPU 类型一致。把 node_modules 复制到别的系统上是不能用的。
• 转换得到的 SVG 可以在较新的浏览器、resvg、librsvg 2.46 及以上版本中显示。

平台支持与故障排查 →