专为 Expo React Native 项目设计的微信 SDK 封装库

📦 安装

使用 Expo CLI（推荐）

npx expo install expo-react-native-wechat-v2

使用 yarn

yarn add expo-react-native-wechat-v2

使用 npm

npm install expo-react-native-wechat-v2 --save

🚀 快速开始

1. 基础配置

Expo 项目配置

在项目根目录的 app.json 中添加配置：

{
  "expo": {
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["weixin", "weixinULAPI", "weixinURLParamsAPI"],
        "CFBundleURLTypes": [
          {
            "CFBundleTypeRole": "Editor",
            "CFBundleURLName": "weixin",
            "CFBundleURLSchemes": ["wx5555555555555555"]
          }
        ]
      }
    }
  }
}

执行预构建

• 生成./ios 和 ./android 项目文件夹

npx expo prebuild

2. 基础使用

import * as WeChat from 'expo-react-native-wechat-v2';

// 注册微信应用
// 项目中只需要全局注册一次， 多次注册可能会导致意想不到的问题发生；
await WeChat.registerApp('wx5555555555555555', 'https://your-domain.com/');

// 检查微信是否安装
const isInstalled = await WeChat.isWXAppInstalled();

// 分享文本
await WeChat.shareText({
  text: 'Hello from React Native!',
  scene: 0, // 0: 会话, 1: 朋友圈, 2: 收藏
});

⚙️ 配置指南

iOS Universal Links 配置

1. 苹果开发者后台配置

1. 登录 Apple Developer
2. 开启 Associated Domains 功能
3. 记录项目的 Team ID

2. 创建 apple-app-site-association 文件

{
   "applinks": {
       "apps": [],
       "details": [
           {
               "appID": "com.douyin.sample",
               "paths": [ "*" ]
           }
       ]
   }
}

重要注意事项：

3. Xcode 配置

在 Xcode 中设置 Associated Domains：

• Targets → Signing & Capabilities → Associated Domains
• 添加：applinks:your-domain.com

Expo 一键配置

1. 在项目根目录的 app.json 中添加配置：

{
    "expo": {
        "ios": {
          "infoPlist": {
            "LSApplicationQueriesSchemes": ["weixin", "weixinULAPI", "weixinURLParamsAPI"],
            "CFBundleURLTypes": [
              {
                "CFBundleTypeRole": "Editor",
                "CFBundleURLName": "wexin",
                "CFBundleURLSchemes": ["wx5555555555555555"]
              }
            ]
          }
        }
    }
}

2. 执行命令：

npx expo prebuild

React Native 手动配置

iOS 配置

1. URL Schemes 配置
   • Xcode → Targets → Info → URL Types
   • 添加微信 AppID：wx5555555555555555

或者在 Info.plist 文件中添加：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>wexin</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>wx5555555555555555</string>
        </array>
    </dict>
</array>

2. Queried URL Schemes 配置
   • 添加：weixin、weixinULAPI、weixinURLParamsAPI

或者在 Info.plist 文件中添加：

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>weixin</string>
    <string>weixinULAPI</string>
    <string>weixinURLParamsAPI</string>
</array>

Android 配置

Android 无需额外配置，库会自动处理。

📚 API 文档

本库支持 TypeScript，使用 Promise 或 async/await 来接收返回。

接口名称和参数尽量跟腾讯官网保持一致性，除了嵌套对象变成扁平对象，你可以直接查看腾讯文档来获得更多帮助。

基础功能

registerApp(appId, universalLink?) - 注册应用

返回值： Promise<Boolean>

import * as WeChat from 'expo-react-native-wechat-v2';

// 注册微信应用（全局调用一次）
await WeChat.registerApp('wx5555555555555555', 'https://your-domain.com/');

isWXAppInstalled() - 检查微信安装状态

返回值： Promise<Boolean>

const isInstalled = await WeChat.isWXAppInstalled();
console.log('微信是否已安装:', isInstalled);

isWXAppSupportApi() - 检查 API 支持

返回值： Promise<Boolean>

const isSupported = await WeChat.isWXAppSupportApi();
console.log('微信 API 是否支持:', isSupported);

getApiVersion() - 获取 SDK 版本

返回值： Promise<String>

const version = await WeChat.getApiVersion();
console.log('微信 SDK 版本:', version);

openWXApp() - 打开微信应用

返回值： Promise<Boolean>

await WeChat.openWXApp();

授权登录

sendAuthRequest(scope?, state?) - 微信授权登录

返回值： Promise<AuthResponse>

const authResult = await WeChat.sendAuthRequest(['snsapi_userinfo'], 'state123');
console.log('授权结果:', authResult);

分享功能

shareText(data) - 分享文本

await WeChat.shareText({
  text: '分享的文本内容',
  scene: 0,
});

shareImage(data) - 分享网络图片

await WeChat.shareImage({
  imageUrl: 'https://example.com/image.jpg',
  scene: 0,
});

shareLocalImage(data) - 分享本地图片

await WeChat.shareLocalImage({
  imageUrl: 'file:///path/to/local/image.jpg',
  scene: 0,
});

shareMusic(data) - 分享音乐

await WeChat.shareMusic({
  title: '音乐标题',
  description: '音乐描述',
  musicUrl: 'https://example.com/music.mp3',
  thumbImageUrl: 'https://example.com/thumb.jpg',
  scene: 0,
});

shareVideo(data) - 分享视频

await WeChat.shareVideo({
  title: '视频标题',
  description: '视频描述',
  videoUrl: 'https://example.com/video.mp4',
  thumbImageUrl: 'https://example.com/thumb.jpg',
  scene: 0,
});

shareWebpage(data) - 分享网页

await WeChat.shareWebpage({
  title: '网页标题',
  description: '网页描述',
  webpageUrl: 'https://example.com',
  thumbImageUrl: 'https://example.com/thumb.jpg',
  scene: 0,
});

shareMiniProgram(data) - 分享小程序

await WeChat.shareMiniProgram({
  title: '小程序标题',
  description: '小程序描述',
  userName: 'gh_d39d10000000',
  path: 'pages/index/index',
  webpageUrl: 'https://example.com/fallback.html',
  thumbImageUrl: 'https://example.com/thumb.jpg',
  scene: 0,
});

shareFile(data) - 分享文件

await WeChat.shareFile({
  url: 'file:///path/to/file.pdf',
  title: '文件标题',
  ext: 'pdf',
  scene: 0,
});

小程序功能

launchMiniProgram(data) - 跳转到小程序

await WeChat.launchMiniProgram({
  userName: 'gh_d39d10000000',
  miniProgramType: 0,
  path: 'pages/index/index?id=123',
});

subscribeMessage(data) - 订阅消息

await WeChat.subscribeMessage({
  scene: 0,
  templateId: 'template_id_here',
  reserved: 'reserved_data',
});

支付功能

pay(data) - 微信支付

await WeChat.pay({
  partnerId: 'partner_id',
  prepayId: 'prepay_id',
  nonceStr: 'nonce_str',
  timeStamp: 'timestamp',
  package: 'Sign=WXPay',
  sign: 'signature',
});

发票功能

chooseInvoice(data) - 选择发票

返回值： Promise<{errCode, errStr, cards: Invoice[]}>

const result = await WeChat.chooseInvoice({
  cardSign: 'card_sign',
  signType: 'SHA256',
  timeStamp: Date.now(),
  nonceStr: `${Date.now()}`,
});

console.log('发票数据:', result.cards);

🔄 事件处理

设置事件监听器

从小程序回到 APP，或者支付成功回到 APP 都会触发回调事件来返回相应信息，请在触发相应方法前提前添加事件队列。

import { DeviceEventEmitter } from 'react-native';

// 监听微信请求事件
DeviceEventEmitter.addListener('WeChat_Req', (req) => {
  console.log('微信请求事件:', req);
  if (req.type === 'LaunchFromWX.Req') {
    // 从小程序回到APP
    handleMiniProgramCallback(req.extMsg);
  }
});

// 监听微信响应事件
DeviceEventEmitter.addListener('WeChat_Resp', (resp) => {
  console.log('微信响应事件:', resp);
  if (resp.type === 'WXLaunchMiniProgramReq.Resp') {
    // 小程序跳转回调
    handleMiniProgramCallback(resp.extMsg);
  } else if (resp.type === 'SendMessageToWX.Resp') {
    // 分享消息回调
    handleShareCallback(resp);
  } else if (resp.type === 'PayReq.Resp') {
    // 支付回调
    handlePayCallback(resp);
  }
});

使用事件发射器

import * as WeChat from 'expo-react-native-wechat-v2';

// 添加事件监听器
WeChat.addListener('SendMessageToWX.Resp', (resp) => {
  console.log('分享结果:', resp);
});

// 一次性监听器
WeChat.once('PayReq.Resp', (resp) => {
  console.log('支付结果:', resp);
});

// 移除所有监听器
WeChat.removeAllListeners('SendMessageToWX.Resp');

🛠️ 错误处理

WechatError 类

所有 API 调用失败时会抛出 WechatError 异常：

import * as WeChat from 'expo-react-native-wechat-v2';

try {
  await WeChat.shareText({ text: 'Hello' });
} catch (error) {
  if (error instanceof WeChat.WechatError) {
    console.log('错误代码:', error.code);
    console.log('错误信息:', error.message);
  }
}

常见错误代码

📱 使用示例

基础调用示例

import { StatusBar } from 'expo-status-bar';
import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import * as WeChat from 'expo-react-native-wechat-v2';

export default function App() {
    return (
        <View style={styles.container}>
            <Text onPress={()=>{
                WeChat.registerApp('wx5555555555555555', 'https://www.baidu.com/').then((a)=>{
                    console.log("==registerApp==>",a);
                });
            }}>registerApp</Text>
            <Text onPress={()=>{
                WeChat.isWXAppInstalled().then((a)=>{
                    console.log("==isWXAppInstalled==>",a);
                });
            }}>isWXAppInstalled</Text>
            <Text onPress={()=>{
                WeChat.getApiVersion().then((a)=>{
                    console.log("==getApiVersion==>",a);
                });
            }}>getApiVersion</Text>
            <Text onPress={()=>{
                WeChat.openWXApp().then((a)=>{
                    console.log("==openWXApp==>",a);
                });
            }}>openWXApp</Text>
            <Text onPress={()=>{
                WeChat.shareText({
                    text: 'Text content.',
                    scene: 0,
                }).then((a)=>{
                    console.log("==shareText==>",a);
                });
            }}>shareText</Text>
            <StatusBar style="auto" />
        </View>
    );
}

const styles = StyleSheet.create({
    container: {
        flex: 1,
        backgroundColor: '#fff',
        alignItems: 'center',
        justifyContent: 'center',
    },
});

现代化应用示例

import React from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import * as WeChat from 'expo-react-native-wechat-v2';

export default function App() {
  const [isRegistered, setIsRegistered] = React.useState(false);

  React.useEffect(() => {
    // 注册微信应用
    WeChat.registerApp('wx5555555555555555', 'https://your-domain.com/')
      .then(() => setIsRegistered(true))
      .catch(console.error);
  }, []);

  const handleShareText = async () => {
    try {
      await WeChat.shareText({
        text: 'Hello from React Native!',
        scene: 0,
      });
      console.log('分享成功');
    } catch (error) {
      console.error('分享失败:', error);
    }
  };

  const handleWeChatLogin = async () => {
    try {
      const result = await WeChat.sendAuthRequest(['snsapi_userinfo']);
      console.log('登录成功:', result);
    } catch (error) {
      console.error('登录失败:', error);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>微信 SDK 示例</Text>
      
      <TouchableOpacity style={styles.button} onPress={handleShareText}>
        <Text style={styles.buttonText}>分享文本</Text>
      </TouchableOpacity>
      
      <TouchableOpacity style={styles.button} onPress={handleWeChatLogin}>
        <Text style={styles.buttonText}>微信登录</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 30,
  },
  button: {
    backgroundColor: '#07C160',
    padding: 15,
    borderRadius: 8,
    marginVertical: 10,
    width: 200,
    alignItems: 'center',
  },
  buttonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: 'bold',
  },
});

📋 注意事项

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

📞 支持

如有问题，请通过以下方式联系：

• 📧 邮箱: [email protected]
• 🐛 提交 Issue: GitHub Issues
• 📖 文档: 查看本文档的 API 文档 部分

Made with ❤️ by Zeeklog

Thanks zeng-zhiming