@canvas-components/react-print-design

面向 React 的 Canvas 打印模板编辑器，包含工具栏、组件栏、图层和页面列表、属性面板、撤销重做以及 JSON、HTML、PNG、PDF 导出和打印。导出格式集中在 ReactDropdown 菜单中；点击格式后可在弹窗中修改文件名，支持拖出的格式使用当前文件名。编辑器的画布和文档操作由 @canvas-components/print-design 提供，表单和可调面板优先组合 @canvas-components/react-components。图片式 PDF 将页面作为图片嵌入；矢量 PDF 保留可由内置字体表示的文字和图形，遇到中文等不支持的字符或非标准字体时，仅将对应文字由浏览器 Canvas 绘成紧凑位图。含水印等标记为位图模式的页面在 jsPDF 导出时仍为整页位图；浏览器真实打印使用 SVG 水印文字。

编辑器下载、拖出和打印 HTML 时会等待组件的 prepareHtml 回调。拖出菜单会先准备文件，尚未完成时提示稍后重试；核心实例的同步 HTML API 遇到需要异步准备的组件会给出明确错误。单页 PNG 下载复用实例的异步 Blob 导出；批量 PNG 和 PDF 导出逐页等待组件的 prepareCanvas 回调。自定义字体加载失败时使用浏览器字体回退；其他资源准备失败时停止输出。直接调用核心同步 Canvas API 的宿主应先调用 preparePrintDesignCanvasPage。

安装

pnpm add @canvas-components/react-print-design react react-dom

基础用法

import { ReactPrintDesign } from "@canvas-components/react-print-design";
import type { PrintDesignDocument } from "@canvas-components/print-design";
import { useState } from "react";

export function TemplateEditor() {
  const [document, setDocument] = useState<PrintDesignDocument>();

  return (
    <div style={{ width: "100%", height: 720 }}>
      <ReactPrintDesign onChange={setDocument} />
    </div>
  );
}

传入 document 可加载外部模板并使用受控更新；data 提供 {{field.path}} 变量预览数据，onChange 返回文档副本。组件也接受 readonly、showGrid、zoom 和 editor={false} 等属性。默认编辑器会注入自身样式，容器需要有明确高度。

读取并校验模板

ReactPrintDesign 的 getTemplates 属性接收分页查询方法。查询参数为 { page, pageSize, query }，页码从 1 开始；返回 { data, page, pageSize, total }，其中 data 为完整模板包或裸文档数组。null 和 [] 表示空结果。设计器自动校验模板，并在左侧模板面板按需加载后续页面。网络请求与鉴权由业务代码负责。

import { ReactPrintDesign } from "@canvas-components/react-print-design";

<ReactPrintDesign
  getTemplates={async ({ page, pageSize, query }) => {
    const response = await fetch(
      `/api/business/templates?page=${page}&pageSize=${pageSize}&query=${encodeURIComponent(query)}`,
    );
    if (!response.ok) throw new Error(`模板请求失败：${response.status}`);
    return response.json();
  }}
/>;

设计器按当前 componentRegistry、tools 和 pluginCatalog 校验模板；缺失插件或外部资源仍需由宿主处理。导出的工具函数 getTemplates(loader, query, options?) 也可单独用于校验，不会修改设计器状态。

getPlugins 使用相同的 { page, pageSize, query } 查询参数和 { data, page, pageSize, total } 返回结构。data 中每项为现有 PrintDesignRemotePluginRecord。插件市场滚动加载，未提供方法或返回 null、[] 时显示空状态。下载、启停、删除由宿主回调执行；IndexedDB 保存下载清单及启停状态，刷新后根据清单与宿主安装结果恢复。设计器在安装前校验插件声明的 printDesign 与 reactPrintDesign 版本范围。

JSON 模板导入导出

工具栏使用“JSON 导出模板”和“JSON 导入模板”。JSON 只有一个导出项，导出的模板包包含文档内容与组件布局、页面辅助线、Mock 数据、工具配置、实际使用的组件和工具插件版本及兼容范围，并将组件声明的图片、字体等外部资源归档到同一文件。外部资源无法完整归档时会提示错误，不会下载不完整的文件。导入使用同一模板包格式并校验依赖；该格式可供后续模板和插件市场识别所需插件。

离线插件包接入

插件市场标题右侧显示导入入口，导出入口保留在可分发插件的详情弹窗。选择 ZIP 后弹窗展示归档清单、组件、工具、依赖和兼容范围，确认后才调用 onPluginPackageImport。回调获得经过结构检查的清单与原始 File；宿主负责完整的文件摘要、来源、协议版本、依赖和分发许可校验，并持久保存构建产物。导入成功后宿主更新注册表，设计器随属性更新重绘，无需刷新浏览器页面。当前模板有未保存改动时，设计器先保存模板；无法保存则停止导入。设计器不会执行归档内的脚本。未提供该回调时，导入按钮保持可见但不可用。提供 onPluginPackageExport 时，允许分发的插件详情显示导出按钮。

可分发的市场项声明 exportable: true 且宿主提供 onPluginPackageExport(packageId) 时，市场才显示导出按钮。回调返回宿主持有的 Blob 或 Uint8Array；市场核对归档结构、包 ID 和 redistributable 声明后下载 .zip 文件，不依赖浏览器的 Web Crypto。宿主在返回归档前负责完整的摘要校验；导入和安装仍逐文件校验摘要。仅有运行时注册表或模板 JSON 无法生成插件代码。

createPrintDesignPluginArchive 和 inspectPrintDesignPluginArchive 提供格式版本为 1 的 ZIP 归档构建与校验。归档必须含 manifest.json、原生/React 构建入口及清单列出的文件；清单记录包和注册项版本、兼容范围、依赖、所需权限、资源、许可、再分发状态及每个文件的大小和 SHA-256 摘要。组件和工具注册项可附加 name、description，供未启用时的市场列表展示。导入会拒绝路径穿越、重复路径、额外文件、摘要不一致和超限归档。

Node 宿主可从 @canvas-components/react-print-design/plugin-host 单独导入 PrintDesignPluginHost。宿主指定安装目录、可解析同版本依赖的 node_modules 目录、核心包版本和 authorize(manifest, sha256) 许可回调。install(bytes) 校验归档、兼容范围、依赖与注册冲突，经宿主许可后落盘并加载；load() 在重启后重新核对归档及已安装文件，返回同版本的原生与 React 注册声明，供宿主装配注册表。插件入口须分别导出 printDesignNativePlugin、printDesignReactPlugin。失败安装保留原版本，已发布的同版本内容不可改写。安装目录应由宿主管理，不能让不可信用户修改；插件代码在 Node 宿主进程中执行，authorize 必须核查来源及执行权限。多个实例或进程共用安装目录时，传入共用的 withExclusiveWrite(directory, work)，使安装、远程升级和移除的索引事务由宿主串行化；默认队列仅作用于同一个宿主实例。

插件间依赖按清单中的包 ID 和最低版本解析。宿主为每套已安装版本组合生成独立运行快照，并从快照加载入口；升级依赖后，依赖它的插件会从新快照重新加载，避免 Node 模块缓存继续指向旧版本。宿主会在执行插件代码前校验所有已安装归档、兼容范围和注册项冲突。历史快照与旧版安装目录可用于仍在运行的代码及回退，部署方应在进程退出后按自身保留策略清理。

独立打印服务可调用 loadNative()，只返回带原生入口的插件。它仍会核对完整归档和插件依赖，但不会执行 React 入口，也无需配置 reactPrintDesignVersion；安装和完整 load() 仍要求 React 兼容版本。打印服务将返回的 native.components[].renderer 注册到自己的 PrintDesignComponentRegistry，并使用该注册表输出 HTML 或执行分页。

独立打印服务可从 @canvas-components/react-print-design/template-runtime 导入模板包解析、资源检查与归档资源恢复方法；该入口不加载 React 运行时。图片和字体经归档后，打印端用原生组件注册表调用 materializePrintDesignTemplateResources，再交给核心包输出静态 HTML。导入时，已注册组件的资源清单必须与当前配置一致；未知插件的资源引用保持原样，供后续安装后校验。必需的内嵌资源若缺少组件注册项或与原文档配置不匹配，恢复阶段会报错；编辑后的文档若已替换原地址，则跳过旧资源。构建核心、组件插件和本包后运行 pnpm --filter @canvas-components/react-print-design verify:offline-template-print，会把模板 JSON 交给独立 Node 进程并在禁用外部请求的条件下验收图片和字体输出。

市场服务可调用 listInstalled() 读取当前包的清单与归档摘要，不会执行插件入口。exportArchive(packageId) 返回已安装当前版本的原始 .zip 字节；宿主会再次核对磁盘文件和摘要，仅在清单声明 redistributable: true 且可选的 authorizeExport 策略通过时返回。宿主可把该方法接到编辑器的 onPluginPackageExport 回调；需要由宿主自行提供文件传输和访问控制。

createPrintDesignInstalledCatalog(list) 可将安装清单中的每个组件和工具分别转成市场项，状态为“已安装”。宿主把已加载并启用的注册项另行传给 registerPrintDesignPluginPackages；市场区分已安装与已启用，并提供“已安装”筛选。市场优先使用归档中逐项声明的名称和用途，旧归档未提供时显示注册 ID 和通用说明。

Node 服务可从 @canvas-components/react-print-design/plugin-host-http 导入 createPrintDesignPluginHostHttpHandler({ host, authorizeRequest })，挂到自身的 HTTP 服务。处理器默认使用 /api/print-design/plugins，提供安装清单、离线归档安装与导出、移除、远程目录查询和指定版本安装；未命中的请求返回 false。authorizeRequest 必须由业务宿主针对各操作鉴权，安装器的 authorize 仍负责核对插件来源和可执行代码许可。浏览器使用 PrintDesignPluginHostClient 调用同一路径，安装或移除后重新读取安装清单并装配注册表；客户端不执行归档代码。

正式 Node 宿主可从 @canvas-components/react-print-design/plugin-server-http 导入 createPrintDesignPluginServerHttpHandler({ host, browserDirectory, sharedModules, authorizeRequest })，取得同一套安装管理与浏览器 ESM 模块路由的 handle 和 deployment。sharedModules 必须来自宿主实际部署的同源核心、React 和适配包 ESM；模块读取与安装清单使用同一逐请求鉴权回调，modules 动作同时保护目录与代码文件。已构建文件被清理时，模块服务会从仍已安装的归档重建一次；文件存在但摘要不符时继续拒绝提供。业务宿主仍负责身份认证、持久目录、静态文件服务和路由挂载。

宿主可从 @canvas-components/react-print-design/plugin-remote-http 导入 createPrintDesignHttpRemotePluginSource({ baseUrl, headers })，将结果传给 PrintDesignPluginHost({ remote })。适配器只向固定的 baseUrl 请求 GET /packages 和 GET /packages/:packageId/:version/archive；除本机回环地址外必须使用 HTTPS，并拒绝重定向和超限响应。远程目录返回完整归档清单、归档 SHA-256、大小和来源；宿主下载后再次校验摘要、完整清单、兼容性与依赖，全部候选包加载成功才切换安装索引。目录中的 URL 不作为下载地址。宿主仍须决定可信服务、凭据、authorize 许可和跨进程安装串行化。

插件共享库可从 @canvas-components/react-print-design/plugin-library 导入 PrintDesignPluginLibrary。宿主必须指定持久目录、authorizeUpload(actor, manifest, sha256) 发布权策略及 validateRelease(manifest, archive) 发布前检查。uploadDraft 仅暂存可再分发的 .zip，草稿不进入其他用户目录；publish 检查依赖可见性、注册项冲突并将当前包版本固定，withdraw 阻止撤下仍被其他已发布插件依赖的版本。listMine、listPublished、download 按作者及个人、团队、公开范围授权。sourceFor(actor) 可直接接入现有安装器；撤下不会修改其他宿主已安装的归档。宿主需在 validateRelease 中实施组件 Canvas/HTML/分页、工具 UI 和资源检查，库本身不会执行上传代码。

插件共享库和 @canvas-components/react-print-design/template-library 的 PrintDesignTemplateLibrary 均支持可选的 withExclusiveWrite(directory, work)。同一持久目录被多个宿主实例或进程使用时，宿主应传入共用的分布式锁或数据库事务实现，并在整个 work() 完成后释放目录锁；回调须原样返回结果或抛出错误。默认队列只串行化同一个库实例内的写入，不能代替跨进程协调。

@canvas-components/react-print-design/plugin-library-http 提供 createPrintDesignPluginLibraryHttpHandler({ library, authenticate })，由宿主将请求认证为用户和团队身份，并检查跨站请求与写入权限。默认路径 /api/print-design/shared-plugins 的 GET /packages 与 GET /packages/:packageId/:version/archive 可直接供远程 HTTP 来源适配器使用；POST /drafts、GET /mine、POST /packages/:packageId/:version/publish 和 /withdraw 管理作者版本。浏览器使用 PrintDesignPluginLibraryClient 提交草稿并读取状态，不加载归档中的脚本。库的文件目录与安装目录应仅由宿主进程修改；多进程写入、团队身份和下载凭据由部署方控制。

市场“我的插件”区域由宿主传入 sharedPlugins 和 onSharedPluginUpload、onSharedPluginPublish、onSharedPluginWithdraw 时显示。上传前先在浏览器校验 .zip 并预览包清单，再选择个人、指定团队或公开范围；上传只形成草稿，发布后才进入远程目录。操作成功后宿主重新读取 listMine() 和远程目录。未配置共享库回调时不显示上传、发布或撤下操作。

宿主把 load() 返回的数组传入 registerPrintDesignPluginPackages(base, loaded, options)，一次生成设计器和打印端共用的组件注册表、创建器、菜单、属性区、工具注册表及市场目录。base 可使用官方插件包提供的注册表集合；options.isEnabled(packageId) 控制当前包是否启用，停用时仍显示市场记录。生成的 componentRegistry 同时传给编辑器预览和独立打印调用，避免两端使用不同绘制版本。这个装配函数只接收已由宿主校验和加载的声明，不负责执行归档或选择可信来源。

构建脚本可从 @canvas-components/react-print-design/plugin-archive 单独导入归档工具，避免加载编辑器入口。

大数据量可在设计阶段只传入第一页样本，并提供 loadPreviewData(document, { signal, onProgress })，在点击预览或打印、导出时异步返回完整的 { document, data }。预览会分批生成页面并显示进度，退出预览时通过 signal 取消任务；加载函数应响应取消信号，并避免同步遍历全部数据。ReactListTable 的打印设计已采用此方式，首次打开只读取第一页，预览分页保留当前模板的编辑结果。

组件栏提供文本、形状、分割线、图片、条形码、二维码和图表。选中分割线后，可在属性面板设置方向、线型、颜色和线宽；尺寸、位置及旋转也可在通用属性中调整。

组件栏也提供连接线。选中连接线后可拖动两端吸附到其他组件的边中点、四角以及多边形的边中点或顶点；属性面板可指定起止组件及连接点、直线/曲线/折线、颜色、线宽、箭头大小与显隐、线上文本。拖动线上文本可沿路径调整位置。 选中折线后，每段中点会显示方形控制柄；沿线段的垂直方向拖动控制柄即可调整折角，起止连接点保持固定。控制柄接近其他折点或端点的水平、垂直坐标时会吸附对齐，多余折角会自动合并；按住 Alt 可暂时关闭吸附。调整后的折点保存在模板中。 选中单个组件后，四边会显示加号按钮。拖动加号可从该边的连接点画出折线；拖到另一个组件内部或边缘控制点时，线端自动绑定到最近的连接点，组件移动后连接线随之更新。

左侧“曲线组件”提供二次曲线、三次曲线和多段曲线。选中后可在画布拖动锚点和控制点，也可在右侧调整曲率、线条样式、曲线文本的上中下轨迹和位置；多段曲线支持增减段数。曲线文字在画布预览与实际打印中沿曲线路径排布。

左侧“基础元素”提供流程组件，可拖入画布。右侧“数据”属性支持静态节点新增、删除和排序，以及动态节点数组路径与字段映射；切换模式会保留静态节点。还可设置左右交替、倒序、节点样式及字号。

开发排查时可设置 debug 开启 Canvas 调试覆盖层。它会显示元素边界、当前选区和指针命中的元素；也可通过对象配置单独控制各层：

<ReactPrintDesign debug={{ showHitTarget: true, showElementBounds: true }} />

编辑器默认显示毫米刻度尺和辅助线，可用 showRulers、showGuides、showMarginGuides 控制初始状态。辅助线会在刻度尺上显示位置标记和毫米值，可拖放到纸张外的画布区域。拖动上方或左侧刻度尺可创建辅助线，拖动辅助线可调整位置，拖回对应刻度尺或选中后按 Delete/Backspace 可移除。工具栏“打印边距”开关显示页面四边的打印边距线，边距值可在页面属性中配置。

画布辅助配置

左侧“配置”面板（React 编辑器）可控制刻度尺、辅助线、打印边距和最近组件间距的显示，还能设置左右面板的最小、最大及当前宽度。拖动面板分隔条会更新当前宽度。配置面板还可调整以下原生选项：

“缓存配置到本地”位于配置页顶部。开启后，主题、显示单位、字体和颜色、面板宽度、画布辅助设置、缩放比例与调试显示状态会保存到浏览器本地，并在下次打开时恢复；关闭或点击“重置配置”会清除缓存。传入的 zoom、debug 和 displayUnit 属性优先于对应的本地缓存值。

• snapToGuides：默认开启。组件边缘和中心吸附到辅助线；辅助线吸附到纸张边缘、中心、打印边距和组件位置。按住 Alt 临时关闭。
• snapTolerance：默认 6 CSS 像素，不随缩放改变屏幕吸附距离。
• dragThreshold：默认 4 CSS 像素。选中后超过此距离才开始移动、缩放、旋转、辅助线拖拽或画布平移。
• showMeasurements：默认开启，标注选中组件与上下左右投影相交的最近可见组件间距，单位毫米；旋转组件使用外接矩形测量。
• zoomDuration：默认 180 毫秒，设为 0 关闭缩放过渡。

在画布上使用滚轮可纵向平移，按住 Shift 滚轮可横向平移，Ctrl/⌘ 加滚轮可缩放。也可按住空格拖拽或拖拽纸张空白/外部区域平移查看；平移和缩放不会修改打印文档或导出内容。 鼠标滚轮的大步进采用平滑过渡，触控板的小幅连续滚动直接跟随输入。 滚轮和拖拽平移最多偏离画布可见区域宽高的 200%。

刻度与辅助线外观

左侧“配置”面板支持调整刻度尺字号/背景和辅助线数值字号/背景，原生实例可通过以下选项或 updateOptions() 实时设置：

标签随字号自动调整尺寸，保持与纸张 8px 间距。

辅助线颜色可通过配置面板或原生选项设置：guideColor 控制普通辅助线（默认青色），marginGuideColor 控制打印边距辅助线（默认紫色）。纸张内线条与纸张外延长线同步更新，选中标记保留高亮。

表格组件

左侧“表格”可点击添加或拖入画布。右侧提供静态数据 JSON、数组路径绑定、表头显隐、行高、字号及列配置；列可添加、删除、隐藏，配置 ListTable 的单元格类型、宽度、对齐与汇总。高级“列配置 JSON”支持嵌套表头和 moneyFormat、cellStyle、dataFormat 等声明式配置。JSON 草稿校验通过后才写入文档，可使用设计器撤销/重做。预览与 HTML/PDF 导出按页面高度拆分表格记录。

静态数据支持按行展开、直接编辑字段和增删数据行，保留数值、布尔值及嵌套字段类型，复杂对象可用 JSON 编辑。动态绑定使用设计器 data 中的数组路径，显示有效记录数和前 5 行预览；切换模式保留静态记录。示例页提供 order.items 数据源。表头、表格体、汇总行各自支持背景色和文字色，默认背景透明，可通过“背景透明”开关切换。

“单元格边框”可选择显示、隐藏或动态数据控制；动态边框字段使用级联选择器从当前 mock/data 或记录字段中选择。“单元格”面板按行列设置合并行列数、对角线文字、背景、文字及边框颜色，单元格边框字段也使用级联选择器。画布中先点击表头或表体单元格，再按 Shift 点击同一区域的另一单元格可选择矩形范围；右侧面板与右键菜单均可执行“合并选中单元格”。右键菜单也支持与右侧或下方单元格合并及取消合并。拖动表格上下句柄会调整行高，表格随数据行数变化而扩高，打印分页时后续组件紧跟实际表格末尾。

“数据自动合并”面板可输入逗号分隔的字段名：连续行分组字段用于判定相邻记录是否属于同一组，执行行合并的列用于指定需要显示为合并单元格的列（留空时使用分组字段），同行相邻列合并字段用于合并值相同的相邻列。字段设置失焦后应用，动态绑定数据变化时重新计算，手动合并配置优先。

选中表格后，顶部字母选择器可选整列，左侧行号选择器可选表头或数据整行，左上角可全选。右键数据行号可在上方或下方新增静态数据行；右键列字母可在左侧或右侧新增列。左上角全选选择器的右键菜单可在末尾新增行或列。动态绑定表格的新增数据行操作禁用；所有插入操作支持撤销重做。

列类型支持文本、金额、图片、二维码、条码、颜色、进度、勾选、评分、标签、按钮、图表等常见 ListTable 单元格内容；数据值也可使用带 type 的对象覆盖列类型。图表对象需提供 chartType 和 option，时间线对象需提供 items。

画布与左侧元素图层共用右键菜单：剪切、复制、粘贴、生成副本、组合/取消组合、锁定/解锁、显示/隐藏、删除，以及全选和撤销重做。层级和对齐操作在对应面板中使用。空白画布提供全部解锁、显示全部图层与适合页面。右键已选元素保留多选；复制粘贴使用当前设计器实例内剪贴板，粘贴偏移 5mm 并重建组合 ID。菜单支持方向键、Home/End 和 Esc。

左侧点击组合的子图层只选中该子图层，点击组合标题选中其成员；画布点击组合成员时选中整个组合，拖动时整体移动。元素超过 80 个时，左侧自动启用虚拟列表，只挂载可视区域与预加载行，支持展开分组、滚动和拖拽排序。

右侧“图层对齐”对所有元素类型及组合提供水平/垂直位置操作。单个图层或完整组合相对纸张对齐，多选相对选区对齐；完整组合保持内部布局，独立选中的子图层只移动自身。两端对齐按等间距排列，分散对齐按等中心距排列，至少需要三个独立图层或组合，首尾位置不变。锁定图层禁用操作，支持撤销/重做；文本内容对齐仍单独位于“文本样式”。

所有组件右侧统一提供“数据”面板，支持“静态数据”和“动态绑定”切换，保留两种模式下的配置。基础组件可编辑内容、图片地址、颜色和线宽对应的字段，绑定模式显示路径及解析预览；字段路径支持数组索引，也可输入 {{字段}} 模板。图表保留分类、数值系列及数组绑定，表格保留静态行编辑、列配置及数组绑定。原文本、编码内容、图片地址和形状/分割线颜色线宽入口统一移入数据面板。

数据方式使用按钮切换。动态绑定时可直接编辑“默认内容”，缺失、空值或无效字段会回退，0 和 false 保持有效；图表和表格提供显式的缺失数据源回退开关，有效空数组不回退。画布悬停动态图层时在右上角展示“动态绑定”，提示包含绑定路径；标记不会打印或导出。

字段路径复用 ReactCascader，从当前传入的 mock/data 解析对象、数组和字段类型，支持搜索、清空及数组索引。图表/表格数组数据源选择器只展示数组路径，分类、系列、表格列字段从当前记录样本合并解析。数据更新后选项同步更新，缺失的已选路径保持回显。为避免大数据阻塞，字段解析最多展开 16 层、3000 个节点，并采样前 100 条记录、每层前 200 个字段。

表格/图表使用专用数据源适配：表格可选择记录数组或 { dataSource, columns }，通过“使用数据源列配置”导入 ListTable 的声明式列属性（回调不写入 JSON 模板）；图表可选择记录数组、ListTable 记录集，或直接选择 ListTableChartData 的 { labels, keys?, series: [{ name, data }] }。直接图表数据不显示分类/数值字段映射，并保留稳定类别 keys。适配逻辑位于原生 print-design/model，React 面板只负责配置，避免后续 ReactListTable 集成产生反向依赖。

单组件、组合与多选边框均提供八个控制句柄：左右调整宽度，上下调整高度，四角同时调整宽高，以对边或对角为锚点；组合同步缩放成员位置和尺寸。操作保留拖拽阈值、最小尺寸及撤销/重做；只读或包含锁定成员时不提供控制柄。