# # 签名流程接口升级指南

## # 变更背景

自 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` | 自定义验签流程

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

1. 自定义签名流程：

   旧版：

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

   新版：

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

2. 自定义验签流程：

   旧版：

       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 版本起已标记为不推荐使用，建议尽快迁移至新版接口。

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

- 旧版签名接口文档
- 新版签名流程接口文档
- 签名 UI 自定义文档