福昕开发者文档中心

图章 ​

福昕 PDF SDK（Web）支持通过完整 UI（UIExtension）创建和管理图章注释，也支持通过 API 管理图章图标资源并向页面添加 stamp 注释。完整 UI 已内置图章下拉列表、动态图章入口和图章管理相关界面；需要自定义图章资源、程序化添加图章或接入业务图章库时，可使用本文介绍的接口。

相关接口包括：

  • PDFViewer.initAnnotationIcons()：初始化一组图章图标；设置后会替换 UIExtension 默认图章列表。
  • PDFViewer.addAnnotationIcon()：向图章列表追加一个自定义图章图标。
  • PDFViewer.removeAnnotationIcon()：移除自定义图章图标。
  • PDFUI.getAnnotationIcons()：读取图章列表，可选择只读取自定义图章。
  • PDFViewer.setFormatOfDynamicStamp() / getFormatOfDynamicStamp()：设置或读取默认动态图章中的用户和时间格式。
  • PDFPage.addAnnot()：向页面添加 stamp 注释。

如果需要创建带用户姓名、日期时间或自定义字段的动态图章，请参阅 自定义动态图章。

图章类型 ​

UIExtension 默认图章通常包含三类：

  • Static：固定外观的常规图章，例如 Approved、Draft、Final 等。
  • SignHere：签署指示类图章，例如 Sign Here、Initial、Witness 等。
  • Dynamic：带用户姓名、日期或时间等动态信息的图章。

默认图章列表由 SDK 内置资源提供，不建议直接修改。需要使用业务自己的图章时，应通过自定义图章接口添加或替换图章列表。

初始化自定义图章列表 ​

PDFViewer.initAnnotationIcons(icons) 用于初始化图章图标列表。该接口支持数组格式；设置后，默认图章列表会被替换。

javascript
const pdfViewer = await pdfui.getPDFViewer();

await pdfViewer.initAnnotationIcons([
    {
        annotType: 'stamp',
        category: 'Business',
        name: 'Approved',
        fileType: 'png',
        url: 'https://example.com/stamps/approved.png',
        width: 150,
        height: 45
    },
    {
        annotType: 'stamp',
        category: 'Business',
        name: 'Rejected',
        fileType: 'pdf',
        url: 'https://example.com/stamps/rejected.pdf',
        width: 150,
        height: 45
    }
]);

提示

url 支持 HTTP URL、Blob URL 和 Base64 URL。旧版本对象格式（{ stamp: { category: { name: ... } } }）仍可用于兼容，但新文档建议使用数组格式。

添加单个图章图标 ​

PDFViewer.addAnnotationIcon(icon) 用于向图章列表追加一个自定义图章。

javascript
await pdfViewer.addAnnotationIcon({
    annotType: 'stamp',
    category: 'Business',
    name: 'Reviewed',
    fileType: 'webp',
    url: 'https://example.com/stamps/reviewed.webp',
    width: 150,
    height: 45
});

常用字段如下：

字段说明
annotType当前仅支持 'stamp'。
category图章分类名称。
name图章名称，同一分类下应唯一。
fileType图章资源类型，支持 png、jpg、jpeg、bmp、webp、pdf 等。
url图章资源地址，支持 HTTP、Blob URL、Base64 URL。
width / height图章默认尺寸，使用 PDF 坐标单位。

category 和 name 不应包含特殊字符，例如 ~!@#$%^&*()=;[]{}。

移除自定义图章 ​

javascript
// 移除指定图章
await pdfViewer.removeAnnotationIcon('stamp', 'Business', 'Reviewed');

// 移除指定分类下的所有图章
await pdfViewer.removeAnnotationIcon('stamp', 'Business', '');

// 移除所有自定义图章
await pdfViewer.removeAnnotationIcon('stamp', '', '');

读取图章列表 ​

javascript
// 读取默认图章和自定义图章
const allStamps = await pdfui.getAnnotationIcons('stamp', false);

// 只读取自定义图章
const customStamps = await pdfui.getAnnotationIcons('stamp', true);

返回结果按分类组织，可用于渲染业务侧图章选择面板。

向页面添加图章 ​

如果图章已经在图章列表中，可通过 icon 和 iconCategory 指定图章外观。

javascript
const pdfViewer = await pdfui.getPDFViewer();
const pdfDoc = pdfViewer.getCurrentPDFDoc();
const page = await pdfDoc.getPageByIndex(0);

await page.addAnnot({
    type: 'stamp',
    rect: {
        left: 100,
        right: 250,
        top: 720,
        bottom: 675
    },
    icon: 'Approved',
    iconCategory: 'Business'
});

如果只想程序化添加图章，而不把图章显示在 Viewer 的图章列表中，可以在注释 JSON 中直接传入 iconInfo。

javascript
await page.addAnnot({
    type: 'stamp',
    rect: {
        left: 100,
        right: 250,
        top: 720,
        bottom: 675
    },
    iconInfo: {
        annotType: 'stamp',
        category: 'Business',
        name: 'Internal',
        fileType: 'png',
        url: 'https://example.com/stamps/internal.png',
        width: 150,
        height: 45
    }
});

设置默认动态图章格式 ​

默认动态图章会使用用户名和时间等动态信息。可以通过 PDFViewer.setFormatOfDynamicStamp(separator, timeFormat) 调整用户名与时间之间的分隔符和时间格式。

javascript
await pdfViewer.setFormatOfDynamicStamp(' ', 'yyyy-mm-dd HH:MM:ss');

const format = await pdfViewer.getFormatOfDynamicStamp();
console.log(format);

保存图章 ​

图章是注释。添加、删除或修改图章后，如需写入文件，应导出或保存 PDF。

javascript
const file = await pdfDoc.getFile({
    fileName: 'stamps.pdf'
});

注意事项 ​

  • 图章矩形使用 PDF 坐标，不是 Viewer 的 device pixels。
  • initAnnotationIcons() 会替换默认图章列表；如果只想追加图章，请使用 addAnnotationIcon()。
  • 通过 icon / iconCategory 添加图章前，应确保图章图标已初始化或已添加到图章列表。
  • 自定义图章资源需要可被浏览器访问；跨域资源应正确配置 CORS。
  • 修改图章注释后，如需保存结果，应导出或保存 PDF 文件。