DocuCanvas

English README

DocuCanvas 是一个面向前端应用的 Office 文档导出 SDK，用于把浏览器侧的场景、报表、仪表盘、低代码设计器、物流图、Canvas 编辑器内容导出为 Microsoft Office 级别的文档。

社区版覆盖常见 Excel 导出需求，用于免费使用和产品采用。授权的 Pro/Core 版本解锁高价值能力，包括可编辑 DrawingML 图形、Canvas 场景导出、Office 目标格式契约、图层、分组、WASM 加速和企业离线部署。

当前状态

• Community .xlsx 导出已实现：单元格、样式、图片、合并单元格、行高、列宽。
• Pro Excel DrawingML 场景渲染已实现：形状、文本、图片、路径、原生分组、z-index 图层顺序、圆角矩形、虚线、斜体文本、工作表锚点和场景分析指标。
• 已实现并测试签名 license claims。
• 已定义 Excel、Word、PowerPoint 目标格式契约；Word .docx 和 PowerPoint .pptx 已有基础 DrawingML 包生成器。
• 已实现 WASM facade、功能 gate、最小可构建 docucanvas_core.wasm、企业离线激活基础流程和性能 benchmark；高级商业几何/布局 WASM 引擎不会随公开仓库直接发布。

版本能力

| 能力 | Community | Pro/Core | | --- | --- | --- | | 普通 Excel workbook 导出 | 是 | 是 | | 单元格样式 | 是 | 是 | | 图片 | 是 | 是 | | 合并单元格 | 是 | 是 | | 行高 | 是 | 是 | | 列宽 | 是 | 是 | | 形状导出 | 否 | 是 | | Canvas 场景导出 | 否 | 是 | | DrawingML | 否 | 是 | | SmartArt 路线图 | 否 | 是 | | 图层 | 否 | 是 | | 分组节点 | 否 | 是 | | Word/PPT DrawingML 包生成器 | 否 | 是 | | 高性能导出 | 否 | 是 | | WASM core | 否 | 是 |

包结构

• packages/community - MIT 社区版 API，用于普通 Excel 导出。
• packages/pro - 授权版 DrawingML、场景分析、场景导出和 Office target API。
• packages/core-wasm - 商业核心 WASM loader 和 facade。
• packages/benchmark - 确定性 benchmark 场景生成和 Office 导出指标。
• packages/license - license 注册、签名 claims 和能力检查。
• packages/excel - 共享 workbook 模型和 OpenXML helper。
• packages/plugin-vue - Vue 集成入口。
• packages/plugin-react - React 集成入口。

Community 示例

import {
  addImage,
  addWorksheet,
  createWorkbook,
  exportWorkbook,
  mergeCells,
  setCell,
  setColumnWidth,
  setRowHeight
} from '@docucanvas/community'

const workbook = createWorkbook()
const sheet = addWorksheet(workbook, 'Report')

setCell(sheet, 'A1', 'DocuCanvas', { fontWeight: 'bold', align: 'center' })
mergeCells(sheet, 'A1:C1')
setRowHeight(sheet, 1, 28)
setColumnWidth(sheet, 1, 32)
addImage(sheet, {
  id: 'logo',
  cell: 'A2',
  data: 'aGVsbG8=',
  mimeType: 'image/png'
})

const xlsx = exportWorkbook(workbook)

商业模型

Community 用户可以免费使用 MIT 包完成普通 Excel 导出。商业客户在使用 Pro/Core 能力前需要注册 license key：

import { configureLicenseEngine, registerSignedLicense } from '@docucanvas/license'
import { configureProEngine, createProExporter } from '@docucanvas/pro'
import { createDocuCanvasLicenseEngine } from '@docucanvas/core-wasm'

configureLicenseEngine(createDocuCanvasLicenseEngine())
await registerSignedLicense('dc_sig_xxx', { projectName: 'your-package-name' })

configureProEngine(commercialWasmProEngine)
const exporter = createProExporter()
const analysis = exporter.analyzeScene(scene)
const drawing = exporter.renderDrawingML(scene, { anchor })
const docx = exporter.exportSceneToWordPackage(scene)
const pptx = exporter.exportSceneToPowerPointPackage(scene)

设计上，license 边界位于 API 和二进制加载阶段。Community 代码可以独立使用。公开的 @docucanvas/pro 和 @docucanvas/license 是壳包：它们提供 API、类型、license 状态和 engine 注册入口，但商业执行委托给配置后的 WASM engine。@docucanvas/core-wasm 提供受控 license engine 和 WASM 计算边界。公开 GitHub release 不应包含 Pro/Core 源码、WASM 源码、license 签发脚本、私钥或生产客户 license 文件。

价格和付款

Community 对普通 Excel 导出免费。Pro/Core 针对可编辑 DrawingML、Word/PPT 包生成器、场景导出、WASM 加速和企业离线激活收取 license 费用。

| 方案 | 期限 | 价格 | 推荐用途 | | --- | ---: | ---: | --- | | Community | 不限期 | 免费 | 普通 .xlsx 导出：单元格、样式、图片、合并、行高、列宽 | | Pro Trial | 7 天 | CNY 29 | 集成 Pro API 前快速验证 | | Pro Monthly | 30 天 | CNY 99 | 推荐首次真实项目测试 | | Pro Quarterly | 90 天 | CNY 249 | 短期生产上线或团队评估 | | Pro Annual | 365 天 | CNY 799 | 月度或季度验证通过后的长期使用 | | Enterprise | 定制 | 联系 | 离线部署、机器绑定、SLA、私有交付和兼容性工作 |

付款流程：

1. 扫描 docs/assets/alipay-qr-placeholder.svg 中的支付宝二维码。公开销售前请替换为真实收款码。
2. 按所选期限付款。
3. 将付款截图发送到 [email protected]。
4. 邮件中注明方案、付款人、license 邮箱、产品域名或 bundle id；如需离线激活，还需提供机器 id。
5. license 签发方通过邮件回复签名 license key 或 license 文件。

推荐购买路径：先购买 Pro Monthly 或 Pro Quarterly，确认 SDK 符合真实导出工作流后，再升级到 Pro Annual 或 Enterprise。

质量门禁

npm test

该命令会运行 typecheck、build 和全部自动化场景测试。

npm run build:wasm

该命令会写入当前 WASM artifact：packages/core-wasm/dist/docucanvas_core.wasm。 该 artifact 由 packages/core-wasm/assembly/index.ts 通过 AssemblyScript 编译生成，并导出 license gate、scene analysis、geometry、worksheet marker、color 和 DrawingML XML 原语，包括 shape、text、picture、path geometry、group、two-cell anchor 和 worksheet drawing root writer。 私有 Pro DrawingML renderer 现在会通过 embedded WASM facade 生成这些低层 DrawingML 原语；JS 层保留场景遍历、媒体关系和 Office 包装配。

npm run build:release

该命令生成公开发布包到 release/packages/*：Community、共享 Excel helper、框架插件，以及 Pro/License 壳包。Pro/Core 实现通过配置后的 WASM engine 单独交付。发布前建议检查 tarball 内容：

npm pack ./release/packages/community --dry-run
npm pack ./release/packages/license --dry-run
npm pack ./release/packages/pro --dry-run
npm pack ./release/packages/plugin-react --dry-run
npm pack ./release/packages/plugin-vue --dry-run

Demo、trial、evaluation license 应绑定域名或 bundle id，并设置过期时间；它们不是生产 license，不得用于商业服务、再分发、转授权、衍生产品，或嵌入到其他产品和服务中。

设计

完整架构、license 模型、扩展路线图和商业 SDK 定位见 DESIGN.zh-CN.md。