在 UniApp 中使用阿里云验证码插件(aliyun-captcha
)需要完成微信小程序端的插件配置和项目内的组件使用两个主要步骤,以下是详细流程:
一、微信公众平台配置插件(必须)
-
获取插件 AppID
阿里云验证码插件的 AppID 通常为
wx4ef6e42c5e3d0
(建议确认最新官方信息)。 -
添加插件到小程序
- 登录 微信公众平台,进入你的小程序项目
- 左侧菜单:设置 → 第三方设置 → 插件管理 → 添加插件
- 输入 AppID 搜索插件,申请添加并等待审核通过(通常即时生效)
二、UniApp 项目配置
-
在
pages.json
中注册组件在需要使用验证码的页面配置中,添加微信小程序的插件引用:
json
{ "pages": [ { "path": "pages/login/login", // 你的页面路径 "style": { "mp-weixin": { // 仅微信小程序生效 "usingComponents": { "aliyun-captcha": "plugin://AliyunCaptcha/captcha" // 注册组件 } } } } ] }
-
配置插件版本(可选)
若需要指定插件版本,在项目根目录的
manifest.json
中添加:json
"mp-weixin": { "plugins": { "AliyunCaptcha": { // 插件名称(需与引用时一致) "version": "1.0.0", // 插件版本号 "provider": "wx4ef6e42c5e3d0" // 插件 AppID } } }
三、在页面中使用组件
-
基本用法(Vue 模板)
在页面的
.vue
文件中直接使用注册好的aliyun-captcha
组件:vue
<template> <view class="login-page"> <!-- 阿里云验证码组件 --> <aliyun-captcha ref="captcha" :scene="scene" :options="captchaOptions" @success="onCaptchaSuccess" @fail="onCaptchaFail" @close="onCaptchaClose" /> <!-- 触发验证码的按钮 --> <button @click="showCaptcha">获取验证码</button> </view> </template>
-
JS 逻辑处理
javascript
运行
<script> export default { data() { return { scene: "login", // 验证码场景(自定义,如登录/注册/支付) captchaOptions: { // 插件配置参数(需从阿里云控制台获取) appKey: "你的阿里云appKey", // 必传,阿里云验证码服务的appKey // 可选配置 lang: "zh-CN", // 语言(zh-CN/en) theme: "light" // 主题(light/dark) } }; }, methods: { // 显示验证码 showCaptcha() { // 调用组件的show方法显示验证码 this.$refs.captcha.show(); }, // 验证成功回调 onCaptchaSuccess(res) { console.log("验证成功", res); // res包含验证凭证(如token),需传给后端进行二次校验 const { validateToken } = res; this.submitForm(validateToken); // 提交表单时携带凭证 }, // 验证失败回调 onCaptchaFail(err) { console.error("验证失败", err); uni.showToast({ title: "验证失败,请重试", icon: "none" }); }, // 关闭验证码回调 onCaptchaClose() { console.log("验证码已关闭"); }, // 提交表单(示例) submitForm(validateToken) { // 调用后端接口时携带验证凭证 this.$api.login({ username: this.username, password: this.password, validateToken: validateToken // 验证码验证结果 }); } } }; </script>
四、关键说明
-
appKey
获取需在 阿里云验证码控制台 开通服务并创建应用,获取对应的
appKey
。 -
组件方法
show()
:显示验证码弹窗(需通过ref
调用)hide()
:手动隐藏验证码弹窗
-
回调参数
- 成功回调
res
包含validateToken
(验证凭证),需后端调用阿里云接口校验有效性 - 失败回调
err
包含错误信息(如用户取消、验证超时等)
- 成功回调
-
兼容性
该配置仅对微信小程序(
mp-weixin
)有效,其他端(如 H5、App)需使用对应平台的验证码方案。
通过以上步骤,即可在 UniApp 的微信小程序中集成并使用阿里云验证码插件,实现安全验证功能。