Appearance
Ukey签章
Ukey 签章使用插入电脑的硬件 Ukey 中的证书完成 PDF 数字签署。用户在电脑上拖拽章面或加盖骑缝章，保存时按提示验证 Ukey PIN。接入方开启免密签署后，可复用驱动仍有效的 PIN 验证状态。
本页介绍 PC 页面使用方式。SDK 的引入、页面渲染和文件加载分别见快速上手、SDK 通用设置与文件操作。通过手机扫码授权的使用方式见移动签章。
使用前准备
- 电脑已安装并运行配套的本地签署驱动，Ukey 已插入电脑且能被驱动识别。
- Ukey 中具有可用的签署证书；使用有外观签章时，还需有可用章面。
- 已打开待签的未加密 PDF，并允许当前页面进行签署，即
canSign: true。 - 知道当前 Ukey 的 PIN，用于保存时验证。
页面使用流程
操作顺序：打开 PDF → 插入 Ukey → 选择 Ukey签章 → 放置章面 → 保存并按需验证 PIN → 下载或提交结果。
以下截图来自当前 SDK 的演示页面，文件、证书信息和章面均为演示数据。点击截图可查看原图，实际使用时请以自己的设备和证书为准。
第一步：进入 Ukey 签章
打开 PDF，点击顶部工具栏的签章图标，在左侧选择“Ukey签章”。驱动识别设备后，面板展示证书状态和可用章面。
如果提示未插入 Ukey，先检查设备连接和驱动运行状态；若提示证书过期或当前设备不匹配，请更换为可用且符合业务要求的 Ukey。
第二步：拖拽加盖普通章
- 从左侧面板选择需要的章面，按住并拖入 PDF 的签署位置后松开。
- 保存前可拖动 PDF 上的章面调整位置，也可使用章面工具栏删除不需要的待签位置。
- 多份 PDF 需要使用同一证书签署时，可逐份切换文件并放置章面，再统一保存。
放置章面只是确定待签位置，尚未将数字签名写入 PDF。
业务开启批注功能后，还可为普通章添加说明文字，具体操作见批注。
第三步：按需加盖骑缝章
点击章面对应的“加盖骑缝章”，在“批量应用多文件多页面”弹窗中设置应用方式、页面和文件，点击“确定”后检查位置。
- “每份文件单独加盖骑缝章”分别为各份文件创建骑缝章。
- “多份文件合并统一加盖骑缝章”将勾选文件的页面作为一组处理。
- “全部页面”适用于单面打印；独立加盖时，每份文件至少需要两页。
- “奇数页”适用于双面打印；独立加盖时，每份文件至少需要三页。
保存前可上下拖动骑缝章调整位置。加密文件不能参与加盖。
第四步：保存并按需验证 PIN
确认位置后，点击头部“保存”。出现“保存签名”弹窗时，输入当前 Ukey 的 PIN 并点击“确定”；验证通过后，页面执行签署。
默认每次保存都会打开 PIN 弹窗。已开启免密签署且驱动确认 PIN 验证状态仍有效时，点击“保存”会直接执行签署，详见下方免密签署。
取消或关闭 PIN 弹窗会终止本次签署验证。签署过程中请保持 Ukey 和本地驱动连接，不要更换设备或切换签章方式。
保存只处理当前所选 Ukey 证书的待签位置，范围包括所有已加载 PDF，不限于当前显示的文件。其他证书或移动印章的待签位置不会一并签署。
第五步：获取签署结果
保存成功后，可通过业务页面提供的下载或提交入口获取文件。SDK 接入方通过 signCb(files) 接收本批次成功签署的文件数组，再读取 rawFileData 下载或上传，具体见签署结果与下载。
“保存”不会自动下载文件或上传至业务服务器；下载也不会代替数字签署。
免密签署
免密签署用于减少重复输入 Ukey PIN。此功能由接入方通过 enablePasswordFree 开启，默认值为 false，页面没有单独的免密开关。
typescript
/** 允许在保存时复用本地驱动仍有效的 PIN 验证状态。 */
const sdk = new QysUKeySdk({
canSign: true,
enablePasswordFree: true,
});
对已有实例，可通过 sdk.updateConfig({ enablePasswordFree: true }) 开启，或设置为 false 关闭；配置会在后续点击保存时生效。
用户如何使用
- 按普通签章流程放置章面，检查位置后点击“保存”。无外观签名则直接保存。
- 如果驱动尚未保留有效的 PIN 验证状态，仍会显示图 5 的“保存签名”弹窗。输入 PIN 并确认后，完成本次验证与签署。
- 后续再次保存时，SDK 会重新查询驱动。只有驱动确认验证状态仍有效，才会跳过 PIN 弹窗直接签署；状态无效或查询失败时，仍需输入 PIN。
- 保存完成后，按获取签署结果下载或提交文件。
| 保存时的条件 | 页面行为 |
|---|---|
enablePasswordFree: false | 每次保存均弹出 PIN 输入框。 |
| 已开启免密，驱动确认 PIN 已验证 | 跳过 PIN 弹窗，直接签署当前证书的待签文件。 |
| 已开启免密，驱动未确认有效验证状态 | 显示 PIN 输入框，验证成功后继续签署。 |
验证状态的有效时长由设备和驱动决定，SDK 没有固定的免密有效期。重新插拔或更换 Ukey、重启驱动后，请按页面实际提示验证。免密仅适用于硬件 Ukey；移动签章仍按手机端授权与确认流程操作。
无外观签名
当 Ukey 证书不包含章面时，面板会显示“无外观签名”。检测到唯一且符合设备与章面限制的无外观证书后，页面会自动选中该证书；此时无需拖拽章面，直接点击“保存”并按需完成 PIN 验证即可。
签署后的 PDF 不显示印章图像，但会包含可验证的数字签名。无外观签名只处理符合条件且没有章面记录的文件，不会覆盖其他来源的待签位置，也不会因再次点击保存而为已有章面记录的文件重复补签。此方式同样支持上述免密设置。
Ukey 专属设置
以下配置只用于硬件 Ukey 方式；其他页面和文件配置见 SDK 通用设置。
| 配置项 | 用途 |
|---|---|
signDevice.deviceId | 限定可用于签署的 Ukey 设备号；插入其他设备时提示设备不匹配。 |
signDevice.sealNames | 限定该设备可使用的章面名称，支持多个名称；未配置时展示该设备可用章面。 |
enablePasswordFree | 默认 false；允许复用驱动有效的 PIN 验证状态，具体流程见免密签署。 |
typescript
/** 按业务要求限定可签署的硬件设备和章面。 */
const sdk = new QysUKeySdk({
canSign: true,
signDevice: { deviceId: '实际设备号', sealNames: ['实际章面名称'] },
});
切换签章方式
切换“Ukey签章”与“移动签章”本身会保留文件上的待签章面。移动授权仍有效时，切回移动签章无需重新扫码。
若实际加盖 Ukey 章面时存在移动签章的未保存章面，会出现替换提示。点击“确认”后，清理所有已加载 PDF 中的全部未保存章面，再加盖本次章面；取消或关闭提示框则保留原章面。已保存的数字签章始终保留。
常见提示
| 提示或现象 | 处理方式 |
|---|---|
| 未连接驱动或未插入 Ukey | 启动驱动，重新连接设备，等待页面识别。 |
| 设备或章面不匹配 | 检查业务是否配置了 signDevice，使用指定设备和章面。 |
| 检测到证书已过期 | 使用有效的签署证书后重试。 |
| PIN 验证失败 | 按弹窗提示检查当前 Ukey 的 PIN，确认使用的是同一设备。 |
| 已开启免密，保存时仍需输入 PIN | 驱动未确认有效的 PIN 验证状态时仍会弹窗，请完成本次验证；开启免密不代表永久跳过 PIN。 |
| “保存”不可用 | 确认已打开可签署 PDF、已识别可用证书且存在该证书的待签位置；无外观签名按上节规则处理。 |
| 保存前更换了 Ukey | 插回创建待签章面的原 Ukey，或使用新证书重新放置章面。 |