更新记录

0.0.1（2026-04-07） 下载此版本

Version: 0.0.1

新增企微鉴权登录插件

平台兼容性

uni-app(4.07)

uni-app x(4.07)

插件API

uni-wecom-auth 插件对外提供 3 个API。下面逐一说明。

1.1 sendWecomAuth(options)

作用：发起企业微信 OAuth 授权。调用后会拉起企业微信 App，用户在企微中确认授权后，通过回调返回授权码 code。

引入方式：

// #ifdef APP-PLUS
import { sendWecomAuth } from '@/uni_modules/uni-wecom-auth'
// #endif

调用示例：

sendWecomAuth({
    corpId: 'xxxxxxxxxxxxxxxx',
    agentId: 'xxxxxxx',
    schema: 'wxxxxxxxxxxxxxxxxxxxxxxxxxx',
    success: function(res) {
        console.log('授权码:', res.code)
        console.log('state:', res.state)
    },
    fail: function(err) {
        console.log('错误码:', err.errCode)
        console.log('错误信息:', err.errMsg)
    },
    complete: function() {
        console.log('授权流程结束')
    }
})

参数 options 类型为 WecomLoginOptions，字段如下：

返回值：无（void）。结果通过 success / fail / complete 回调返回。

内部流程：

1. 校验 corpId 和 agentId 是否为空，为空则立即触发 fail + complete
2. 初始化企微原生 SDK（Android 使用 IWWAPI，iOS 使用 WWKApi）
3. 构造授权请求并拉起企业微信 App
4. 用户在企微中确认授权后，SDK 通过原生回调返回结果
5. 插件将原生回调结果封装为 WecomLoginResult 或 WecomLoginError，触发对应的 success 或 fail 回调
6. 最后触发 complete 回调

注意事项：

• corpId 和 agentId 不能为空字符串，否则直接触发 fail（errCode = 10004）
• 如果企业微信未安装，iOS 端会在 SDK 内部检测并触发 fail（errCode = 10001）；Android 端建议先调用 isWecomInstalled() 手动检查
• 调用此函数后，用户会离开当前 App 进入企业微信，页面的 onHide 会触发；用户返回后 onShow 会触发。关于时序处理，参见文档 3.6 节
• iOS 端必须在 App.vue 中配合 handleWecomOpenURL 使用，否则收不到 success 回调

1.2 isWecomInstalled()

作用：检查当前设备是否已安装企业微信 App。同步调用，立即返回结果。

引入方式：

// #ifdef APP-PLUS
import { isWecomInstalled } from '@/uni_modules/uni-wecom-auth'
// #endif

调用示例：

// #ifdef APP-PLUS
var result = isWecomInstalled()
console.log('企业微信已安装:', result.installed)

if (!result.installed) {
    uni.showModal({
        title: '提示',
        content: '请先安装企业微信 App',
        showCancel: false
    })
    return
}
// #endif

参数：无。

返回值类型为 IsWecomInstalledResult：

平台差异：

注意事项：

• 这是同步方法，不需要回调，直接使用返回值即可
• 建议在调用 sendWecomAuth() 之前先调用此方法检查，避免拉起授权后因企微未安装而报错
• 只检测是否安装，不检测企微是否已登录账号

1.3 handleWecomOpenURL(url)

作用：将企业微信回调的 URL 交给 SDK 解析，使 SDK 能触发授权结果回调。仅 iOS 需要调用此方法。

引入方式：

// #ifdef APP-PLUS
import { handleWecomOpenURL } from '@/uni_modules/uni-wecom-auth'
// #endif

调用示例：

在 App.vue 中拦截 URL Scheme 并传给插件：

handleSchemeUrl: function() {
    var args = plus.runtime.arguments
    if (!args) return

    // 企业微信回调 URL 以 wxwork 或 wwauth 开头
    if (args.indexOf('wxwork') === 0 || args.indexOf('wwauth') === 0) {
        var handled = handleWecomOpenURL(args)
        console.log('URL 处理结果:', handled)
        plus.runtime.arguments = ''
        return
    }
}

参数：

返回值：

平台差异：

注意事项：

• 只有 iOS 端需要调用此方法。如果遗漏，表现为：能拉起企微、用户也完成了授权，但前端收不到 success 回调
• 需要同时在 onLaunch 和 newintent 事件中调用，分别处理冷启动和热启动两种场景
• 处理完毕后应清空 plus.runtime.arguments，防止重复处理
• 虽然 Android 端调用此方法不会报错，但没有实际效果

1.4 错误码

插件定义了以下错误码，通过 fail 回调的 err.errCode 返回：

关于 errCode=5（Android）：如果 Android 端收到 errCode=5 且 errMsg 包含 no_priveleges，说明企微后台配置的应用签名与实际 APK 签名不匹配。Android 签名必须使用企微官方提供的签名工具 APK 生成，不能直接使用证书的 SHA1 指纹。

示例

以下是一个完整的登录页示例

<template>
  <view>
    <button :loading="loading" @click="handleWecomLogin">
      <text>企业微信登录</text>
    </button>
  </view>
</template>

<script>
  // #ifdef APP-PLUS
  import {
    sendWecomAuth,
    isWecomInstalled,
  } from "@/uni_modules/uni-wecom-auth";
  // #endif

  export default {
    data: function () {
      return {
        loading: false,
        pendingWecomAuth: false,
      };
    },

    onShow: function () {
      // #ifdef APP-PLUS
      if (this.pendingWecomAuth) {
        var self = this;
        // 延迟检查，给 SDK 回调足够时间先执行
        setTimeout(function () {
          if (self.pendingWecomAuth) {
            // SDK 回调未完成，自动重新发起授权
            self.pendingWecomAuth = false;
            self.handleWecomLogin();
          }
        }, 1500);
      }
      // #endif
    },

    methods: {
      handleWecomLogin: function () {
        this.loading = true;
        var self = this;

        // #ifdef APP-PLUS
        var checkResult = isWecomInstalled();
        if (!checkResult.installed) {
          self.loading = false;
          uni.showModal({
            title: "提示",
            content: "请先安装企业微信 App",
            showCancel: false,
          });
          return;
        }

        // 标记授权流程进行中
        self.pendingWecomAuth = true;

        sendWecomAuth({
          corpId: "你的企业 CorpID",
          agentId: "你的应用 AgentID",
          schema: "企业微信后台配置的 Schema 值",
          success: function (res) {
            // 授权成功，清除待授权标记
            self.pendingWecomAuth = false;
            self.loading = false;
            // 提交 code 给后端，完成登录...
          },
          fail: function (err) {
            self.loading = false;
            // 不清除 pendingWecomAuth，保持为 true
            // 让 onShow 检测到授权未完成并自动重试
          },
          complete: function () {
            self.loading = false;
            // 同样不在 complete 中清除 pendingWecomAuth
          },
        });
        // #endif
      },
    },
  };
</script>