ppt-dsl-renderer

用同一套组件将 PPT DSL 渲染为 Vue 页面，或转为一页一个、可直接在浏览器打开的 HTML。独立 HTML 为 agent 提供稳定的页面节点和渲染完成状态，由 agent 自行截图、审查和修改 DSL。

提供浏览器侧标准可编辑 PPTX 生成方法，返回完整 ArrayBuffer，默认全部页，可指定页码，保留音视频并应用默认母版。后端通过统一 CLI 直接保存 PPTX。

运行要求：Node.js 18+；Vue 接入要求 Vue 3.4.21+（3.x）；浏览器需要支持现代 DOM、SVG、Canvas。

安装

发布后可安装：

yarn add ppt-dsl-renderer

Vue 渲染、Node HTML 生成和浏览器端 PPTX 导出只需安装主包。仅后端使用 export-pptx CLI 时，还需由调用方显式安装浏览器驱动：

yarn add ppt-dsl-renderer [email protected]

playwright-core 是可选 peer dependency，不会随主包自动安装，也不会下载浏览器。CLI 仍要求部署机器已有 Google Chrome/Chromium。

CLI 与 Agent 接入

ppt-dsl-renderer --help
ppt-dsl-renderer render ./deck.json --out-dir ./preview
ppt-dsl-renderer export-pptx ./deck.json --out ./result.pptx

仅在当前项目安装时，使用 ./node_modules/.bin/ppt-dsl-renderer。PPTX CLI 通过调用方显式安装的 [email protected] 启动已有 Chrome/Chromium，每次创建新实例，不复用后端正在运行的浏览器；不改变原导出算法。

Agent 先读 统一调用指南，其中集中说明运行前提、全部参数、JSON 返回值及失败处理。后端子进程调用、浏览器生命周期和修改范围见 PPTX 后端接入。两份文档随 npm 包发布。

Node API

import { renderToHtml, type PptDslDocument } from 'ppt-dsl-renderer'
import { writeFile } from 'node:fs/promises'

const document: PptDslDocument = {
  title: 'Hello DSL', width: 1000, height: 562.5,
  slides: [{
    id: 'cover',
    elements: [{
      id: 'title', type: 'text', left: 60, top: 70, width: 800, height: 100,
      content: '<p style="font-size: 48px">Hello DSL</p>',
    }],
  }],
}

const pages = await renderToHtml(document, { pages: [1] })
await writeFile('slide.html', pages[0].html)

返回 { pageNumber, slideId, width, height, html }[]。API 不写文件、不启动浏览器、不下载素材、不修改输入。Node 入口仅使用 Node 内置模块，Vue 等库已经打包进 HTML 的浏览器运行代码。

Vue 前端接入

发布包提供预编译的 ESM 组件；前端通过 /vue 入口导入，样式只需引入一次：

<script setup lang="ts">
import { SlideRenderer } from 'ppt-dsl-renderer/vue'
import type { PptDslSlide } from 'ppt-dsl-renderer'
import 'ppt-dsl-renderer/style.css'

defineProps<{ slide: PptDslSlide; width: number; height: number }>()
</script>

<template>
  <SlideRenderer :slide="slide" :width="width" :height="height" />
</template>

SlideRenderer 用于只读整页和缩略图，支持 scale。ElementRenderer 用于编辑画布，提供文字、形状文字和表格单元格插槽；展示结构与样式由包维护，编辑控件、交互和数据回写由前端维护。Vue 入口不会自动挂载页面或设置全局截图状态，CSS 不包含独立 HTML 的全局重置和光标隐藏规则。

Vue 从宿主项目复用；纯 Node 使用者无需安装 Vue。完整 API、插槽示例及现有渲染器的迁移步骤见 Vue 接入指南。

Agent 接入

1. 生成符合 DSL 文档 的 JSON。
2. 使用 CLI 或 API 生成 HTML，从本次结果清单取得文件路径。
3. 在浏览器打开文件，等待 window.__PPT_DSL_RENDER__.status 不再为 loading。
4. 状态为 error 时读取 errors；为 ready 时截图 #ppt-slide。
5. 根据截图修改 DSL，再生成需要重审的页。

完整调用流程见根目录 Agent 调用指南，页面状态协议见 Agent 渲染与截图协议。本包不包含截图工具、MCP 服务、视觉模型或自动布局评价。

HTML 内嵌 JS、CSS 和该页数据，打开后等比例适配窗口并居中，窗口较大时保持原尺寸。DSL 坐标和内部尺寸不变；需要原始分辨率截图时，将浏览器 viewport 设置为 DSL 的 width、height。图片、背景图和视频封面支持 HTTP(S) URL 或 data URL；使用远程素材时仍需网络。视频只显示封面，音频只显示静态控件，不加载音视频内容。字体来自浏览器环境；缺少字体可能产生替换和换行差异，ready 不代表视觉通过或字体与其他系统完全相同。

PPTX 导出

浏览器模块现已支持生成完整 PPTX ArrayBuffer，不自动下载：

import { exportToPptx } from 'ppt-dsl-renderer/pptx'

const binary = await exportToPptx(document)
// 指定页：await exportToPptx(document, { pages: [1, 3] })

后端通过统一 CLI 导出，调用示例及兼容边界见 PPTX 后端接入。

开发与验证

yarn test
yarn coverage

测试覆盖输入、分页、CLI 文件行为、JSON 嵌入、渲染状态、图片加载等待及 Vue 组件和样式语法；Vue 行为测试在内存中编译源码，验证缩放、插槽切换、多实例 SVG 引用和图表生命周期，并通过单个消费端夹具检查公开类型。图表测试使用 ECharts 交互替身，API 与安装目录模拟测试使用明确标识的测试运行资源，不代替生产构建或浏览器视觉验收；测试不会调用 build、vue-tsc 或启动本地服务。

发布前由维护者显式执行 yarn build，生成 dist/index.js、dist/cli.js、dist/browser、dist/vue 和 dist/pptx 中的运行产物，再使用 yarn pack 检查安装包。npm 包只发布 dist、TypeScript 声明、使用文档、示例和第三方许可，不发布实现用的 src/*.js、src/pptx 或 source map。prepack 会检查公开入口、构建资源和发布清单，但不会自动构建。真实包验收应在独立目录安装生成的 tgz，验证 Node 生成示例 HTML、CLI、Vue 组件及 CSS、PPTX 模块的导入，再在浏览器核对渲染、PPTX 二进制返回和媒体播放。PPTX 单元测试检查真实 ZIP/XML、媒体字节和返回的 ArrayBuffer；DOM/Canvas 适配不代替浏览器或 Office 验收。另确认 npm 包名和构建产物的开源授权后再发布。

许可证

本包采用 MIT 许可证。浏览器依赖的许可证及声明见 第三方声明。