Flutter UniApp Bridge API 文档

简介

@wlydfe/flutter-bridge 是一个用于 Flutter 和 UniApp 之间通信的桥接库，提供了丰富的原生能力调用接口。

安装

npm install @wlydfe/flutter-bridge

初始化

直接导入整个库，它会自动初始化并将 API 挂载到全局 uni 对象上：

import '@wlydfe/flutter-bridge';

或者通过 script 标签引入：

<script src="path/to/flutter-bridge.js"></script>

初始化后，所有 API 会挂载到全局 uni 对象上，可以直接通过 uni.xxx 的方式调用，无需 import。

基础类型

BaseOptions

所有 API 都支持的基础选项类型：

interface BaseOptions {
  success?: () => void;  // 成功回调
  fail?: () => void;     // 失败回调
  complete?: () => void; // 完成回调（无论成功或失败都会执行）
}

API 列表

1. chooseImage - 选择图片

从相册选择图片或拍照。

参数

interface ChooseImageOptions {
  count: number;                    // 最多可以选择的图片张数
  sizeType: ['original', 'compressed'];  // 图片尺寸类型
  sourceType: ['album', 'camera'];      // 图片来源类型
  success?: (result: {
    tempFilePaths: string[];         // 图片的本地文件路径列表
    tempFiles: {
      size: number;                  // 文件大小，单位 B
      type: string;                  // 文件类型
    }[];
  }) => void;
  fail?: () => void;
  complete?: () => void;
}

示例

uni.chooseImage({
  count: 1,
  sizeType: ['original', 'compressed'],
  sourceType: ['album', 'camera'],
  success: (result) => {
    console.log('选择的图片路径:', result.tempFilePaths);
    console.log('文件信息:', result.tempFiles);
  },
  fail: () => {
    console.error('选择图片失败');
  },
  complete: () => {
    console.log('选择图片操作完成');
  }
});

2. getLocation - 获取定位

获取当前的地理位置信息。

参数

interface GetLocationOptions {
  success?: (result: {
    latitude: number;   // 纬度，浮点数，范围为 -90~90
    longitude: number;  // 经度，浮点数，范围为 -180~180
  }) => void;
  fail?: () => void;
  complete?: () => void;
}

示例

uni.getLocation({
  success: (result) => {
    console.log('纬度:', result.latitude);
    console.log('经度:', result.longitude);
  },
  fail: () => {
    console.error('获取定位失败');
  },
  complete: () => {
    console.log('获取定位操作完成');
  }
});

3. previewImage - 预览图片

预览图片，支持多张图片滑动查看。

参数

interface PreviewImageOptions {
  urls: string[];      // 需要预览的图片链接列表
  success?: () => void;
  fail?: () => void;
  complete?: () => void;
}

示例

uni.previewImage({
  urls: [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg'
  ],
  success: () => {
    console.log('预览图片成功');
  },
  fail: () => {
    console.error('预览图片失败');
  }
});

4. login - 登录

执行登录操作。

参数

interface LoginOptions {
  success?: (result: {
    loginSuccess: boolean;  // 登录是否成功
    userId: string;         // 用户ID
  }) => void;
  fail?: () => void;
  complete?: () => void;
}

示例

uni.login({
  success: (result) => {
    if (result.loginSuccess) {
      console.log('登录成功，用户ID:', result.userId);
    }
  },
  fail: () => {
    console.error('登录失败');
  }
});

5. navigateTo - 导航到指定页面

跳转到应用内的某个页面。

参数

interface NavigateToOptions {
  route: string;        // 目标页面路由
  params: any;         // 页面参数
  success?: () => void;
  fail?: () => void;
  complete?: () => void;
}

示例

uni.navigateTo({
  route: '/pages/detail/index',
  params: {
    id: '123',
    title: '详情页'
  },
  success: () => {
    console.log('页面跳转成功');
  },
  fail: () => {
    console.error('页面跳转失败');
  }
});

6. navigateBack - 返回上一页

返回到上一个页面。

参数

interface BaseOptions {
  success?: () => void;
  fail?: () => void;
  complete?: () => void;
}

示例

uni.navigateBack({
  success: () => {
    console.log('返回成功');
  },
  fail: () => {
    console.error('返回失败');
  }
});

7. wxShare - 微信分享

这个方法只有flutter中可以使用 分享内容到微信。

参数

interface WxShareOptions {
  title: string;                              // 分享标题
  url: string;                                 // 分享链接
  shareType: ['appMessage', 'timeline', 'favorite'];  // 分享类型
  success?: () => void;
  fail?: () => void;
  complete?: () => void;
}

shareType 说明

• appMessage: 分享给微信好友
• timeline: 分享到微信朋友圈
• favorite: 收藏到微信

示例

uni.wxShare({
  title: '分享标题',
  url: 'https://example.com/share',
  shareType: ['appMessage', 'timeline'],
  success: () => {
    console.log('分享成功');
  },
  fail: () => {
    console.error('分享失败');
  }
});

8. setNavigationBarTitle - 设置标题

设置标题

参数

interface NavigationBarTitleOptions {
  title: string;
}

示例

uni.setNavigationBarTitle({
  title: '新标题',
  success: () => {
    console.log('返回成功');
  },
  fail: () => {
    console.error('返回失败');
  }
});

核心机制

桥接通信原理

1. 初始化: 调用 initBridgeCore() 初始化桥接核心，创建全局 AppBridge 对象
2. 调用流程:
   • H5 通过 invoke(type, data) 调用 Flutter 原生 API
   • 生成唯一的 callbackId 用于匹配回调
   • 通过 WLYDBridge.postMessage 发送消息到 Flutter
3. 回调处理:
   • Flutter 处理完成后调用全局 __onFlutterCallback 函数
   • 根据 callbackId 匹配对应的 Promise resolve/reject
   • 执行相应的成功或失败回调

错误处理

• 如果 Flutter 桥接未就绪（WLYDBridge 不存在），会返回 Promise.reject 并触发 fail 回调
• 所有 API 调用都支持 fail 和 complete 回调来处理错误情况

使用方式

所有 API 都通过全局 uni 对象调用，使用方式与 UniApp 官方 API 保持一致：

// 引入库后，直接使用 uni.xxx 调用
uni.chooseImage({ ... });
uni.getLocation({ ... });
uni.previewImage({ ... });
uni.login({ ... });
uni.navigateTo({ ... });
uni.navigateBack({ ... });
uni.wxShare({ ... });

注意事项

1. 初始化顺序: 确保在使用任何 API 之前先引入库（会自动初始化）
2. 环境要求: 需要在 Flutter WebView 环境中使用，依赖全局 WLYDBridge 对象
3. 回调处理: 所有 API 都是异步的，使用 Promise 和回调函数处理结果
4. 类型安全: 项目使用 TypeScript 编写，提供了完整的类型定义
5. 调用方式: 所有 API 都通过 uni.xxx 的方式调用，无需单独 import

版本信息

• 当前版本: 0.0.1
• 桥接协议版本: 1.0

许可证

MIT