更新记录

1.0.0（2025-09-30）

支持iOS、安卓、鸿蒙平台 企业微信授权登录

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-wechat-work

🚀 企业SDK插件，为 uni-app x & uni-app 提供企业授权登录功能

📖 目录

• 环境配置
• 快速开始
• 功能介绍
  • 企业***授权登录
• 错误处理
• 常见问题

📚 推荐阅读: 企业***官方集成文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法

环境配置

前置条件

1. 在企业***开放平台申请企业应用
2. 获取 corpId（企业ID）和 agentId（应用ID）
3. 配置应用包名和签名

iOS平台配置

1. 配置 URL Scheme

修改插件目录下的 uni_modules/tt-wechat-work/utssdk/app-ios/Info.plist 文件：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>wechatwork</string>
        <key>CFBundleURLSchemes</key>
        <array>
           <!-- 填写您的scheme -->
          <string>你所注册的应用程序获得的scheme</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

💡 配置说明:

• 将 "你所注册的应用程序获得的scheme" 替换为您的实际企业***应用Scheme
• 此配置会自动合并到项目的Info.plist中

Android平台配置

Android平台会自动完成相关配置，确保在企业***开放平台正确配置应用包名和签名即可。

HarmonyOS平台配置

1. 配置 module.json5

⚠️ 重要提示: 由于 harmony-configs/entry/src/main/module.json5 会完全替换默认配置，需要提供完整的配置文件。

在项目的 harmony-configs/entry/src/main/module.json5 文件中使用以下完整配置：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "querySchemes": [
      "https",
      "wxworkapi"
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

💡 配置说明:

• 必须使用完整配置: module.json5 会覆盖默认配置，不能只添加部分字段
• 关键添加项:
  • querySchemes 数组包含 "https" 和 "wxworkapi"
• 保留默认配置: 其他配置项保持与默认模板一致

快速开始

1. 导入插件

import * as wxwork from "@/uni_modules/tt-wechat-work";

export default {
    data() {
        return {
            weChatWork: null as wxwork.TTWeChatWorkSDK | null,
        }
    },
    onLoad() {
        // 初始化企业***SDK实例
        this.weChatWork = wxwork.getTTWeChatWorkSDK()
        // 注册企业***SDK
        this.initWeChatWorkSDK()
    },
    methods: {
        // 初始化企业***SDK
        initWeChatWorkSDK() {
            // SDK初始化代码见下方
        }
    }
}

2. 初始化 SDK

initWeChatWorkSDK() {
    if (!this.weChatWork) {
        console.error('企业***SDK初始化失败')
        return
    }

    this.weChatWork.register({
        scheme: "您的应用Scheme",           // 必填：第三方App的Scheme
        corpId: "您的企业ID",              // 必填：企业***企业ID
        agentId: "您的应用ID",             // 必填：企业***企业应用ID
        success: (e) => {
            console.log("✅ 企业***SDK初始化成功");
            // 可以在这里进行后续操作，如检测企业***是否安装
            this.checkWeChatWorkInstalled()
        },
        fail: (err) => {
            console.error("❌ 企业***SDK初始化失败:", err);
            uni.showToast({
                title: '企业***SDK初始化失败',
                icon: 'error'
            })
        }
    } as wxwork.TTWeChatWorkRegisterOptions);
}

功能介绍

企业***授权登录

💡 企业***登录是一个两步过程：先获取code，再通过后端接口换取用户信息

第一步：获取授权码 (code)

参数说明

TTWeChatWorkLoginOptions

返回值 TTWeChatWorkLoginSuccess

示例代码

// 检测企业***是否安装
checkWeChatWorkInstalled() {
    const isInstalled = this.weChatWork?.isInstall()
    if (!isInstalled) {
        uni.showModal({
            title: '提示',
            content: '请先安装企业***客户端',
            showCancel: false
        })
        return false
    }
    return true
}

// 企业***授权登录
handleWeChatWorkLogin() {
    // 先检查企业***是否安装
    if (!this.checkWeChatWorkInstalled()) {
        return
    }

    this.weChatWork?.login({
        state: Date.now().toString(), // 使用时间戳作为唯一标识
        success: (result) => {
            console.log("✅ 获取授权码成功:", result.code);
            // 将code发送到后端服务器
            this.sendCodeToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ 企业***授权失败:", error);
            uni.showToast({
                title: '授权失败',
                icon: 'error'
            })
        }
    } as wxwork.TTWeChatWorkLoginOptions)
}

// 发送code到后端服务器
sendCodeToServer(code: string) {
    uni.request({
        url: 'https://your-server.com/api/wechatwork/login',
        method: 'POST',
        data: { code },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

第二步：后端换取用户信息

📖 详细流程请参考: 企业***授权后接口调用文档

后端需要完成的步骤：

1. 使用code换取access_token
2. 使用access_token获取用户信息
3. 返回用户信息给前端

错误处理

错误码说明

错误处理最佳实践

// 统一错误处理函数
handleWeChatWorkError(error: any, action: string) {
    console.error(`❌ ${action}失败:`, error)

    // 获取错误码和错误信息
    const errCode = error.errCode || error.code
    const errMsg = error.errMsg || error.message

    switch(errCode) {
        case 101:
            uni.showModal({
                title: '企业***未安装',
                content: '请先安装企业***客户端后再试',
                showCancel: false,
                confirmText: '知道了'
            })
            break

        case 102:
            uni.showModal({
                title: 'SDK初始化失败',
                content: '请检查企业***corpId和agentId配置是否正确',
                showCancel: false
            })
            break

        case 201:
            uni.showToast({
                title: '请先初始化SDK',
                icon: 'error'
            })
            break

        case 202:
            uni.showToast({
                title: '登录参数配置错误',
                icon: 'error'
            })
            break

        case 203:
            uni.showToast({
                title: 'URL Scheme配置错误',
                icon: 'error'
            })
            break

        case 204:
            // 用户取消登录，不显示错误提示
            console.log('用户取消登录')
            break

        case 999:
            // 其他错误，显示具体错误信息
            uni.showToast({
                title: errMsg || '操作失败',
                icon: 'error'
            })
            break

        case 1000:
            uni.showToast({
                title: '当前平台不支持此功能',
                icon: 'error'
            })
            break

        default:
            // 企业***SDK原始错误，可能是用户取消等
            if (errMsg && errMsg !== '用户取消') {
                uni.showToast({
                    title: errMsg,
                    icon: 'error'
                })
            }
            break
    }
}

// 使用示例
this.weChatWork?.login({
    state: Date.now().toString(),
    success: (result) => {
        console.log('登录成功:', result)
    },
    fail: (error) => {
        this.handleWeChatWorkError(error, '企业***登录')
    }
} as wxwork.TTWeChatWorkLoginOptions)

常见问题

1. 找不到插件方法？

解决方案: 确保使用自定义基座运行，标准基座不包含原生插件。

2. iOS平台登录无响应？

解决方案:

• 检查插件目录下 uni_modules/tt-wechat-work/utssdk/app-ios/Info.plist 中的 URL Scheme 配置
• 确认企业***应用Scheme配置正确
• 验证企业***开放平台的应用配置

3. Android平台功能异常？

解决方案:

• 确认应用签名与企业***开放平台配置一致
• 检查包名是否正确
• 确保企业***客户端版本支持相关功能

4. HarmonyOS平台问题？

常见问题:

• 配置不完整: 只添加了 querySchemes 导致应用无法正常运行
• 功能异常: SDK初始化失败

解决方案:

• 在正确路径 harmony-configs/entry/src/main/module.json5 创建配置文件
• 使用文档提供的完整 module.json5 模板配置
• 确认 querySchemes 数组包含 "https" 和 "wxworkapi"
• 检查所有默认配置项是否保留（abilities、permissions等）

5. 登录失败？

解决方案:

• 确保企业***客户端已安装
• 检查corpId和agentId是否正确
• 验证应用包名和签名配置
• 确认网络连接正常

📞 技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方常见问题
2. 参考企业***官方开发文档
3. 检查配置是否正确
4. 确认企业***客户端版本

祝您开发愉快！ 🎉