@printstack/print-studio 0.1.1 → 0.1.3

package/README.md

@@ -1,243 +1,210 @@
-# @printstack/print-studio
+### **Print Studio** —— Web 打印，从此简单。
 
-浏览器端打印模板设计器与输出运行时。可视化设计打印模板，注入业务数据后进行预览与打印，或导出 HTML / PDF。适用于在 ERP、CMS、OA 等第三方业务系统中嵌入打印能力。
+---
+
+轻量级 Web 打印解决方案：可视化设计模板、绑定业务数据，即可预览、打印并导出 HTML / PDF。支持独立使用或嵌入业务系统，无需额外部署服务端。适用于在 ERP、CMS、OA 等第三方业务系统中嵌入打印能力。
 
 - **可视化设计器**：多页管理、页面模板与文本、表格、条码、二维码、图片等常用打印元素；界面运行于库自管的隔离 iframe，宿主零样式接入。
 - **数据绑定**：字符串属性 `{{ 路径 | 格式化器 }}` 注入业务数据，表格跨页续排、循环区块展开明细。
 - **输出**：浏览器预览与打印、独立 HTML、PDF Blob。全部在浏览器内完成，无服务端依赖，打印数据由调用方传入。
 
-## 安装
+> **完整文档（API 参考、教程、示例、演练场）请访问 [https://print-studio-docs.github.io](https://print-studio-docs.github.io)**。
 
-预览、打印和 PDF 导出依赖浏览器 DOM / Canvas，不支持 Node.js / SSR。发布包为纯 ESM，Vue、Pinia 等运行时依赖随包自动安装，非 Vue 项目无需编写 Vue 组件；样式已随隔离 iframe 内联加载，无需手动导入。
+---
+
+## 安装
 
 ```bash
 npm install @printstack/print-studio
+```
 
-# 或
+```bash
 pnpm add @printstack/print-studio
+```
+
+```bash
 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()` 等） |
+- **浏览器**：Chrome / Edge / Firefox / Safari 现代版本；系统打印行为由浏览器决定，建议按目标浏览器实际验收。
+- **模块格式**：纯 ESM 包，不提供 CommonJS 接入。Vue、Pinia 等运行时依赖随包自动安装，非 Vue 项目无需编写 Vue 组件；样式已随隔离 iframe 内联加载，无需手动导入。
+- **Node.js / SSR**：模板渲染依赖浏览器 DOM / Canvas，不在服务端直接运行；服务端输出需以无头浏览器等宿主承载。
+- **PDF / 图片 / 字体**：浏览器资源加载与跨域策略参与输出结果，需用实际资源验证。
+- **移动端**：可打开文档；设计器需要足够的容器宽高。
 
-## 基础使用
+## 选择接入方式
 
-### 引入与初始化
+按业务场景二选一，两种方式可同时使用：
 
-`createPrintStudio()` 创建工作区实例，`mount()` 把可视化设计器挂载到业务页面的容器。适用于任意前端框架：
+| 接入方式 | 适用场景 | 需要的能力 |
+| --- | --- | --- |
+| **嵌入设计器** | 让用户在系统内可视化设计、维护模板 | `PrintDesigner` 组件（Vue）或 `studio.mount()`（任意技术栈） |
+| **仅输出，不嵌设计器** | 只在业务页面用已有模板渲染数据、预览打印 | 仅 `createPrintStudio()`，不调用 `mount()`；或更轻量的 `createPrintRenderer()` |
 
-```ts
-import { createPrintStudio } from '@printstack/print-studio'
+不嵌入设计器时，设计器视图与相关插件代码不会加载（视图运行时按需加载）。
+
+### 方式一：嵌入设计器（Vue 应用）
+
+```vue
+<script setup lang="ts">
+import { PrintDesigner, usePrintStudio } from '@printstack/print-studio/vue'
 
-// 1. 创建工作区
-const studio = createPrintStudio({
-  storage: false, // 关闭自动草稿，由 onSave 决定保存时机
-  async onSave(document) {
-    // 收到文档对象（非 JSON 字符串）；等待持久化完成后再 resolve，失败抛错
+const studio = usePrintStudio({
+  storage: false, // 关闭自动草稿，见下文「配置偏好与草稿」
+  onSave: async (document) => {
     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">
+  <!-- 容器需要有明确高度 -->
+  <div style="height: 80vh">
     <PrintDesigner :studio="studio" />
   </div>
 </template>
 ```
 
-### 预览
+要点：
 
-`studio.preview(input)` 注入本次业务数据并打开打印预览。默认以全屏预览层展示；`input` 是普通对象，属性路径与模板中 `{{ }}` 绑定对应：
+- `usePrintStudio()` 在 setup 作用域中创建实例，页面卸载时自动 `dispose()`；组件与界面操作同一份文档。
+- 通过 `studio.mount()` 也可把设计器挂载到任意容器（支持元素或 CSS 选择器），一个工作区同时只挂载一个设计器，可用 `unmount()` 移除后重新挂载。非 Vue 技术栈用这种方式。
+
+### 方式二：不嵌设计器，只做输出
 
 ```ts
-const input = { order: { number: 'SO-20261114-001', customer: '张女士' } }
+import { createPrintStudio } from '@printstack/print-studio'
 
-// 全屏预览层展示，用户自行关闭
-await studio.preview(input)
+const studio = createPrintStudio()
 
-// 需要编程控制时使用返回的句柄
-const handle = await studio.preview(input)
-handle.close()
+// 加载系统已有模板数据（不挂载设计器）
+studio.document.loadJson(templateJson)
 
-// 或嵌入页面指定容器（容器需要有明确高度）
-await studio.preview(input, {
-  container: document.querySelector('#preview-box')!,
-})
-
-// 独立挂载完整打印预览，无需挂载设计器；支持 container，缺省挂到 body
-const designerPreview = await studio.preview(input, { mode: 'designer' })
-// 关闭时释放预览界面与渲染会话；也可在指定 container 中展示
-designerPreview.close()
+// 业务数据渲染 + 输出
+await studio.print({ orderNo: 'A001' })
+const { blob } = await studio.toPDF({ orderNo: 'A001' })
 ```
 
-`mode: 'designer'` 使用调用时的文档与数据快照，独立显示带分页导航、缩放、数据编辑和打印操作的完整打印预览；不要求先调用 `studio.mount()`。预览窗口关闭后再调用 `studio.dispose()` 释放工作区。
+不需要界面时直接用 `createPrintStudio()`，即可完成加载模板、注入数据、预览、打印、导出。不需要任何编辑 UI 时，可用更轻量的纯输出运行时 `createPrintRenderer()`，详见 [createPrintRenderer() 参考](https://print-studio-docs.github.io/reference/renderer)。
 
-### 打印
+## 模板保存到自己的系统
 
-`studio.print(input)` 注入数据后调用浏览器打印，在浏览器打印对话框中由用户确认：
+模板在设计器中就是一份 JSON 文档（`PrintDocument`），接入点是 `onSave` 回调：
 
 ```ts
-const { warnings } = await studio.print(input)
+const studio = usePrintStudio({
+  onSave: async (document) => {
+    // document 为完整模板 JSON，存到你的数据库 / 接口
+    await saveToMySystem(templateId, JSON.stringify(document))
+  },
+})
 ```
 
-注意事项：
+- 触发途径：界面「保存」按钮、文件菜单的保存命令，或代码调用 `studio.document.save()`。`save()` 返回只表示回调执行完成。
+- 若未提供 `onSave`，界面保存能力不可用（`studio.document.dirty` 仍正常）。
+- 程序化获取当前文档：`studio.document.data`；导出 JSON 字符串：`studio.export.json()`。
+- 文档有未保存修改时 `studio.document.dirty` 为 `true`，可用于自己的保存提示；挂载方式可另传 `onDirtyChange` 监听脏状态。
 
-- `print()` 返回仅表示打印任务已提交，不代表用户确认或设备出纸成功。
-- 输出界面渲染在隐藏 iframe 中完成；需要时可通过 `signal` 与 `timeoutMs` 控制取消与超时：
+## 加载系统已有模板
+
+两种途径：
+
+**代码加载**（嵌入与非嵌入方式都适用）：
 
 ```ts
-const controller = new AbortController()
-await studio.print(input, { signal: controller.signal, timeoutMs: 15_000 })
+// 字符串 JSON
+studio.document.loadJson(json)
+// 对象
+studio.document.load(document)
 ```
 
-### 导出
-
-`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)
+const studio = usePrintStudio({ initialDocument: myTemplate })
 ```
 
-## 第三方系统集成示例
-
-以 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
-}
+import { definePlugin } from '@printstack/print-studio'
+import { createRemoteTemplateProvider } from '@printstack/print-studio/designer'
+
+const myTemplateLibrary = definePlugin({
+  manifest: {
+    apiVersion: '1.0',
+    id: 'my-company:templates',
+    version: '1.0.0',
+    permissions: ['templates'],
+  },
+  setup(ctx) {
+    return ctx.templateLibrary.register(
+      createRemoteTemplateProvider({
+        id: 'my-company:remote',
+        manifestUrl: '/api/templates/manifest',
+        title: () => '系统模板',
+        headers: { Authorization: `Bearer ${token}` },
+      }),
+    )
+  },
+})
+
+const studio = usePrintStudio()
+studio.use(myTemplateLibrary)
 ```
 
-业务页面只需调用这些函数：
+- Provider 支持 `create` / `update` / `remove` 时，用户可在模板库中把当前文档存入你的系统、更新或删除已有模板。
+- 不需要模板库时也可用 `studio.template.import()` 程序化导入模板对象。
+
+## 配置偏好与草稿
+
+两类自动持久化默认都写入 `localStorage`，均有开关和自定义存储接口：
+
+| 配置项 | 默认行为 | 关闭 | 自定义存储 |
+| --- | --- | --- | --- |
+| **草稿（未保存的模板数据）** | 修改自动写入 `localStorage`（键 `print-studio:document`），下次打开自动恢复 | `storage: false` | `storage: { get(): string \| null, set(json) }`，实现 `DocumentStorage` 接口 |
+| **偏好设置（主题等界面偏好）** | 变更时写入 `localStorage` | `persistPreferences: false` | `preferenceStorage: { get(key), set(key, value) }`，实现 `PreferenceStorage` 接口 |
+
+典型配置：宿主系统统一管理模板，关闭本地草稿，只信任 `onSave`：
 
 ```ts
-printButton.addEventListener('click', () => printOrder(currentOrder))
+usePrintStudio({ storage: false, onSave })
 ```
 
-模板已定稿、不再需要设计器界面时，改用纯输出运行时 `createPrintRenderer()`，不加载任何编辑 UI。注意参数顺序为模板在前、数据在后：
+需要把草稿/偏好存到服务端或 IndexedDB 时，实现对应接口传入即可。
 
-```ts
-import { createPrintRenderer } from '@printstack/print-studio/runtime'
-import { deserializeDocument } from '@printstack/print-studio/core'
+## 在业务场景中预览与打印
 
-const renderer = createPrintRenderer()
+拿到模板和业务数据后，输出入口都接受 `input`（数据源值，键需与模板中的数据绑定一致）：
 
-// 业务保存的模板 JSON：解析后可先经 deserializeDocument 校验补全
-const { document: template } = deserializeDocument(
-  JSON.parse(savedTemplateJson),
-)
+```ts
+// 预览：打开成品视图，返回句柄，用完 dispose()
+const handle = await studio.preview({ orderNo: 'A001' })
+handle.dispose()
 
-const input = { order: { number: 'SO-20261114-001' } }
-const { blob } = await renderer.toPDF(template, input)
-await renderer.print(template, input)
+// 打印：提交浏览器打印任务；resolve 表示任务已提交，不代表用户确认或设备出纸
+await studio.print({ orderNo: 'A001' })
 
-renderer.dispose()
+// 导出
+const { blob } = await studio.toPDF({ orderNo: 'A001' })
+const { html } = await studio.toHTML({ orderNo: 'A001' })
 ```
 
+批量打印、PDF 批量导出等进阶输出见教程 [批量打印与批量导出](https://print-studio-docs.github.io/tutorial/batch)。
+
+---
+
 ## 更多功能与完整文档
 
 > 更多高级功能、详细配置说明及完整 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/)：模板设计、页面尺寸、元素绘制、数据绑定、保存加载、批量打印
+- [API 参考](https://print-studio-docs.github.io/reference/studio)：`createPrintStudio()` 与工作区 API
 - [数据绑定参考](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、事件与上下文