# @canvas-components/react-print-design 中文文档

规范地址：https://npmcn.com/package/%40canvas-components/react-print-design/

版本：0\.1\.20
npm 元数据更新时间：2026-11-06T09:19:37.722Z
中文译文更新时间：2026-11-09T09:28:35.687Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canvas-components/react-print-design
原文对照：https://npmcn.com/package/%40canvas-components/react-print-design/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，65 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.12\.0
- 运行依赖：6 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2026-10-20T07:00:15.510Z
- 最新版本发布：2026-11-06T09:19:37.490Z
- 近 30 天下载量：3094（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

Canvas打印设计引擎的反应编辑器.

## 安装

```sh
npm install @canvas-components/react-print-design
```

也可以使用：`pnpm add @canvas-components/react-print-design`、`yarn add @canvas-components/react-print-design`、`bun add @canvas-components/react-print-design`

## README

# @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`。

## 安装

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

## 基础用法

```tsx
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` 和 `[]` 表示空结果。设计器自动校验模板，并在左侧模板面板按需加载后续页面。网络请求与鉴权由业务代码负责。

```tsx
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 调试覆盖层。它会显示元素边界、当前选区和指针命中的元素；也可通过对象配置单独控制各层：

```tsx
<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()` 实时设置：

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `rulerFontSize` | 9 | 刻度尺字号，8–16 CSS px |
| `rulerBackground` | `#f8fafc` | 刻度尺背景色 |
| `guideFontSize` | 9 | 辅助线数值字号，8–24 CSS px |
| `guideBackground` | `#cffafe` | 辅助线圆角标签背景色 |
| `guideSelectedBackground` | `#ffedd5` | 选中辅助线的标签背景色 |

标签随字号自动调整尺寸，保持与纸张 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 集成产生反向依赖。

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

## 常见问题

### @canvas-components/react-print-design 是什么？

Canvas打印设计引擎的反应编辑器\.

### 如何安装 @canvas-components/react-print-design？

在项目目录运行 npm install @canvas-components/react-print-design，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @canvas-components/react-print-design 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @canvas-components/react-print-design 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @canvas-components/react-print-design 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @canvas-components/react-print-design 可以商用吗？

@canvas-components/react-print-design 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @canvas-components/react-print-design 的下载量有多少？

根据 npm 官方下载统计，@canvas-components/react-print-design 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,094 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canvas-components/react-print-design 还在维护吗？

最新版本 0\.1\.20 发布于 2026/11/06（3 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。