@printstack/print-studio 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,247 @@
-# Temporary Holding Version
+# @printstack/print-studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+浏览器端打印模板设计器与输出运行时。可视化设计打印模板，注入业务数据后进行预览与打印，或导出 HTML / PDF。适用于在 ERP、CMS、OA 等第三方业务系统中嵌入打印能力。
+
+- **可视化设计器**：多页管理、页面模板与文本、表格、条码、二维码、图片等常用打印元素；界面运行于库自管的隔离 iframe，宿主零样式接入。
+- **数据绑定**：字符串属性 `{{ 路径 | 格式化器 }}` 注入业务数据，表格跨页续排、循环区块展开明细。
+- **输出**：浏览器预览与打印、独立 HTML、PDF Blob。全部在浏览器内完成，无服务端依赖，打印数据由调用方传入。
+
+## 安装
+
+预览、打印和 PDF 导出依赖浏览器 DOM / Canvas，不支持 Node.js / SSR。发布包为纯 ESM，Vue、Pinia 等运行时依赖随包自动安装，非 Vue 项目无需编写 Vue 组件；样式已随隔离 iframe 内联加载，无需手动导入。
+
+```bash
+npm install @printstack/print-studio
+
+# 或
+pnpm add @printstack/print-studio
+yarn add @printstack/print-studio
+```
+
+### 包导出入口
+
+| 导入路径 | 内容 |
+| --- | --- |
+| `@printstack/print-studio` | `createPrintStudio()` 工作区工厂与公共类型 |
+| `@printstack/print-studio/vue` | `PrintDesigner` 组件、`usePrintStudio()` |
+| `@printstack/print-studio/designer` | `mountPrintDesigner()` 命令式挂载 |
+| `@printstack/print-studio/runtime` | `createPrintRenderer()` 纯输出运行时 |
+| `@printstack/print-studio/core` | 文档模型与工具（`deserializeDocument()` 等） |
+
+## 基础使用
+
+### 引入与初始化
+
+`createPrintStudio()` 创建工作区实例，`mount()` 把可视化设计器挂载到业务页面的容器。适用于任意前端框架：
+
+```ts
+import { createPrintStudio } from '@printstack/print-studio'
+
+// 1. 创建工作区
+const studio = createPrintStudio({
+  storage: false, // 关闭自动草稿，由 onSave 决定保存时机
+  async onSave(document) {
+    // 收到文档对象（非 JSON 字符串）；等待持久化完成后再 resolve，失败抛错
+    await fetch('/api/templates', {
+      method: 'POST',
+      body: JSON.stringify(document),
+    })
+  },
+})
+
+// 2. 挂载设计器界面；resolve 即界面就绪
+await studio.mount({ el: '#designer' })
+
+// 3. 编辑模板：代码与设计器界面操作同一份文档
+const page = studio.page.active
+const cell = page.elements.add({
+  type: 'text',
+  x: 20,
+  y: 30,
+  width: 100,
+  height: 12,
+})
+page.elements.updateProps(cell, { text: '订单号：{{ order.number }}' })
+
+// 4. 页面退出时释放工作区
+// studio.unmount()  // 仅卸载界面，文档保留，可再次 mount
+// studio.dispose()  // 彻底释放
+```
+
+要点：
+
+- `el` 接受元素或 CSS 选择器，**容器需要有明确高度**，设计器界面填满其容器。
+- 界面配置（`ui` / `settings` / `plugins` / `zIndex`）与回调（`onDirtyChange` / `onError`）作为 `mount()` 选项传入，工作区创建选项仍在 `createPrintStudio()` 中配置。
+- 不传 `initialDocument` 时默认打开内置欢迎模板，可直接试用；业务模板通过 `initialDocument` 或 `studio.document.loadJson(json)` 加载。
+- 一个工作区同时只挂载一个设计器；`mount()` 失败或就绪前卸载会 reject，调用方应捕获并 `dispose()` 工作区。
+
+Vue 项目也可以使用组件方式。`usePrintStudio()` 在 setup 中创建同一工作区，页面卸载时自动清理：
+
+```vue
+<script setup lang="ts">
+import { PrintDesigner, usePrintStudio } from '@printstack/print-studio/vue'
+
+const studio = usePrintStudio({ storage: false })
+</script>
+
+<template>
+  <div style="height: 100vh">
+    <PrintDesigner :studio="studio" />
+  </div>
+</template>
+```
+
+### 预览
+
+`studio.preview(input)` 注入本次业务数据并打开打印预览。默认以全屏预览层展示；`input` 是普通对象，属性路径与模板中 `{{ }}` 绑定对应：
+
+```ts
+const input = { order: { number: 'SO-20261114-001', customer: '张女士' } }
+
+// 全屏预览层展示，用户自行关闭
+await studio.preview(input)
+
+// 需要编程控制时使用返回的句柄
+const handle = await studio.preview(input)
+handle.close()
+
+// 或嵌入页面指定容器（容器需要有明确高度）
+await studio.preview(input, {
+  container: document.querySelector('#preview-box')!,
+})
+
+// 独立挂载完整打印预览，无需挂载设计器；支持 container，缺省挂到 body
+const designerPreview = await studio.preview(input, { mode: 'designer' })
+// 关闭时释放预览界面与渲染会话；也可在指定 container 中展示
+designerPreview.close()
+```
+
+`mode: 'designer'` 使用调用时的文档与数据快照，独立显示带分页导航、缩放、数据编辑和打印操作的完整打印预览；不要求先调用 `studio.mount()`。预览窗口关闭后再调用 `studio.dispose()` 释放工作区。
+
+### 打印
+
+`studio.print(input)` 注入数据后调用浏览器打印，在浏览器打印对话框中由用户确认：
+
+```ts
+const { warnings } = await studio.print(input)
+```
+
+注意事项：
+
+- `print()` 返回仅表示打印任务已提交，不代表用户确认或设备出纸成功。
+- 输出界面渲染在隐藏 iframe 中完成；需要时可通过 `signal` 与 `timeoutMs` 控制取消与超时：
+
+```ts
+const controller = new AbortController()
+await studio.print(input, { signal: controller.signal, timeoutMs: 15_000 })
+```
+
+### 导出
+
+`studio.toHTML(input)` 生成独立 HTML 字符串，`studio.toPDF(input)` 生成 PDF Blob，交给宿主下载或上传：
+
+```ts
+// HTML：返回 { html, warnings }
+const { html } = await studio.toHTML(input)
+
+// PDF：返回 { blob, warnings }；以下载为例
+const { blob } = await studio.toPDF(input)
+const url = URL.createObjectURL(blob)
+const link = document.createElement('a')
+link.href = url
+link.download = 'order.pdf'
+link.click()
+URL.revokeObjectURL(url)
+```
+
+## 第三方系统集成示例
+
+以 ERP 订单打印为例。典型接入方式：模板在设计器中定稿后以 JSON 保存到业务系统；业务页面调用打印服务，加载模板、注入订单数据，提供预览与打印：
+
+```ts
+// print-service.ts —— ERP 订单打印服务
+import { createPrintStudio, type DesignStudio } from '@printstack/print-studio'
+
+interface Order {
+  number: string
+  customer: string
+}
+
+let studio: DesignStudio | undefined
+
+function getStudio(): DesignStudio {
+  studio ??= createPrintStudio({ storage: false })
+  return studio
+}
+
+/** 加载业务系统保存的订单模板 JSON；模板更新频率低时可缓存加载结果 */
+async function loadOrderTemplate(): Promise<void> {
+  const response = await fetch('/api/templates/order')
+  getStudio().document.loadJson(await response.text())
+}
+
+/** 点击「打印预览」：打开预览层，用户核对后关闭 */
+export async function previewOrder(order: Order): Promise<void> {
+  await loadOrderTemplate()
+  await getStudio().preview({ order })
+}
+
+/** 点击「打印」：浏览器打印对话框中确认 */
+export async function printOrder(order: Order): Promise<void> {
+  await loadOrderTemplate()
+  await getStudio().print({ order })
+}
+
+/** 点击「导出 PDF」：拿到 Blob 后下载或上传 */
+export async function exportOrderPdf(order: Order): Promise<Blob> {
+  await loadOrderTemplate()
+  const { blob } = await getStudio().toPDF({ order })
+  return blob
+}
+
+/** 应用退出时释放 */
+export function destroyPrintService(): void {
+  studio?.dispose()
+  studio = undefined
+}
+```
+
+业务页面只需调用这些函数：
+
+```ts
+printButton.addEventListener('click', () => printOrder(currentOrder))
+```
+
+模板已定稿、不再需要设计器界面时，改用纯输出运行时 `createPrintRenderer()`，不加载任何编辑 UI。注意参数顺序为模板在前、数据在后：
+
+```ts
+import { createPrintRenderer } from '@printstack/print-studio/runtime'
+import { deserializeDocument } from '@printstack/print-studio/core'
+
+const renderer = createPrintRenderer()
+
+// 业务保存的模板 JSON：解析后可先经 deserializeDocument 校验补全
+const { document: template } = deserializeDocument(
+  JSON.parse(savedTemplateJson),
+)
+
+const input = { order: { number: 'SO-20261114-001' } }
+const { blob } = await renderer.toPDF(template, input)
+await renderer.print(template, input)
+
+renderer.dispose()
+```
+
+## 更多功能与完整文档
+
+> 更多高级功能、详细配置说明及完整 API 文档，请访问 [Print Studio 官方文档](https://print-studio-docs.github.io)。
+
+- [快速开始](https://print-studio-docs.github.io/guide/getting-started)：从创建项目到预览、打印的完整流程
+- [循序渐进教程](https://print-studio-docs.github.io/tutorial/)：模板设计、页面尺寸、元素绘制、数据绑定、保存加载、批量打印
+- [数据绑定参考](https://print-studio-docs.github.io/reference/data-binding)：数据源声明、表达式与格式化器
+- [预览 / 打印 / 导出 API](https://print-studio-docs.github.io/reference/output)：输出选项、取消与超时、批量输出
+- [Vue 集成](https://print-studio-docs.github.io/reference/vue-designer)：组件 props、事件与上下文
+- [插件与扩展](https://print-studio-docs.github.io/reference/plugins)：自定义元素、解析器、命令、面板
+- [业务案例](https://print-studio-docs.github.io/examples/product-label)：商品标签、快递面单、出入库单、批量导出等完整示例
+- [常见问题](https://print-studio-docs.github.io/guide/troubleshooting)：安装、渲染与打印排查
+- [在线演练场](https://print-studio-docs.github.io/playground/index.html)：浏览器内直接运行全部示例