Core · 使用插件

模板打印

提供的能力

@nocobase/app-plugin-template-print 提供模板打印的 Agent Skills 与参考实现,帮助应用从 Office 模板和业务数据生成文档,并按需要处理图片、二维码及 PDF 转换。

安装后得到什么

当前包只分发开发指引,没有 Client、Server、CLI 运行时入口,不提供模板表、打印路由、渲染引擎或现成打印页面。安装后,应用仍需实现自己的打印功能。

将兼容版本作为应用的直接开发依赖安装,然后在应用根目录同步:

Bash
pnpm nocobase skills sync

确认应用可读取 nocobase-app-plugin-template-print Skill。无需把该包加入 Client 或 Server 插件注册数组,也不要为了安装 Skill 虚构运行时入口。

使用场景与示例

示例:为订单生成打印文档

可以将下面的需求交给应用 Agent:

纯文本
请使用模板打印 Skill,为当前应用的订单详情增加“下载订单”功能。

使用我提供的 DOCX 模板,填充订单信息、明细与合计。
读取数据时复用当前用户的订单与字段权限。
先实现 DOCX 下载;如果需要 PDF,说明转换依赖并接入应用部署环境。
覆盖无明细、长文本、图片缺失和无权限访问,验证生成文件可正常打开。

实现应由应用或业务插件持有:模板资产、数据查询、渲染依赖、下载接口和按钮。可以先使用固定模板完成一条业务流程,再决定是否需要模板上传、版本管理和预览。

完成标志:授权用户能下载字段与排版正确的 DOCX;需要 PDF 时,在目标环境也能生成可打开的文件。

重要原理与实现

以下是实现本例时的接入位置与预期界面变化;它们是开发说明,具体文件名沿用当前应用结构。

接入位置代码或配置变化界面与行为变化
开发依赖与同步 Skills安装指导包并同步到应用Coding Agent 能读取当前版本指引,不新增运行时插件
模板资产、业务查询与下载接口实现受授权的数据装配和 DOCX 渲染返回真实可打开的文档
订单详情与可选 PDF 环境接入下载按钮、转换依赖和失败反馈用户可以下载,转换失败可解释

内容组织与使用

先确定模板中的字段与重复明细区域,再准备经过授权的数据。图片、二维码、字体和分页需要在目标文档中实际检查。PDF 只是可选输出,转换工具、运行环境和部署依赖必须另外落实,不能因安装本包就认为服务器已有转换能力。

插件源码中的 app-plugin-template-print-example 是独立示例,拥有自己的发票数据、授权、固定 DOCX 和下载界面;它不是本 Skill 包内置的通用渲染服务。

AI 开发的约束与验证

本插件的开发约束

  • 包只提供开发指引,不得导入不存在的运行时入口或声称已有通用打印服务。
  • 模板字段只使用当前用户获准访问的数据,下载接口重新检查记录与字段权限。
  • 真实打开输出文件检查明细、合计、分页和图片;PDF 转换要在实际部署依赖下验证,不能只测接口返回 200。

验证结果

检查生成文档能打开、字段值和合计正确、重复区域与分页合理,并验证当前用户不能打印无权查看的记录或字段。需要 PDF 时,还要在部署环境验证转换、字体和错误处理。

相关文档:持续开发应用、文件、权限管理。

上述检查是接入后的验收要求,不表示本文已完成运行验证。让 Agent 报告实际改动、执行过的检查和未验证项;项目指引、Skills 与通用检查流程见持续开发应用和测试。

源码依据:插件公开入口与实现。

NocoBase 文档助手

关于 NocoBase,你想了解什么?

每次提问独立回答,不会参考之前的问答。请提供完整背景。