HarmonyOS

UI 初始化

import { UIAbility } from '@kit.AbilityKit'
import { window } from '@kit.ArkUI'
import { BJCASDK } from '@szyx/sdk_ywx'

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (error): void => {
      if (error.code) {
        AppStorage.setOrCreate<string>('sdkReadyStatus', 'HOST_PAGE_LOAD_FAILED')
        return
      }
      const result = BJCASDK.initialize(windowStage.getMainWindowSync().getUIContext())
      AppStorage.setOrCreate<string>('sdkReadyStatus', result.status)
    })
  }
}

权限

entry 模块 module.json5：

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.ACCESS_BIOMETRIC" },
      { "name": "ohos.permission.PRIVACY_WINDOW" },
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:permission_h5_camera",
        "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
      },
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:permission_h5_microphone",
        "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
      }
    ]
  }
}

在 resources/base/element/string.json 添加上述权限说明：

{
  "string": [
    { "name": "permission_h5_camera", "value": "用于证书身份认证时的拍摄核验" },
    { "name": "permission_h5_microphone", "value": "用于证书身份认证时的音视频核验" }
  ]
}

初始化 SDK

接口： initialize

绑定当前窗口的 UIContext，供 SDK 页面与 PIN 弹窗使用。

调用示例

const result = BJCASDK.initialize(uiContext)

返回结果

返回类型：YwxResult<undefined>。

返回 UI 上下文绑定结果；参数为空为 1003，绑定失败为 1027。

YwxResult<T> 通用结果

error 字段

获取配置管理器

接口： settingManager

取得环境、clientId 与页面配置接口。

调用示例

const result = BJCASDK.settingManager()

参数： 无。

返回结果

返回类型：SettingManager。

返回配置管理器。

获取证书管理器

接口： certManager

取得证书下载、更新、查询与清除接口。

调用示例

const result = BJCASDK.certManager()

参数： 无。

返回结果

返回类型：CaManager。

返回证书管理器。

获取签名管理器

接口： signManager

取得签名、签章、免密与生物识别接口。

调用示例

const result = BJCASDK.signManager()

参数： 无。

返回结果

返回类型：SignManager。

返回签名管理器。

导出加密日志

接口： exportEncryptedLogs

导出 SDK 本地加密日志文件。

调用示例

const exported = await BJCASDK.exportEncryptedLogs()
if (exported.isSuccess() && exported.data) {
  const filePath: string = exported.data.path
  const count: number = exported.data.segmentCount
  const recordingFailure: string | undefined = exported.data.recordingFailure
  // 使用 filePath 保存或分享文件。
}

参数： 无。

返回结果

返回类型：Promise<YwxResult<EncryptedLogExport>>。

成功 data 包含 path、segmentCount 和可选 recordingFailure；导出失败为 1023。

EncryptedLogExport 字段

设置服务环境

接口： configure

配置集成或生产服务环境。

调用示例

const result = await BJCASDK.settingManager().configure(EnvEnum.PUBLIC)

返回结果

返回类型：Promise<YwxResult<undefined>>。

返回配置结果；参数错误为 1003，SDK 忙为 1017。

environment 取值

设置 clientId

接口： setClientId

配置分配给接入应用的 clientId。

调用示例

const result = await BJCASDK.settingManager().setClientId(clientId)

返回结果

返回类型：Promise<YwxResult<undefined>>。

返回配置结果；clientId 为空为 1003，SDK 忙为 1017。

获取设备标识

接口： getDeviceId

获取 SDK 业务请求使用的设备标识。

调用示例

const result = await BJCASDK.settingManager().getDeviceId()

参数： 无。

返回结果

返回类型：Promise<YwxResult<string>>。

成功 data 为设备标识字符串。

获取 SDK 版本

接口： getVersion

读取当前集成的 SDK 版本号。

调用示例

const result = BJCASDK.settingManager().getVersion()

参数： 无。

返回结果

返回类型：string。

返回版本字符串 2.0.1-alpha.24。

获取当前环境

接口： getServerEnvType

读取 SDK 当前使用的服务环境。

调用示例

const result = BJCASDK.settingManager().getServerEnvType()

参数： 无。

返回结果

返回类型：YwxResult<EnvEnum>。

成功 data 为当前 EnvEnum。

获取 clientId

接口： getClientId

读取 SDK 当前配置的 clientId。

调用示例

const result = BJCASDK.settingManager().getClientId()

参数： 无。

返回结果

返回类型：YwxResult<string>。

成功 data 为当前 clientId。

获取用户 OpenId

接口： getOpenId

读取当前证书用户的 OpenId。

调用示例

const result = BJCASDK.settingManager().getOpenId()

参数： 无。

返回结果

返回类型：YwxResult<string>。

成功 data 为当前用户 OpenId；缺证书为 1001。

设置页面语言

接口： setLanguage

切换 SDK 页面的显示语言。

调用示例

const result = BJCASDK.settingManager().setLanguage(language)

返回结果

返回类型：YwxResult<undefined>。

返回设置结果；支持 zh、en，其他值为 1003。

获取页面语言

接口： getLanguage

读取 SDK 当前页面语言。

调用示例

const result = BJCASDK.settingManager().getLanguage()

参数： 无。

返回结果

返回类型：string。

返回当前页面语言，默认 zh。

设置页面导航栏

接口： setNavigationBar

设置 SDK 页面标题、颜色与返回图标。

调用示例

import { BJCASDK, NavigationBarConfig } from '@szyx/sdk_ywx'

const config = new NavigationBarConfig('#333333', '#FFFFFF', '签名')
const result = BJCASDK.settingManager().setNavigationBar(config)

config 构造参数（按表格顺序传入）

返回结果

返回类型：YwxResult<undefined>。

返回样式设置结果；颜色或字号不合法为 1003。

查询本地证书

接口： existsCert

查询当前用户是否有本地证书。

调用示例

const result = BJCASDK.certManager().existsCert(phone)

返回结果

返回类型：YwxResult<boolean>。

成功 data 为 boolean；传 phone 时同时选定该手机号，未传时查询当前用户。

批量查询本地证书

接口： BJCASDK.certManager().queryCertificateStates(queries)

查询指定平台和厂商的本地证书状态。

调用示例

import { BJCASDK, CertificateQuery, EnvEnum } from '@szyx/sdk_ywx'
const queries: CertificateQuery[] = [new CertificateQuery(EnvEnum.PUBLIC, firmId)]
const result = BJCASDK.certManager().queryCertificateStates(queries)
if (result.isSuccess()) {
  result.data?.forEach(state => console.info(`${state.firmId}: ${state.exists}`))
}

CertificateQuery 构造参数（按顺序传入）

返回结果

YwxResult<CertificateState[]>，同步返回；成功时 data 数组的字段如下。

清除本地证书

接口： clearCert

清除当前用户的本地证书及相关授权状态。

调用示例

BJCASDK.certManager().clearCert()

参数： 无。

返回结果

返回类型：void。

无返回值。

下载证书

接口： certDown

打开 SDK 证书申领与下载流程。

调用示例

const result = await BJCASDK.certManager().certDown(phone)

返回结果

返回类型：Promise<YwxResult<CertificateResult>>。

成功 data 为 CertificateResult，action 为 DOWNLOAD；手机号为空或格式错误返回 1002。

CertificateResult 字段

更新证书

接口： certUpdate

打开当前用户的证书更新流程。

调用示例

const result = await BJCASDK.certManager().certUpdate()

参数： 无。

返回结果

返回类型：Promise<YwxResult<CertificateResult>>。

成功 data 为 CertificateResult，action 为 UPDATE；未到更新条件返回 1007。

CertificateResult 字段见对应返回说明。

重置签名密码

接口： certResetPin

打开签名 PIN 重置流程。

调用示例

const result = await BJCASDK.certManager().certResetPin()

参数： 无。

返回结果

返回类型：Promise<YwxResult<CertificateResult>>。

成功 data 为 CertificateResult，action 为 RESET_PIN。

CertificateResult 字段见对应返回说明。

查看证书详情

接口： showCert

打开 SDK 证书详情页面。

调用示例

const result = await BJCASDK.certManager().showCert()

参数： 无。

返回结果

返回类型：Promise<YwxResult<CertificateResult>>。

成功 data 为 CertificateResult，action 为 VIEW。

CertificateResult 字段见对应返回说明。

获取用户信息

接口： getUserInfo

查询当前证书用户的资料。

调用示例

const result = await BJCASDK.certManager().getUserInfo()

参数： 无。

返回结果

返回类型：Promise<YwxResult<UserInfo>>。

成功 data 为 UserInfo。

UserInfo 字段

显示 PIN 输入框

接口： showPinWindow

打开 SDK PIN 输入窗口并取得输入结果。

调用示例

const result = await BJCASDK.signManager().showPinWindow()

参数： 无。

返回结果

返回类型：Promise<YwxResult<PinResult>>。

成功 data 为 PinResult；已有 PIN 窗口时为 1017，取消为 3000。

PinResult 字段

关闭 PIN 输入框

接口： hidePinWindow

关闭已显示的 SDK PIN 输入窗口。

调用示例

const result = await BJCASDK.signManager().hidePinWindow()

参数： 无。

返回结果

返回类型：Promise<YwxResult<PinResult>>。

成功 data 为 PinResult，其中 pin、encodedPin 为空字符串。

PinResult 字段见对应返回说明。

获取签章图片

接口： getStampPic

读取当前用户的 Base64 签章图片。

调用示例

const result = await BJCASDK.signManager().getStampPic()

参数： 无。

返回结果

返回类型：Promise<YwxResult<StampResult>>。

成功 data 为 StampResult，读取 stampPic；无签章为 1002。

StampResult 字段

设置签章图片

接口： drawStamp

打开 SDK 手写签章页面并保存签章。

调用示例

const result = await BJCASDK.signManager().drawStamp()

参数： 无。

返回结果

返回类型：Promise<YwxResult<StampResult>>。

成功 data 为 StampResult；用户取消为 3000。

StampResult 字段见对应返回说明。

签署待签数据

接口： sign

对服务端生成的待签 ID 列表完成签署。

调用示例

const result = await BJCASDK.signManager().sign(uniqueIds)
if (result.isSuccess() && result.data) {
  const completedIds: string[] = result.data.uniqueIds
  const failedIds: string[] = result.data.failedUniqueIds
} else {
  const status: string = result.status
  const message: string = result.message
}

返回结果

返回类型：Promise<YwxResult<SignatureResult>>。

成功 data 为 SignatureResult，包含 uniqueIds、failedUniqueIds；待签 ID 数量范围为 1～100。

SignatureResult 字段

协同签名

接口： teamSign

对协同签名业务的待签 ID 列表完成签署。

调用示例

const result = await BJCASDK.signManager().teamSign(uniqueIds)

返回结果

返回类型：Promise<YwxResult<SignatureResult>>。

成功 data 为 SignatureResult，包含 uniqueIds、failedUniqueIds。

SignatureResult 字段见对应返回说明。

授权他人签名

接口： grantSignature

向指定用户授予限定时长的签名权限。

调用示例

const result = await BJCASDK.signManager().grantSignature(grantedUserId, hours)

返回结果

返回类型：Promise<YwxResult<GrantResult>>。

成功 data 为 GrantResult，包含 grantedUserId、hours；hours 为正整数小时。

GrantResult 字段

开启免密签名

接口： keepPin

校验 PIN 并设置免密有效天数。

调用示例

const result = await BJCASDK.signManager().keepPin(keepDays)

返回结果

返回类型：Promise<YwxResult<PinResult>>。

成功 data 为 PinResult；keepDays 为 1～60，参数错误为 1003 或 1008。

PinResult 字段见对应返回说明。

关闭免密签名

接口： clearPin

关闭免密签名。

调用示例

const result = await BJCASDK.signManager().clearPin()

参数： 无。

返回结果

返回类型：Promise<YwxResult<boolean>>。

成功 data 为 true。

查询免密状态

接口： isPinExempt

读取当前用户是否已开启免密签名。

调用示例

const result = BJCASDK.signManager().isPinExempt()

参数： 无。

返回结果

返回类型：YwxResult<boolean>。

成功 data 为 boolean。

查询可用生物识别类型

接口： getSupportedBiometricTypes

获取设备当前可用于签名认证的指纹或人脸类型。

调用示例

const result = await BJCASDK.signManager().getSupportedBiometricTypes()

参数： 无。

返回结果

返回类型：Promise<YwxResult<BiometricType[]>>。

成功 data 为 BiometricType[]；无可用类型时为空数组。

BiometricType 取值

开启生物识别签名

接口： openBiometric

通过 PIN 校验与系统生物认证开启签名授权。

调用示例

const result = await BJCASDK.signManager().openBiometric(type)

返回结果

返回类型：Promise<YwxResult<PinResult>>。

成功 data 为 PinResult；类型取 Fingerprint 或 Face，取消为 3000。

PinResult 字段见对应返回说明。

关闭生物识别签名

接口： closeBiometric

关闭生物识别签名。

调用示例

const result = await BJCASDK.signManager().closeBiometric()

参数： 无。

返回结果

返回类型：Promise<YwxResult<PinResult>>。

成功 data 为 PinResult。

PinResult 字段见对应返回说明。

查询生物识别状态

接口： isBiometric

读取当前用户的生物识别签名开关状态。

调用示例

const result = BJCASDK.signManager().isBiometric()

参数： 无。

返回结果

返回类型：YwxResult<FingerSignState>。

成功 data 为 FingerSignState.ON 或 FingerSignState.OFF。

处理业务二维码

接口： qrDispose

接收扫码文本并执行签名或授权登录流程。

调用示例

const result = await BJCASDK.signManager().qrDispose(qrText, handleGrantedOauth)

返回结果

返回类型：Promise<YwxResult<QrCodeResult>>。

成功 data 为 QrCodeResult；二维码不支持为 2002，平台不匹配为 1020。授权登录返回 oauth.selectionRequired=true 时，从 oauth.grantedUsers 选择用户，再调用 startOauthLogin。

QrCodeResult 字段

嵌套结果：SignatureResult、OAuthResult、AutoSignResult。

完成授权登录

接口： startOauthLogin

根据授权请求和所选授权人完成登录流程。

调用示例

const result = await BJCASDK.signManager().startOauthLogin(uuid, grantOpenId, grantUserName)

返回结果

返回类型：Promise<YwxResult<OAuthResult>>。

成功 data 为 OAuthResult，selectionRequired 为 false。

OAuthResult 字段

GrantedUser 字段

开启自动签名

接口： startAutoSign

打开自动签名授权流程。

调用示例

const result = await BJCASDK.signManager().startAutoSign(systemTag)

返回结果

返回类型：Promise<YwxResult<AutoSignResult>>。

成功 data 为 AutoSignResult；未指定 systemTag 时显式传 undefined。

AutoSignResult 字段

AutoSignSession 字段

查询自动签名信息

接口： getSignAutoInfo

查询当前用户的自动签授权信息。

调用示例

const result = await BJCASDK.signManager().getSignAutoInfo()

参数： 无。

返回结果

返回类型：Promise<YwxResult<AutoSignResult>>。

成功 data 为 AutoSignResult；未开通或未匹配授权为 003x043，data 为 null。

AutoSignResult 字段见对应返回说明。

关闭自动签名

接口： stopAutoSign

关闭指定业务系统的自动签授权。

调用示例

const result = await BJCASDK.signManager().stopAutoSign(systemTag)

返回结果

返回类型：Promise<YwxResult<AutoSignResult>>。

成功 data 为 null；关闭全部业务系统时传 undefined，否则传 systemTag。

AutoSignResult 字段见对应返回说明。

必做配置

1. .ohpmrc 按本页接入配置设置远端仓库。

2. 依赖更新为 @szyx/sdk_ywx: 2.0.1-alpha.24，执行 ohpm install --all。

3. 在窗口内容加载成功后调用 BJCASDK.initialize(uiContext)。

4. 将旧的 settingManager().init(...) 改为依次等待 configure(...) 和 setClientId(...)。

5. 返回值统一改为读取 YwxResult，通过 isSuccess() 判断成功。

const settings = BJCASDK.settingManager()
const configured = await settings.configure(EnvEnum.PUBLIC) // 医信客户使用 EnvEnum.SZYX
if (!configured.isSuccess()) return
const initialized = await settings.setClientId(clientId)
if (!initialized.isSuccess()) return

返回值必须修改

使用了以下旧接口时必须修改

下表中的方法分别通过 BJCASDK.settingManager()、BJCASDK.certManager()、BJCASDK.signManager() 调用。

旧类型与已移除接口

按需接入的新接口