# # Stamp 及其自定义

Foxit PDF SDK for Web 提供了丰富的 stamp 功能，用户可以通过 API 和默认图标来实现这些功能。本节将引导您了解如何管理 stamp，以及如何向 PDF 文档中添加 stamp。

## # 默认 stamp 列表

Foxit PDF SDK for Web 在 Viewer 中提供了默认的 stamp 列表，如下所示：

    {
    	"stamp": {
    		"Static": {
    			"Approved": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Completed": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Confidential": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Draft": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Revised": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Emergency": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Expired": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Final": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Received": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Reviewed": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			}
    		},
    		"SignHere": {
    			"Accepted": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Initial": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Rejected": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"SignHere": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Witness": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			}
    		},
    		"Dynamic": {
    			"Approved": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Confidential": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Received": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Reviewed": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			},
    			"Revised": {
    				"url": "xxx://url.url",
    				"fileType": "pdf"
    			}
    		}
    	}
    }

## # 管理 stamp 列表

默认 stamp 列表是不允许更改的。但是，您可以创建自己的 stamp 来替换默认的 stamp，然后对其进行编辑。首先需要制作一个 PDF 文件以及相应的 svg 文件，可以参考 `lib\stamps\en-US\DynamicStamps` 文件夹下的示例。

### # 创建自定义 stamp 列表

自定义 stamp 列表可以通过 API `pdfViewer.initAnnotationIcons()` 来进行预定义，然后将其加载到 viewer 中。运行如下代码后，默认 stamp 列表将被覆盖。

    var initIcons = {
        MyCategory1: {
            StampName1: {
                fileType: "jpg",
                url: "http://stamp.jpg"
            }
        },
        MyCategory2: {
            StampName2: {
                fileType: "png",
                url: "stamp.png"
            }
    },
       ...
    };
    var pdfViewer = await pdfui.getPDFViewer();
    await pdfViewer.initAnnotationIcons({ stamp: initIcons });

### # 移除自定义 stamp

    //remove a stamp with the category and name as 'MyCategory1' and 'StampName1' from you stamp list
    var pdfViewer = await pdfui.getPDFViewer();
    await pdfViewer.removeAnnotationIcon('stamp','MyCategory1','StampName1')

    //clear the whole stamp list
    var pdfViewer = await pdfui.getPDFViewer();
    await pdfViewer.removeAnnotationIcon('stamp','','StampName1')

    //clear all stampes under 'MyCategory1'
    var pdfViewer = await pdfui.getPDFViewer();
    await pdfViewer.removeAnnotationIcon('stamp','MyCategory1','')

### # 添加一个新的自定义 stamp

    var icons = {
        annotType: "stamp",
        fileType: "png",
        url: "http://stamp.png",
        // width:80,
        // height:30,
        category: "MyCategory",
        name: "MyStamp"
    };
    var pdfViewer = await pdfui.getPDFViewer();
    await pdfViewer.addAnnotationIcon(icons);

## # stamp category 及 name

Stamp 是按 category 和 name 进行组织管理的。要找出列表中已经存在的 stamp，简单的方法就是调用 `pdfui.getAnnotationIcons()` 来获取 category 和 name 信息。下面是代码示例。

### # 获取 stamp 的 category 及 name

    //list all available stamps
    await pdfui.getAnnotationIcons("stamp", false);

    //list only custom stamps
    await pdfui.getAnnotationIcons("stamp", true);

您还可以执行以下代码来输出列表中已存在的 stamp。

    var allIcons = pdfui.getAnnotationIcons("stamp", false);
    var iconNames = [];
    for (var categoryKey in allIcons) {
        var category = allIcons[categoryKey];
        for (var name in category) {
            iconNames.push({
                category: categoryKey,
                name
            });
        }
    }
    console.log(iconNames);

## # 在 Viewer 中将 stamp 添加到页面

在 Viewer 的 Comments 选项卡中，下拉 stamp 工具，可以看到 stamp 列表。您可以点击 stamp 图标，然后将其放置在页面所需的位置。

如果您需要在页面上添加一个自定义的 stamp，请按照如下的步骤：

1. 在 Advanced Web Viewer 中，点击 Comment tab，下拉 stamp tool，选择 `Custom Stamps`。

2. 在弹出的 `Create Custom Stamp` 对话框中, 点击 `File -> Browse...` 并选择一个图片文件，或者点击 `File -> Enter File URL`, 输入 PDF 和 SVGA 文件所存放的 URL 地址。

3. 填写 category，name，width，height, 以及从下拉菜单中选择 type，创建 stamp。 创建完成后，自定义的 stamp 就会显示在 Stamp 列表中。

4. 点击自定义的 stamp 图标，然后将其放置在页面所需的位置。

## # 通过 API 在页面上添加自定义 stamp

在调用 `PDFPage.addAnnot` 添加 stamp 列表中不存在的自定义 stamp 时，您需要调用 `PDFViewer.addAnnotationIcon()` 将其添加到 stamp 列表。如果没有添加，则该 stamp 的外观在页面上将不能正确地显示。

    var icons = {
        annotType: "stamp",
        fileType: "png",
        url: "http://stamp.png",
        // width:80,
        // height:30,
        category: "MyCategory",
        name: "MyStamp"
    };

    var stamp = {
        type:'stamp',
        rect:{left:0,bottom:0,right:200,top:100},
        icon:'MyStamp',
        iconCategory:'MyCategory'
    };

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

    await pdfViewer.addAnnotationIcon(icons);
    await page.addAnnot(stamp)

如果只需要在页面上添加新的 stamp，而不需要在 viewer 的 stamp 列表中添加 stamp 图标，可以运行如下的代码：

    pdfpage.addAnnot({
        type: PDFViewCtrl.PDF.annots.constant.Annot_Type.stamp,
        rect: { left: 0, right: 300, top: 450, bottom: 0 },
        iconInfo: {
            annotType: PDFViewCtrl.PDF.annots.constant.Annot_Type.stamp,
            category: "category",
            name: "name",
            fileType: "pdf",
            url: "http://path/file.pdf"
        }
    });

## # 在 Viewer 中将特定的 stamp 设置为默认工具

使用 PDFUI 构造函数将 stamp 定义为默认工具：

    pdfui = new UIExtension.PDFUI({
        customs: {
            defaultStateHandler: PDFViewCtrl.STATE_HANDLER_NAMESSTATE_HANDLER_CREATE_STAMP
    	    handlerParams: {
                category: 'SignHere',
                name: 'SignHere'
            }
        };
    })

使用 API `StateHandlerManager.switchTo()` 设置默认工具：

    pdfui.getStateHandlerManager().then(handlerManager =>
        handlerManager.switchTo(
            PDFViewCtrl.STATE_HANDLER_NAMES.STATE_HANDLER_CREATE_STAMP,
            {
                category: "SignHere",
                name: "SignHere",
    			url: "http://xxx/xx.png",// or "blob:http://xxxxx"
    			showUrl: "http://xxx/xx.png",// or "blob:http://xxxxx"
    			fileType:'png',
    			width:80,
    			height:30,
            }
        )
    );

## # 相关API

API | 描述
--- | ---
PDFViewer.initAnnotationIcons(icons) | 初始化注释的图标(设置后，默认的图标将不会显示)
PDFViewer.addAnnotationIcon(icon) | 添加单个图标
PDFViewer.removeAnnotationIcon(type,category,name) | 移除单个图标
PDFUI.getAnnotationIcons(annotType,onlyCustomized) | 获取自定义图标
StateHandlerManager.switchTo(name,params) | 切换到 addStampStateHandler
PDFViewer.setFormatOfDynamicStamp(seperator,timeFormat) | 设置动态信息的格式
PDFPage.addAnnot(json) | 指定现有图标作为 stamp 样式来添加 stamp