行为式验证码

2025.01.23 11:41:31

    全新人机验证方式,高效拦截机器行为,业务安全第一道防线。搭载风险感知引擎,智能切换验证难度,安全性高,极致用户体验。读屏软件深度适配,视障群体也可轻松使用,符合工信部无障碍适配要求

    兼容性

    条目 说明
    适配版本 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组件加载异常
    Online Chat Tel:95163223 Free trial