# 签名流程接口升级指南

# 变更背景

自 11.0.0 版本起，Foxit PDF SDK for Web 对签名与验签相关接口进行了重构，旨在提升签名流程的灵活性与可扩展性，同时为开发者提供更强大的自定义能力。新版接口不仅统一了签名与验签的服务入口，还支持签名 UI 的深度自定义，显著提升了多样化业务场景的集成效率。

# 主要变更点

# API 层级调整

旧版通过 PDFUI.registerSignatureFlowHandler 和 PDFUI.setVerifyHandler 等接口实现签名与验签流程的自定义。
新版引入 SignatureWorkflowService，统一管理签名流程、签名者策略，以及签名/验签流程的覆盖等。
新版引入 SignatureService.setVerifyHandler，支持设置全局验签处理器。该处理器不仅在用户手动验签时生效，还会在 JavaScript Action 触发的验签流程中被调用。

# 签名流程自定义

新增 overrideSigningWorkflow 和 overrideVerifyWorkflow 接口，支持开发者对签名与验签流程进行完全自定义。

# 签名者显示策略

新增 setSignerOverridePolicy 接口，允许开发者自定义签名者名称的显示逻辑。

# UI 自定义能力

自 11.0.0 版本起，开发者可通过实现 IViewerUI 及其下的 ISignatureUI、ISignDocDialog、ISignVerifiedResultDialog、ISignedSignaturePropertiesDialog 等接口，完全自定义签名、验签、签名属性等 UI。
只需在初始化 PDFViewer 时注入自定义 UI 的实现类。

# 迁移建议

# 旧接口与新接口对照

旧接口	新接口/用法	说明
`PDFUI.registerSignatureFlowHandler({sign:()=>Promise.resolve(...)})`	`SignatureWorkflowService.overrideSigningWorkflow`	重写签名流程
`PDFUI.registerSignatureFlowHandler({verify:()=>Promise.resolve(...)})`	`SignatureWorkflowService.overrideVerifyWorkflow`	重写验签流程
`PDFUI.registerSignatureFlowHandler({showVerificationInfo: ()=>Promise.resolve(...)})`	`ISignatureUI#getSignVerifiedResultDialog`	自定义验签结果 UI
`PDFUI.registerSignatureFlowHandler({showSignatureProperty: ()=>Promise.resolve(...)})`	`ISignatureUI#getSignVerifiedResultDialog`	自定义签名属性（已签名）结果 UI
`PDFUI.registerSignatureFlowHandler({getSigner: ()=>Promise.resolve(...)})`	`SignatureWorkflowService#setSignerOverridePolicy`	覆盖签名者名称（仅 UI 显示）
`PDFUI.setVerifyHandler`	`SignatureService.setVerifyHandler`	自定义验签流程

# 自定义签名、验签流程代码迁移示例

自定义签名流程：

旧版：

pdfui.registerSignatureFlowHandler({
    sign: (field) => {
        // 返回自定义签名设置
    }
})

新版：

service.overrideSigningWorkflow(async (field) => {
    // 返回自定义签名设置
});

自定义验签流程：

旧版：

pdfui.registerSignatureFlowHandler({
    verify: (field) => {
        // 返回验签结果
    }
})

新版：

service.overrideVerifyWorkflow(async (signature) => {
    // 返回验签结果
});

# UI 自定义接口迁移示例

旧版

pdfui.registerSignatureFlowHandler({
    showVerificationInfo: field => {
        // 显示验签信息
    },
    showSignatureProperty: field => {
        // 显示签名属性
    }
})

新版

class CustomSignatureUI implements ISignatureUI {
    async getSignDocumentDialog() {
        /* ... */
    }
    async getSignVerifiedResultDialog() {
        /* ... */
    }
    async getSignedPropertiesDialog() {
        /* ... */
    }
}
class CustomViewerUI extends PDFViewCtrl.TinyViewerUI {
    async getSignatureUI() {
        return new CustomSignatureUI();
    }
}
new PDFViewer({
    viewerUI: new CustomViewerUI(),
    // 其他配置...
});

# 注意事项

新接口需配合 Foxit PDF SDK for Web 11.0.0 及以上版本使用。
自定义 UI 时需严格实现接口定义，注意资源释放与异步处理。
旧接口自 11.0.0 版本起已标记为不推荐使用，建议尽快迁移至新版接口。

有关详细的接口说明和更多示例，请参阅相关文档：

← PDF Action API 迁移指南缩略图加载错误 →