Flutter UniApp Bridge API 文档

简介

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

安装

``bash
npm install @wlydfe/flutter-bridge
`

初始化

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

`typescript
import '@wlydfe/flutter-bridge';
`

或者通过 script 标签引入：

`html

`

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

基础类型

$3

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

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

API 列表

$3

从相册选择图片或拍照。

#### 参数

`typescript
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;
}
`

#### 示例

`typescript
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('选择图片操作完成');
}
});
`

---

$3

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

#### 参数

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

#### 示例

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

---

$3

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

#### 参数

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

#### 示例

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

---

$3

执行登录操作。

#### 参数

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

#### 示例

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

---

$3

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

#### 参数

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

#### 示例

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

---

$3

返回到上一个页面。

#### 参数

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

#### 示例

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

---

$3

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

#### shareType 说明

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

#### 示例

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


---

$3

设置标题

#### 参数

`typescript
interface NavigationBarTitleOptions {
title: string;
}
`

#### 示例

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

核心机制

$3

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

$3

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

使用方式

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

`typescript
// 引入库后，直接使用 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