行为式验证码
2025.03.31 01:50:56
全新人机验证方式，高效拦截机器行为，业务安全第一道防线。搭载风险感知引擎，智能切换验证难度，安全性高，极致用户体验。读屏软件深度适配，视障群体也可轻松使用，符合工信部无障碍适配要求
兼容性
| 条目 | 说明 |
|---|---|
| 适配版本 | HarmonyOS 12 及以上版本 |
资源引入
远程仓库依赖
验证码共享包 HAR 发布在 OpenHarmony 三方库中心仓，需要从 OpenHarmony 三方库中心仓引用
方式一
在Terminal窗口中，执行如下命令安装三方包，DevEco Studio 会自动在工程的 oh-package.json5 中自动添加三方包依赖
ohpm install @yidun/captcha
方式二
在工程的 oh-package.json5 中设置三方包依赖
"dependencies": {
"@yidun/captcha": "^1.0.4"
}
快速调用示例
@Component
export default struct Test {
private listener: CaptchaListener = {
onValidate: (result: string, validate: string, _msg: string, _captchaType:string, _errorValidate:string) => {
if (result === "true") {
AlertDialog.show(
{
title: "验证成功",
message: `校验码为：${validate}`,
alignment: DialogAlignment.Center
}
)
}
},
onError: (code: number, msg: string) => {
AlertDialog.show(
{
title: "验证码报错",
message: `错误code为${code} 错误信息为${msg}`,
alignment: DialogAlignment.Center
}
)
},
onCaptchaShow: () => {
},
onClose:(closeType:CloseType)=>{
}
}
showCaptcha() {
let configuration = new CaptchaConfiguration();
configuration.setCaptchaId("易盾验证码业务id");
configuration.setListener(this.listener);
Captcha.getInstance().init(this.getUIContext(), configuration);
Captcha.getInstance().showCaptcha();
}
build() {
Column() {
Text("易盾行为式验证码")
.fontSize("35fp")
.fontWeight(FontWeight.Bold)
Button("显示验证码")
.width("50%")
.height($r('app.float.default_48'))
.backgroundColor($r('app.color.blueColor'))
.type(ButtonType.Capsule)
.stateEffect(true)
.margin({
top: 64
})
.onClick(() => {
this.showCaptcha();
})
}
.width("100%")
.height("100%")
.justifyContent(FlexAlign.Center)
}
}
共享包方法说明
1. 验证码初始化
代码说明
Captcha.getInstance().init(this.getUIContext(), configuration)
初始化接收两个参数，第一个参数是Context上下文，第二个参数是 CaptchaConfiguration 类型的具体配置项。CaptchaConfiguration具体的可配置项如下
| 配置项 | 参数/类型 | 是否必须 | 默认值 | 描述 |
|---|---|---|---|---|
| setCaptchaId | captchaId:string | 是 | 无 | 业务id |
| setListener | listener:CaptchaListener | 是 | 无 | 回调监听 |
| setMobileTimeout | mobileTimeout:number | 否 | 10s | 超时时间，单位ms |
| setLangType | langType:LangType | 否 | 系统语言 | 语言类型：枚举值 |
| setTheme | theme:Theme | 否 | Theme.LIGHT | 主题：枚举值 |
| setDefaultFallback | defaultFallback:boolean | 否 | true | 是否采用默认降级 |
| setErrorFallBackCount | errorFallBackCount:number | 否 | 3 | 触发降级的最大错误次数，当超过这个错误次数时触发降级 |
| setHideCloseButton | hideCloseButton:boolean | 否 | false | 是否隐藏关闭按钮 |
| setProtocol | protocol:string | 否 | https | 资源加载协议: http 或 https |
| setIpv6 | ipv6:boolean | 否 | false | 网络是否ipv6 |
| setExtraData | extraData:string | 否 | 无 | 额外参数，在二次校验result返回/3.3.3版本加入 |
| setApiServer | apiServer:string | 否 | 无 | 私有化接口域名，私有化部署必须，协议需要和protocol对应 |
| setStaticServer | staticServer:string | 否 | 无 | 私有化资源域名，私有化部署必须，协议需要和protocol对应 |
| setShowInnerClose | showInnerClose:boolean | 否 | false | 是否显示验证码内部关闭按钮 |
| setRadius | radius:number | 否 | 0 | 验证码弹窗圆角弧度 |
| setRefreshInterval | refreshInterval:number | 否 | 300 | 错误提示时长/ms |
| setIsDebug | isDebug:boolean | 否 | false | 是否打开debug日志开关 |
| setAutoCancel | autoCancel:boolean | 否 | true | 点击遮罩层是否可以关闭验证码弹窗 |
| setMaskColor | maskColor:Color/number/string /Resource | 否 | 无 | 验证码弹窗遮罩层颜色 |
高级 ui 配置
| 配置项 | 参数/类型 | 是否必须 | 默认值 | 描述 |
|---|---|---|---|---|
| setUiParamsJson | uiParamsJson:string | 否 | 无 | 高级 ui json字符串 |
json 字段支持范围如下
{
"customStyles":{
"imagePanel":{
"align":"top", // 仅在 float 模式下有效，可选项为 top 和 bottom，指定 imagePanel 出现在 controlBar 上方还是下方
"borderRadius":"2px", // 边框圆角大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"loadBackgroundImage":"xxx", // 加载中时的背景图片地址，v2.21.4 后新增，需要填入一个 url
"loadBackgroundColor" :"#f00" // 加载中时的背景颜色，v2.21.4 后新增，支持 CSS 所有颜色值
},
"controlBar":{
"height": "40px", // 高度，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em，不支持 %，会影响功能
"borderRadius": "20px", // 边框圆角大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"paddingLeft": "40px", // 左边距，如果相对于整个 bar 居中提示文字，设为 0； v2.21.4 后新增，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、%，不支持 em，会影响功能
"borderColor": "transparent", // 边框颜色，支持 CSS 所有颜色值
"background": "#e1c1ff", // 背景颜色，占满整个 controlBar，支持 CSS 所有颜色值
"borderColorMoving": "#0000ff", // 滑动时已滑动区域边框、滑块颜色，仅在滑动类型验证码下有效，支持 CSS 所有颜色值
"backgroundMoving": "rgba(0, 0, 255, 0.1)", // 滑动时已滑动区域背景颜色，仅在滑动类型验证码下有效，支持 CSS 所有颜色值
"borderColorSuccess": "#00ff00", // 验证成功时边框、文字、滑块背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"backgroundSuccess": "rgba(0, 255, 0, 0.1)", // 验证成功时背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"borderColorError": "#ff0000", // 验证失败时边框、文字、滑块背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"backgroundError": "rgba(255, 0, 0, 0.1)", // 验证失败时背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"slideBackground": "#fff", // 滑块滑动前背景颜色，支持 CSS 所有颜色值
"textSize": "14px", // 滑块内文本大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem，不支持 em、%，会影响功能
"textColor": "orange", // 滑块内文本颜色（滑块滑动前、失败、成功前的颜色），支持 CSS 所有颜色值
"slideIcon": "", // 滑块滑动前 icon，需要是一个 url，如果未提供则按照默认icon显示
"slideIconMoving": "", // 滑块滑动过程 icon，需要一个 url，如果未提供则按照默认 icon 显示
"slideIconSuccess": "", // 滑块验证成功时 icon，需要一个 url，如果未提供则按照默认 icon 显示
"slideIconError": "" // 滑块验证失败时 icon，需要一个 url，如果未提供则按照默认 icon 显示
},
"icon": {
"intellisenseLogo": "" // 智能无感知的 icon，需要一个 url，如果未提供则按照默认 icon 显示
},
"gap": "30px", // imagePanel 相对 controlBar 的间距大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"executeBorderRadius": "4px", // imagePanel 右边顶部的操作按钮最外层容器圆角大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"executeBackground": "rgba(0, 0, 0, 0.2)", // imagePanel 右边顶部的操作按钮最外层容器背景颜色，支持 CSS 所有颜色值
"executeTop": "4px", // imagePanel 右边顶部的操作按钮最外层容器顶部距离，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"executeRight": "4px" // imagePanel 右边顶部的操作按钮最外层容器右侧距离，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
}，
"popupStyles":{
"capBarHeight": "50px", // 弹框头部标题所在容器高度，当传入数字时，默认单位 px；当传入字符串时，支持单位 px，v2.21.4 后支持 rem；不支持 %、em，会影响功能
"capBarTextAlign": "left", // 弹框头部标题文字对齐方式，可选值为 left、center、right
"capBarBorderColor": "#fff", // 弹框头部标题下边框颜色，想要去掉的话可取 transparent 或者与背景色同色，支持 CSS 所有颜色值
"capBarTextColor": "#333", // 弹框头部标题文字颜色，支持 CSS 所有颜色值
"capBarTextSize": 14, // 弹框头部标题文字字体大小，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、rem；不支持 %、em，会影响功能
"capBarTextWeight": 600, // 弹框头部标题文字字体体重，可设置粗细，也就是 css 样式的 font-weight 属性
"capPadding": 15, // 弹框 imagePanel 与外边框距离，相当于总体设置 capPaddingTop，capPaddingRight，capPaddingBottom，capPaddingLeft，当传入数字时，默认单位 px；当传入字符串时，支持单位 px；不支持 %、rem，em，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingTop": 0, // 弹框 imagePanel 与上外边框距离，会覆盖 capPadding 上边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingRight": 15, // 弹框 imagePanel 与右外边框距离，会覆盖 capPadding 右边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingBottom": 0, // 弹框 imagePanel 与下外边框距离，会覆盖 capPadding 下边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingLeft": 15, // 弹框 imagePanel 与左外边框距离，会覆盖 capPadding 左边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"opacity": 0.1, // 弹框遮罩层透明度,0 ~ 1 之间的数字
"radius": 20, // 弹框最外层容器圆角，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、%、rem，em
"borderColor": "transparent", // 弹框最外层容器边框颜色，想要去掉的话可取 transparent 或者与背景色同色，支持 CSS 所有颜色值
"paddingTop": 20, // 弹框最外层容器上内边距，实践时可与 capPaddingTop 配合，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、%、rem，em
"paddingBottom": 40, // 弹框最外层容器下内边距，实践时候可与 capPaddingBottom 配合，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、%、rem，em
"position": "absolute", // 弹框的 css 定位，可填 absolute、fixed、static 等，默认时 absolute
"top": "20%" // 弹框相对顶部的位置，也就是 css 样式的 top 属性
}，
"customTexts":{
"slideTip": "向右拖动滑块填充拼图" // 滑动模块文案
}
}
Theme 枚举类说明
// 主题
enum Theme {
// 正常
LIGHT,
// 暗黑
DARK
}
LangType 枚举值说明
enum LangType {
LANG_AM,// 阿姆哈拉语
LANG_AR,//阿拉伯语
LANG_AS,//阿萨姆语
LANG_AZ,//阿塞拜疆语
LANG_BE,//白俄罗斯语
LANG_BG,//保加利亚语
LANG_BN,//孟加拉语
LANG_BO,//藏语
LANG_BS,//波斯尼亚语
LANG_CA,//加泰罗尼亚语
LANG_CS,//捷克语
LANG_DA,//丹麦语
LANG_DE,//德语
LANG_EL,//希腊语
LANG_EN,//英文
LANG_EN_US,//英语/美国
LANG_ES,//西班牙语
LANG_ES_LA,//西班牙语/拉美
LANG_ET,//爱沙尼亚语
LANG_EU,//巴斯克语
LANG_FA,//波斯语
LANG_FI,//芬兰语
LANG_FR,//法语
LANG_GL,//加利西亚语
LANG_GU,//古吉拉特语
LANG_HI,//印地语
LANG_HR,//克罗地亚
LANG_HU,//匈牙利语
LANG_ID,//印尼语
LANG_IT,//意大利语
LANG_HE,//希伯来语
LANG_JA,//日文
LANG_JV,//爪哇语
LANG_KA,//格鲁吉亚语
LANG_KK,//哈萨克语
LANG_KM,//高棉语
LANG_KN,//卡纳达语
LANG_KO,//韩文
LANG_LO,//老挝语
LANG_LT,//立陶宛语
LANG_LV,//拉脱维亚语
LANG_MAI,//迈蒂利语
LANG_MI,//毛利语
LANG_MK,//马其顿语
LANG_ML,//马拉亚拉姆语
LANG_MN,//蒙古语
LANG_MR,//马拉地语
LANG_MS,//马来西亚语
LANG_MY,//缅甸语
LANG_NO,//挪威语
LANG_NE,//尼泊尔语
LANG_NL,//荷兰语
LANG_OR,//欧里亚语
LANG_PA,//旁遮普语
LANG_PL,//波兰语
LANG_PT,//葡萄牙语
LANG_PT_BR,//葡萄牙语/巴西
LANG_RO,//罗马西亚语
LANG_RU,//俄语
LANG_SI,//僧加罗语
LANG_SK,//斯洛伐克语
LANG_SL,//斯洛文尼亚语
LANG_SR,//塞尔维亚语
LANG_SV,//瑞典语
LANG_SW,//斯瓦希里语
LANG_TA,//泰米尔语
LANG_TE,//泰卢固语
LANG_TH,//泰语
LANG_FIL,//菲律宾语
LANG_TR,//土耳其语
LANG_UG,//维吾尔语
LANG_UK,//乌克兰语
LANG_UR,//乌尔都语
LANG_UZ,//乌兹别克语
LANG_VI,//越南语
LANG_ZH_CN,//中文简体
LANG_ZH_HK,//中国香港
LANG_ZH_TW,//中国台湾
}
CaptchaListener 接口说明
interface CaptchaListener {
/**
* 验证之后结果回调
* @param result 结果（true表示验证通过)
* @param validate 检验码
* @param msg 结果信息，包括验证错误信息
* @param captchaType 验证码类型
* @param errorValidate 异常校验码，用于排查不通过原因
*/
onValidate(result:string, validate:string, msg:string, captchaType: string, errorValidate:string):void;
/**
* 异常回调
* @param code 异常码
* @param msg 异常信息
*/
onError(code:number,msg:string):void;
/**
* 验证码弹窗显示回调
*/
onCaptchaShow():void;
/**
* 验证码弹窗关闭回调
* 共三种类型
* CloseType.USER_CLOSE(用户主动关闭)
* VERIFY_SUCCESS_CLOSE(流程结束自动关闭)
* VALIDATE_QUICK_CLOSE(两次showCaptcha时间间隔小于1s)
*/
onClose(closeType: CloseType):void;
}
2. 显示验证码弹窗
代码说明
Captcha.getInstance().showCaptcha()
3. 关闭验证码弹窗
代码说明
Captcha.getInstance().closeCaptcha()
错误码
| code | 含义 |
|---|---|
| 300 | 校验未通过，包含轨迹错误等 |
| 432 | 非法业务ID，包含业务到期等 |
| 501 | 请求失败，包括网络原因等 |
| 502 | 请求脚本资源失败 |
| 503 | 请求图片资源失败 |
| 505 | 请求音频资源失败 |
| 1000 | 未知错误 |
| 1004 | 初始化失败，接口超时 |
| 2000 | json解析异常 |
| -1001 | 网络未连接 |
| -1002 | 鸿蒙Web组件加载异常 |
