#模板打印

模板打印适合按照固定版式，把业务数据填入合同、订单、发票或报表模板，再下载生成文件。你可以提供现有模板和业务规则，让应用 Agent 在 NocoBase 应用中实现打印入口和文件生成。

先明确一个边界：@nocobase/app-plugin-template-print 提供的是 Agent Skill 和实现参考，不是可以直接启用的打印功能。安装后不会自动出现打印按钮、模板管理页或渲染服务；Agent 仍需要在目标应用或业务插件中完成这些功能。

#适合什么场景

• 从订单详情生成一份填好客户、金额和明细的合同
• 从列表中选择多条记录，生成一份发货清单
• 按现有 Office 模板生成 DOCX、XLSX 或 PPTX 文件
• 在已有文件生成流程上增加 PDF 输出或图片、二维码

如果只需要浏览器打印当前页面，通常先用浏览器的打印功能即可，不需要模板打印。模板打印用于生成有固定版式、可归档或可发送的文件。

#接入前要准备什么

• 能让开发 Agent 读取和修改的目标 NocoBase 应用
• 一份实际模板；没有模板时，先描述版式并让 Agent 生成样例供你确认
• 一条代表性业务记录，包含常见字段、明细和可能出现的空值
• 期望的打印入口、记录范围、输出格式和访问权限

这不是在 Settings 页面中启用的运行时插件。先让开发 Agent 检查当前应用是否已经安装并同步模板打印 Skill：

请检查当前应用是否已经安装并同步 nocobase-app-plugin-template-print Skill。如果没有，请将对应包安装为应用的开发依赖，并使用当前应用支持的 Skills 同步方式完成同步。确认你能读取 Skill 后，再开始实现打印功能。这个包只提供实现指导，不会自动添加打印按钮或运行时服务。

同步后，Agent 可以读取模板打印指导。业务用户最终使用的是 Agent 为应用实现的页面和按钮，不需要学习 Skill 或执行安装命令。

#示例：从订单生成合同

把实际 DOCX 模板和示例订单一并提供给 Agent，再发送下面的需求。将方括号中的内容替换成应用中的真实信息：

请使用 nocobase-app-plugin-template-print Skill，为订单详情页添加「打印合同」功能。

使用我提供的 DOCX 合同模板，为当前订单填入客户名称、联系人、订单编号、订单明细、数量、单价和总金额。重复明细按模板中的表格行展开，保留模板已有的页眉、签名区域和版式。生成文件名使用“合同-订单编号”，提供 DOCX 下载。

开始前先检查应用中实际的订单字段、客户和联系人关系、详情页位置，以及当前用户的订单访问权限。只能读取用户有权查看的数据；附件或模板也要遵守应用权限。不要修改订单原始数据。

请先用我提供的示例订单生成一份文件。完成后告诉我按钮在哪里，并检查客户信息、明细行、金额、空字段和分页是否正确；如果模板有无法保留的格式，请先指出再继续。

#预期效果

订单详情页出现「打印合同」入口。用户点击后下载带有当前订单数据的 DOCX 文件，模板的固定版式和签名区域仍然保留。

验收时使用至少一条包含多条明细的订单，并检查生成文件能在目标 Office 软件中打开。还要用无权访问该订单的账号确认下载接口不会返回文件。

#进一步使用

#批量打印

批量任务要说明记录范围和文件组织方式。比如只处理勾选的订单，生成一个按订单号排序的 XLSX 文件：

在订单列表添加「导出发货清单」。使用我提供的 XLSX 模板，只处理我勾选的订单，不要包含未勾选记录。每条订单显示收货人、地址和商品明细，按订单编号排序，输出一个 XLSX 文件。没有勾选时提示我先选择记录；如果选择记录超过 200 条，提示缩小范围。请验证跨页勾选和无权限订单的处理方式。

「当前页」「已勾选记录」和「全部筛选结果」是不同的打印范围。要让 Agent 按业务需要实现其中一种，避免结果意外包含更多记录。

#增加 PDF、图片或二维码

说明图片放在模板的什么位置、二维码指向哪里，以及 PDF 必须保留哪些字体和分页效果：

在订单合同中加入公司 Logo、当前订单的签收图片和指向订单页面的二维码，并增加 PDF 下载。私有图片只能由有权访问订单的用户读取。请说明 PDF 转换需要的部署组件和字体，在目标部署环境用中文、多页订单验证生成效果；转换失败时显示清楚的错误信息。

PDF 转换通常需要额外的服务端转换环境和字体。下载 PDF 后可以由用户通过查看器选择打印机；如果要静默调用用户电脑上的打印机，需要单独设计客户端方案。

#让业务用户管理多份模板

只有当业务人员需要上传、替换或选择模板时，再要求 Agent 增加模板管理：

销售合同有国内版和海外版。请增加模板管理，让管理员上传和替换模板，销售人员打印时选择适用版本。模板需要绑定订单数据，替换模板后也不能影响正在生成的合同；普通销售人员不能上传或修改模板。请先告诉我需要哪些模板字段、权限和版本规则，再实现并用两份模板验证。

固定模板可以随应用代码维护。上传、版本管理、选择模板和管理权限都需要额外实现，不会因安装模板打印 Skill 自动获得。

#使用时要留意

• 每次打印都要明确是当前记录、选中记录、当前页还是全部筛选结果
• DOCX、XLSX、PPTX 和 PDF 的实际生成效果取决于 Agent 选择并接入的渲染方案，需要用目标模板和部署环境验证
• PDF 可能需要额外转换服务和中文字体，不能只在开发机检查
• 服务器生成文件前应先校验用户权限，再读取业务数据、模板和附件
• 插件只同步指导资料；完成后还需要在实际应用页面下载文件并检查版式

安装后没有打印按钮是预期行为。先确认 Skill 已同步给开发 Agent，再明确提出要添加的业务入口、模板、数据范围和输出格式。

#相关链接

• 怎么提需求 —— 向应用 Agent 说明业务规则和验收结果
• 文件 —— 了解上传、附件和文件访问
• 权限 —— 了解数据和功能的访问范围