OpenPencil CLI 导出实战：一条命令把设计文件渲染成 PNG、JPG、SVG、PDF 与 HTML

前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载本篇指南围绕 OpenPencil CLI 的export子命令展开讲解如何在不打开编辑器的情况下从.fig、.pen等设计文件生成位图、矢量图、PDF、可编辑 PPTX、.fig子集、JSX 代码与 HTML 交付物。读完本文你将掌握export的完整参数体系、页面/节点选择方式、字体替换策略与 Live App 模式并能直接照抄命令投入实际产出。export 命令一览无需打开编辑器即可渲染export是 OpenPencil CLI主命令openpencil定义见 packages/cli/src/index.ts中负责渲染与导出的子命令。它读取一个受支持的设计文件对指定页面或对象执行渲染并把结果写入磁盘。最基本的用法bun open-pencil export design.fig -o preview.png在安装为全局命令的环境中同样可以写作openpencil export design.fig -o preview.png上面这条命令把design.fig的第一页渲染为 PNG 并保存为preview.png。如果不带-o文件会以源文件名加格式扩展名命名详见下文输出路径与默认命名一节。从源码看命令本身支持的全部导出格式来自 packages/core/src/io/formats.ts 中的内置 IO 注册表fig、pen、png、jpg、webp、svg、pdf、pptx、jsx、tailwind-jsx、html。运行bun open-pencil export --help可以随时查看当前安装版本支持的具体格式与选项列表。选择导出内容页面、节点还是整个文档export通过三个维度决定渲染范围对应源码 packages/cli/src/commands/export.ts 中的目标解析逻辑默认导出第一页未指定任何选择参数时导出文档的第一个页面--page 名称按页面名称精确查找并导出该页例如--page Page 1--node 节点ID按节点 ID 导出单个节点例如--node 1:23ID 可用openpencil tree、openpencil find等命令查得。两点需要注意的限制源码中有显式校验--page与--node不能同时使用二者互斥同时传入会直接报错退出export.ts导出fig与pptx格式时如果既未指定--page也未指定--node默认导出整个文档而不是仅第一页见 prepareGraphForExport。如果--page指定的名称不存在CLI 不会静默产出空结果而是打印错误并列出文档中所有可用页面名称后以非零状态退出openpencil export design.fig -f png --page NotThere # Page NotThere not found. Available pages: Page 1, Page 2.在文件模式下导出目标确定后CLI 会通过 packages/cli/src/headless.ts 中的populateDocumentPage/populateWholeDocument对 .fig 中的惰性导入子树按需填充并重新计算布局保证导出的画面与编辑器内一致。缩放与尺寸用 -s 控制输出分辨率渲染分辨率由导出缩放比例scale控制通过-s或--scale指定默认值为1即设计稿原始尺寸openpencil export design.fig -f jpg -s 2 -q 90 # JPG2 倍分辨率质量 90 openpencil export design.fig -f webp -s 3 # WEBP3 倍分辨率 openpencil export design.fig -f png -s 2 # PNG 2x关于缩放有两点实现细节值得注意默认文件名自动携带倍率标记当指定了非默认缩放时默认输出文件名会带上Nx后缀例如design2x.png见 exportFileName质量参数仅对 JPG 与 WEBP 生效-q/--quality取值范围 0–100默认 90。对于 PNG、SVG、PDF 等无损或矢量格式该参数会被忽略源码仅在格式支持缩放时才构造 scale/quality 选项见 exportOptions。CLI 还提供了--width与--height参数默认 1920×1080用于缩略图导出的尺寸设定。需要如实说明的是当前共享文件导出路径尚未支持缩略图导出传入--thumbnail会在文件模式下直接报错退出export.ts因此目前控制分辨率的可靠手段是-s。按格式导出详解位图格式PNG、JPG、WEBPPNG 是默认格式适合需要透明背景与无损质量的场景JPG 适合照片类内容配合-q控制压缩质量WEBP 在体积与质量之间更平衡。三者都支持-s缩放openpencil export design.fig # PNG默认格式 openpencil export design.fig -f jpg -s 2 -q 90 # JPG 2x质量 90 openpencil export design.fig -f webp -s 3 # WEBP 3xSVG保留矢量几何-f svg输出 SVG 矢量文件几何信息路径、节点结构、描边与填充被原样保留适合图标、设计评审以及后续在矢量工具中继续编辑的场景openpencil export design.fig -f svgPDF-f pdf生成 PDF 文档。在文件模式下PDF 与位图格式一样参与字体替换策略检查详见下文openpencil export design.fig -f pdfPPTX可编辑的 PowerPoint-f pptx把设计稿导出为可编辑的 PowerPoint 文件适合需要把设计转交到办公场景继续加工的场景。默认导出整个文档openpencil export design.fig -f pptxFIG导出.fig子集-f fig可以把单页或单节点导出为.fig文件适合从大文档中切出局部继续编辑openpencil export design.fig -f fig --page Page 1 # 导出单页为 .fig openpencil export design.fig -f fig --node 1:23 # 导出单个节点为 .fig从源码看FIG 导出选项固定开启renderThumbnail: trueexportOptions导出时走io.writeDocument路径executeFileExport。JSX导出为带 Tailwind 工具类的代码-f jsx把设计稿转译为 JSX 代码。默认使用 OpenPencil 原生 JSX 格式--style openpencil对应 JSX 渲染器文档加上--style tailwind则输出带 Tailwind 工具类的 JSXopenpencil export design.fig -f tailwind-jsx # 等价于 -f jsx --style tailwind典型输出形如div classNameflex flex-col gap-4 p-6 bg-white rounded-xl p classNametext-2xl font-bold text-[#1D1B20]Card Title/p p classNametext-sm text-[#49454F]Description text/p /div实现上--style tailwind会把格式映射为注册表中的独立格式tailwind-jsx见 export.ts 与 formats.ts。HTML交付、检查与后续处理-f html默认生成带内联样式的 HTML 片段fragment适合嵌入既有页面或供程序化消费。也可以切换为 Tailwind 工具类风格openpencil export design.fig -f html openpencil export design.fig -f html --css tailwind需要一份能直接在浏览器打开的交付物时使用--html standalone会生成带重置样式与页面包裹层的独立 HTML 文档。文档官方明确说明standalone HTML 定位是有用的视觉/代码交接物不是 CanvasKit 渲染的像素级替代品openpencil export design.fig -f html --html standalone --css inline openpencil export design.fig -f html --html standalone --css tailwind openpencil export design.fig -f html --html standalone --css tailwind --assets externalstandalone 模式还有两个重要选项--assets external把 CSS 与提取出的图片资源写到 HTML 文件旁边的目录--fonts assets配合外部资源使用通过 OpenPencil 配置的 Web 字体提供方解析场景图中检测到的字体并生成本地font-face文件。此外standalone 的 Tailwind 输出在导出时即已编译完成不依赖 Tailwind 的浏览器运行时。HTML 导出仅在文件模式下可用见 exportViaApp 中对 JSX/HTML/FIG/PPTX 的限制报错。字体替换策略warn、strict 与 allow对于文件模式下的 PNG、JPG、WEBP 与 PDF 导出可以选择如何处理缺失或被替换的字体openpencil export design.fig -f pdf --font-policy strict openpencil export design.fig -f png --font-policy warn openpencil export design.fig -f webp --font-policy allow三种策略源码定义见 packages/cli/src/export-font-policy.tswarn默认报告字体替换情况并继续导出strict如果字体准备无法忠实解析请求的字型则打印错误并以非零退出码终止allow跳过额外的字体保真度检查直接导出。从实现看该策略只对PNG、JPG、WEBP、PDF四种格式生效SVG、PPTX、JSX、HTML 与.fig输出不受影响export-font-policy.ts。其检查的是字体解析的忠实度而非与 Figma 的完整视觉等价性。建议在导出前先用openpencil fonts检查受影响字型font-diagnostics一节。另外注意导出准备过程可能使用配置的字体提供方因此其结果可能与离线文件诊断存在差异运行中的应用内导出也不应用此策略。输出路径与默认命名-o或--output指定输出文件路径。CLI 的错误处理非常严格——遇到无效格式、缺失对象或无效路径时会明确报错而不是静默产出部分结果无效格式命令启动时即校验打印可用格式列表后退出export.ts页面缺失报错并列出可用页面见上文无效组合如--page与--node同时使用、非法的--style/--html/--css/--assets/--fonts/--font-policy取值均在执行前拦截并退出export.ts目标为空app 模式下 SVG/PDF 导出无内容时报Nothing to export.export.ts。未指定-o时的默认命名规则exportFileName默认源文件名.扩展名如design.png指定了缩放源文件名Nx.扩展名如design2x.png。导出完成后CLI 会打印输出路径、文件大小与导出目标Target: first page/page Page 1/node 1:23/whole document见 export.ts。HTML 外部资源模式下关联文件会与主输出一并写入并统计资产数量。Live App 模式导出正在运行的应用文档export的file参数是可选的——省略文件参数时命令会连接正在运行的 OpenPencil 应用导出当前文档isAppModeopenpencil export -f png # 从当前文档导出 PNG该模式通过 MCP discovery 文件定位本地运行的应用进程经由 RPC 调用应用的导出能力packages/cli/src/app-client.ts并支持--document-id与--page-id指定目标文档/页面见 packages/cli/src/app-target.ts。其限制如下支持格式PNG、JPG、WEBP、SVG、PDF不支持PPTX、JSX、HTML 与.fig——传入这些格式会报错并提示仅在文件模式下可用export.ts文件模式的缩略图导出同样不受支持。SVG 与 PDF 在 app 模式中分别走export_svg、export_pdf工具 RPC其余位图格式走通用exportRPCexport.ts。export 参数速查表参数别名说明默认值file—文档文件路径省略则连接运行中的应用必填文件模式-f--format格式png、jpg、webp、svg、pdf、pptx、jsx、html、figpng-s--scale导出缩放比例1-q--quality质量 0–100仅 JPG/WEBP90-o--output输出文件路径名.格式带缩放时名Nx.格式--page—按名称导出指定页面与--node互斥第一页--node—按 ID 导出指定节点—--style—JSX 风格openpencil或tailwindopenpencil--html—HTML 模式fragment或standalonefragment--css—HTML 样式inline或tailwindinline--assets—HTML 资源inline或externalinline--fonts—HTML 字体assets或nonenone--font-policy—位图/PDF 字体策略warn、strict、allowwarn--thumbnail—导出页面缩略图文件模式暂不支持关--width/--height—缩略图宽高1920×1080--document-id/--page-id—app 模式下指定文档/页面当前深入export 命令的源码执行流程把以上内容串起来一次文件模式导出的完整调用链大致是run入口先对格式、JSX 风格、HTML 各选项与字体策略做白名单校验任一非法取值立即报错退出export.ts判断是 app 模式还是文件模式isAppMode并分流执行文件模式调用 loadDocument 读取文件、构建 SceneGraph 并计算全部布局解析页面/节点目标必要时填充惰性 .fig 导入子树对位图/PDF 格式执行字体策略检查applyExportFontPolicy构造各格式专属导出选项renderThumbnail、HTML 组合、scale/quality 等交给IORegistry中注册的格式适配器完成渲染最终写入文件并打印统计信息。值得留意的是export使用的格式能力完全来自open-pencil/core/io的内置注册表formats.ts这也是openpencil export --help与 formats 命令 所报告格式清单的一致来源。理解这条调用链有助于在接入自定义 IO 格式或排查导出异常时快速定位问题环节。延伸阅读CLI 概览与脚本化 | 文档检查与字体诊断 | JSX 渲染器 | CLI 参考赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐OpenPencil CLI 导出指南从设计文件生成 PNG、SVG、PDF、HTML 与 JSXOpenPencil CLI 导出指南从设计文件生成 PNG、SVG、PDF、HTML 与 JSX OpenPencil 的 export 命令可以在不打开编前端桌面应用AI 应用MCP 服务OpenPencil CLI 导出实战指南从终端生成 PNG、SVG、PDF、PPTX、HTML 与 JSXOpenPencil CLI 导出实战指南从终端生成 PNG、SVG、PDF、PPTX、HTML 与 JSX 本篇指南系统讲解 OpenPencil 命令行工前端桌面应用AI 应用MCP 服务OpenPencil CLI 导出实战从 PNG 到 HTML/JSX 的一站式设计交付OpenPencil CLI 导出实战从 PNG 到 HTML/JSX 的一站式设计交付 本文基于 packages/docs/de/programmable前端桌面应用AI 应用MCP 服务上一篇novel-downloader构建个人数字图书馆的智能化解决方案下一篇GeoIP快速获取IP地理位置信息的Ruby利器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考