@wlydfe/flutter-bridge

Flutter App WebView 与 H5 的桥接库，让 H5 调用 App 原生能力（跳转、定位、扫码、存储等）。

接入文档

| 场景 | 文档 | |------|------| | 桥接核心机制（App + bridge） | docs/bridge-core.md | | uni-app H5（跑在 App 内） | docs/uni-app.md | | 纯 H5（Vue / React / Vanilla） | docs/h5.md |

安装

npm install @wlydfe/flutter-bridge

快速开始

uni-app

// 多端项目（H5 + 小程序等）强烈建议加条件编译，仅 H5 打入包
// #ifdef H5
import '@wlydfe/flutter-bridge'
// #endif

#ifdef H5 是否必须？

• 多端 uni-app（H5 + 小程序/App）：强烈建议加。bridge 只服务 H5 嵌 App，不加会把整包打进小程序，白白增大体积。
• 仅 H5 单端：可不加，但加上语义更清晰。
• 运行时：库内对 window 有判断，小程序里不加通常也不会因 window is not defined 崩溃，但无意义代码仍会参与打包。

还需配置 vite 插件，tsconfig 加 "@wlydfe/flutter-bridge/uni" 类型。

// H5 内跳转
uni.navigateTo({ url: '/subs/xxx/index' })
// App 原生页
uni.navigateTo({ nativeUrl: '/home' })
// 强制走原生
uni.getLocation({ useNative: true, success: () => {} })

纯 H5

import '@wlydfe/flutter-bridge'

// App 内默认走原生，无需 useNative
window.WLYDFlutterBridge?.navigateTo({ url: '/pages/detail' })
window.WLYDFlutterBridge?.native('handlerName', { id: 1 })

两种入口

| 入口 | 适用 | 说明 | |------|------|------| | uni.xxx | uni-app | 与官方 API 写法一致，参数区分 H5 / 原生 | | window.WLYDFlutterBridge | 纯 H5 | 勿与 Flutter 注入的 WLYDBridge 混淆 |

参数速查（uni-app）

| 参数 | 行为 | |------|------| | url / delta | H5 页面栈 | | nativeUrl / nativeDelta | App 原生跳转 / 返回 | | useNative: true | 强制走 App 原生能力 |

主要 API

导航： navigateTo redirectTo navigateBack switchTab openWebview

系统： getSystemInfoSync getLocation setNavigationBarTitle setNavigationBarVisible

交互： showToast hideToast showLoading hideLoading scanCode makePhoneCall openLocation

媒体： chooseImage previewImage

存储： setStorageSync getStorageSync removeStorageSync

扩展（仅 App）： login wxShare openFile navigateToMiniProgram

自定义： uni.native() / callNative(method, params) — 调用 Flutter registerBsHandler 注册的方法

生命周期： onShow onHide onResume onPause 等

详细参数见 TypeScript 类型定义（@wlydfe/flutter-bridge/uni 或主包 import）。

环境判断

uni.isInApp                        // uni-app
window.WLYDFlutterBridge?.isInApp  // 纯 H5

App 外仅暴露 isInApp、bridgeVersion；完整 API 仅在 App WebView 内可用。

开发

npm run build        # 构建 JS
npm run build:types  # 构建类型
npm test             # 自测

许可证

MIT