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

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

版本：0\.1\.22
npm 元数据更新时间：2026-11-09T07:59:56.638Z
中文译文更新时间：2026-11-09T08:03:24.233Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：6.3 MB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.12\.0
- 运行依赖：8 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0，@canvas-components/list-table \>=0\.3\.58，@canvas-components/react-components \>=0\.3\.31，@canvas-components/react-print-design \>=0\.1\.21
- 首次发布：2026-10-25T12:45:56.128Z
- 最新版本发布：2026-11-09T07:59:56.461Z
- 近 30 天下载量：3704（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

用于打印设计的原生和反应插件包.

## 安装

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

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

## README

# 打印设计插件包

同一个包提供两个代码入口和一个样式入口：

-   `@canvas-components/print-design-plugin/native`：原生组件注册表，供 Canvas/HTML 打印端使用，不加载 React。
-   `@canvas-components/print-design-plugin/react`：左侧菜单、元素创建、右侧属性与数据编辑配置；同时包含原生注册表，供 React 设计器使用。
-   `@canvas-components/print-design-plugin/style.css`：React 插件的专用界面样式，使用设计器时由宿主显式导入。

## 在 React 设计器中使用

从包根导入样式；只导入 `/react` 不会自动加载插件面板样式。一个应用入口导入一次即可，独立打印服务只使用 `/native`，不需要 CSS。

```tsx
import "@canvas-components/print-design-plugin/style.css";
import { ReactPrintDesign } from "@canvas-components/react-print-design";
import { builtinPrintDesignPlugins } from "@canvas-components/print-design-plugin/react";

export function PrintEditor() {
  return (
    <div style={{ height: 720 }}>
      <ReactPrintDesign
        componentRegistry={builtinPrintDesignPlugins.componentRegistry}
        componentFactories={builtinPrintDesignPlugins.componentFactories}
        componentMenu={builtinPrintDesignPlugins.componentMenu}
        propertySections={builtinPrintDesignPlugins.propertySections}
        contextMenus={builtinPrintDesignPlugins.contextMenus}
        tools={builtinPrintDesignPlugins.tools}
        pluginCatalog={builtinPrintDesignPlugins.pluginCatalog}
      />
    </div>
  );
}
```

第三方组件通过 `registerPrintDesignPluginPackages` 与内置注册表合并，再将返回的同名字段传给设计器；独立打印端使用同版本的 `componentRegistry`。完整接入示例见[当前版本示例](https://npmcn.com/package/%40canvas-components/print-design/docs/plugins/v0.1.10/example.tsx)。

## AI 对话插件

AI 对话位于本包的 `src/ai-chat/`，由宿主按需装配；未装配时设计器不显示 AI 按钮。按钮位于全屏按钮旁，右侧对话面板默认收起。输入框按 Enter 发送，Shift+Enter 换行；下方的更多按钮旁可切换当前模型和思考程度，未获取模型列表时模型选择器显示空列表。底部输入框的“更多 AI 设置”打开固定高度的配置对话框：左侧选择“基础配置”“外观配置”或“历史对话”，右侧显示内容。“基础配置”可维护多个连接，每个连接独立保存 Base URL、API Key、当前模型、思考程度和获取到的模型列表；修改 URL 或密钥后需重新获取列表。思考程度提供默认、低、中、高选项；默认时不向模型服务发送 `reasoning_effort`。“历史对话”可选择已有会话，删除时需要再次确认。旧版单连接配置会在读取时转换。

画布选中图层或组件时，输入框上方显示当前选中元素的名称与可读文本摘要。可从 Chat 的目标卡片中单独移除元素，不改变画布选区；移除项不会进入本轮选区摘要或 Agent 的 `get_selection` 结果。发送消息会把保留项的页面 ID 和元素 ID 作为本轮 Agent 的修改目标；模型通过 `get_element` 读取完整内容后再修改，聊天记录仍只显示用户输入的原文。画布选区改变后，Chat 目标会按新的选区重置。

```tsx
import { createPrintDesignAiChatPlugin } from "@canvas-components/print-design-plugin/react";

<ReactPrintDesign
  aiChatPlugin={createPrintDesignAiChatPlugin({
    defaultConfig: {
      baseUrl: "https://example.com/v1",
      model: "example-model",
    },
  })}
/>;
```

默认连接器使用 OpenAI 兼容的 `/v1/models` 和 `/v1/chat/completions`，并通过核心包的 `createPrintDesignAgentApi` 将读取文档、选区和编辑命令作为模型工具提供。Agent 可列出已注册组件、读取默认模板，并基于组件工厂创建表格等插件元素；表格插入行列和合并单元格复用组件命令。其他协议可通过 `provider` 选项替换。模型配置使用浏览器 Web Crypto 加密后保存在 IndexedDB；非 HTTPS 且非 localhost 的页面只能在本次会话中使用自定义模型配置。浏览器端内置的 API Key 会随前端代码交付，无法作为产品方秘密密钥；默认配置适合填入公开地址和模型，密钥由使用者在浏览器中自行填写。

宿主配置 `pluginAuthoring: createBrowserPluginAuthoring()` 后，Agent 可先调用 `get_plugin_structure` 获取目录约定，再向 `create_plugin_archive` 提交源码。每份归档只含一个组件，源码必须包含 `src/native.js` 和 `src/react.js`；可增加 `src/` 下的 `.js` 共享文件，并使用标准 ESM 导入。原生入口只依赖核心包；React 入口除创建器和菜单外，必须通过 `propertySections` 注册右侧配置面板，`fields` 中至少包含一个与元素字段对应的组件专属配置项。`dist/`、`package.json`、`manifest.json` 由浏览器生成，Agent 不提交这些路径。浏览器检查 JavaScript 语法、配置面板与导入路径，校验 ZIP 摘要，再将产物保存在 IndexedDB；下载按钮从本地存储读取 ZIP，不请求打包服务器。下载不等于安装或发布。插件列表的“导入插件包”用于本机安装，允许导入清单标记为不可再分发的 ZIP；“上传到共享库”用于共享发布，仍要求插件包允许再分发。

在新对话中升级已生成插件时，Agent 可调用 `list_plugin_sources` 查找包标识及最新版本，再调用 `get_plugin_source` 读取浏览器本地保存的原始源码。修改后仍通过 `create_plugin_archive` 生成新 ZIP。浏览器关闭或页面刷新后，已保存的下载卡片仍可从 IndexedDB 取回 ZIP。

“外观配置”分类可填写面板的最小、最大、当前宽度（像素）。拖动面板分隔条会更新当前宽度并独立保存到本地存储；首次宽度可由 `createPrintDesignAiChatPlugin({ panelWidths: { min: 280, max: 640, current: 360 } })` 指定。AI 标题行与属性面板标题行使用相同高度。

对话历史只保存在当前浏览器的 IndexedDB，不包含 API Key；点击“新对话”开始独立会话。用户消息位于右侧，AI 回复位于左侧并显示生成时使用的模型名称。内置 OpenAI 兼容提供方流式展示思考和正文；思考区域限高滚动，流式界面仅保留最近的思考文本，回复完成后可展开查看全文。自定义提供方可实现可选的 `stream` 接口，不实现时继续使用 `complete`。`src/ai-chat/index.ts` 是插件入口，`types.ts` 定义宿主协议，`model/` 管理多连接配置及旧版迁移，`providers/` 放模型连接，`persistence/` 分别管理加密模型配置、面板宽度和历史会话，`hooks/` 管理会话状态，`components/` 放对话、虚拟列表及配置对话框。新增模型提供方、消息能力或配置导航项时分别在对应目录扩展。

## 插件编写指南

按项目安装的 `@canvas-components/print-design` 版本选择指南，当前核心包为 `0.1.10`：

-   [人工编写指南](https://npmcn.com/package/%40canvas-components/print-design/docs/plugins/v0.1.10/personal.md)：组件模型、Agent 接入、右侧属性、工具和宿主接入。
-   [AI 编写指南](https://npmcn.com/package/%40canvas-components/print-design/docs/plugins/v0.1.10/ai.md)：任务输入、实现顺序和交付检查。
-   [可编译组件与工具示例](https://npmcn.com/package/%40canvas-components/print-design/docs/plugins/v0.1.10/example.tsx)；其他版本见[指南索引](https://npmcn.com/package/%40canvas-components/print-design/docs/plugins/README.md)。

供 Agent 创建的第三方组件需要注册完整的 `componentFactories`；只有要让 Agent 发现并调用组件专用命令时，才在工厂中声明可选的 `agentCommands`，并在原生组件中实现对应的 `commands.execute`。

当前复杂组件提供的专用 Agent 命令如下。其他组件的常规字段通过 `get_component_template`、`get_element` 和 `update_element` 编辑。

| 组件 | 专用命令 |
| --- | --- |
| 表格 | `insert-row`、`insert-column`、`merge-body`、`merge-header` |
| 透视表 | `move-field`、`remove-field` |
| 甘特图 | `insert-task`、`update-task`、`remove-task` |
| 图表 | `set-categories`、`set-series` |
| 流程图、列表 | `insert-item`、`update-item`、`remove-item` |
| 网格、坐标网格 | `resize-grid`、`set-cell` |
| 图形 | `set-polygon-points`、`set-curve-points`、`set-path-points` |
| 连接线 | `set-endpoint`、`set-waypoints` |
| 图片 | `set-crop`、`clear-crop` |
| 画笔 | `append-stroke`、`remove-stroke` |

`src/plugins/` 下每种内置组件一个目录，例如 `text/`、`table/`、`pivot-table/`。每个目录的 `native.ts` 声明原生输出能力，`menu.ts` 声明左侧菜单入口和预设，`factory.ts` 创建默认元素，`properties.ts` 可声明右侧属性分组，`react.ts` 汇合创建器与编辑能力；包入口只负责汇总与注册。新增组件时先建独立目录，再将其加入两个入口的清单。

组件实现按实际职责放入 `data/`、`layout/`、`rendering/`、`interaction/`，测试与实现同目录；无需的子目录可以省略。表格插件的具体划分见 [`src/plugins/table/README.md`](https://npmcn.com/package/%40canvas-components/print-design-plugin/src/plugins/table/README.md)，整体约定见[插件化计划](https://npmcn.com/package/plan/2610241259-print-design-plugin-components.md)。

组件专属的绘制、数据、分页和交互逻辑由本包各插件目录实现。`print-design` 核心只负责通用文档模型、分页、Canvas/HTML 调度和组件注册分发；核心默认组件注册表为空，未注册的组件会明确报错。复杂字段控件可复用 `react-print-design` 的通用能力。核心包不反向依赖本包或 React。

## 常见问题

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

用于打印设计的原生和反应插件包\.

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

在项目目录运行 npm install @canvas-components/print-design-plugin，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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