开发者参考

该用哪一个？

所有方式都在你自己的机器、你自己的进程中运行。Node.js 包在后台线程中转换，事件循环不会被阻塞；Python 包在转换期间会释放 GIL。不需要服务器、账号或网络访问。

命令行：docsvg

格式根据文件扩展名决定；没有扩展名或扩展名很通用时，还会查看文件开头的内容。成功时退出码为 0；失败时退出码为 1，并在标准错误中输出原因。

docsvg <INPUT> --output <FOLDER> [options]
docsvg reverse <SVG or FOLDER> --output <FILE>
docsvg transform <SVG or -> --output <SVG or -> [options]

转换：docsvg <INPUT> --output <FOLDER>

写回：docsvg reverse

整理：docsvg transform

所有输入和输出格式 →

转换会写出什么

输出文件夹必须是新的或空的，已有文件绝不会被覆盖。conversion.json 是整个任务的报告，convert() 和 preview() 的返回值中也有相同的字段（Node.js 中为驼峰命名）。

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

Node.js

出错时 Promise 会以 Error 拒绝，消息以问题类型开头："invalid input"、"unsupported input"、"safety limit exceeded" 或 "I/O error"。

const { convert, preview, reverse, transform } = require('document-svg')

async function main() {
  const result = await preview('slides.pptx', { maxPages: 50 })
  console.log(result.pageCount, result.needsReview)
  const firstPageSvg = result.pages[0].svg

  const report = await convert('slides.pptx', 'out/slides', { jobs: 2 })
  await reverse('out/slides', 'slides-copy.pptx')
  const small = transform(firstPageSvg, { minify: true })
}

main().catch(console.error)

preview() 和 convert() 的选项

transform() 的选项

document-svg/preview-ui（在浏览器中运行，不含原生代码）

预览分步指南 →npm 软件包页面 →

Python

安装名为 document-svg，导入名为 document_svg。返回值是普通字典，字段与 conversion.json 相同。

from document_svg import convert, preview, reverse, transform

result = preview("report.docx", max_pages=50)
print(result["page_count"], result["needs_review"])
first_page_svg = result["pages"][0]["svg"]

report = convert("report.docx", "out/report", jobs=2)
reverse("out/report", "report-copy.docx")
small = transform(first_page_svg, minify=True)

preview() 和 convert() 的选项（仅限关键字参数）

异常

PyPI 软件包页面 →

Rust

公开 API 只有 crate 根下的内容（上述函数及其选项、报告类型和 Error）以及 ir、svg 模块；内部读取模块在不同版本之间可能变化。

use document_svg::{convert_path, ConvertOptions};

fn main() -> Result<(), document_svg::Error> {
    let options = ConvertOptions { jobs: 2, ..ConvertOptions::default() };
    let report = convert_path("report.pdf", "out/report", &options)?;
    println!("{} pages, {} warnings", report.page_count, report.warnings.len());
    Ok(())
}

ConvertOptions 字段

Error 变体

docs.rs 上的完整 API 文档 →crates.io 页面 →

在网页中显示页面

可以。页面是普通的 SVG 图片，任何浏览器都能显示。把它们显示到界面上有两种方式。

1. 在服务器或 Electron 主进程中用 Node.js 转换，把 SVG 发送到页面，再用 preview-ui 显示（见 Node.js 一节和预览指南）。适用于所有支持的格式。

2. 用 WebAssembly 版在浏览器中转换，并用现成的 <docsvg-viewer> 元素显示。不上传，也不需要服务器。支持 PDF、Word、Excel 和 PowerPoint，提供缩略图、缩放、适应宽度或页面、旋转、全屏、文字搜索以及下载当前页面。

<script type="module" src="/bindings/wasm/web/docsvg-viewer.js"></script>
<docsvg-viewer thumbnails></docsvg-viewer>

<script type="module">
  const viewer = document.querySelector('docsvg-viewer')
  viewer.options = { maxPages: 200 }          // optional limits
  fileInput.addEventListener('change', () => viewer.openFile(fileInput.files[0]))
</script>

<docsvg-viewer> 速查

• WebAssembly 版没有作为软件包发布。请从 bindings/wasm 构建（需要 Rust 和 wasm-bindgen），再从你的网站提供 bindings/wasm/web。
• 请通过 HTTP 提供；用 file:// 打开无法运行。使用 Content-Security-Policy 时，script 需要 'wasm-unsafe-eval'，worker 需要 'self'。
• 页面通过 <img> 中的 Blob URL 显示，查看器不会把文档 SVG 插入你的页面。

在浏览器中试用查看器 →如何构建和部署查看器 →

上限一览

所有上限都是为了保护机器免受超大或损坏文件的影响。可以按用途调低；不要只是为了让难处理的文件通过而调高。

安全与局限 →