ColorMapRun H5 交互 SDK 开发文档 (Bridge)

本文档描述了 H5 页面如何与彩图奔跑 App (Flutter) 进行交互。所有的交互方法都封装在 bridge.js 中。

1. 快速开始

1.1 文件引入

在您的 index.html 或项目入口文件中，引入 bridge.js。

<!-- 引入通信桥梁 -->
<script src="./bridge.js"></script>

注意：本 SDK 内部会自动处理兼容性（优先检测 uni.webView，自动降级适配旧版 App URL 拦截），因此您不需要关心 App 是新版还是旧版，直接调用 API 即可。

1.2 本地调试 (Mock)

在开发阶段（浏览器环境），App 环境不可用。请在 <head> 中引入 mock_flutter.js 来模拟 App 行为。

<head>
    <!-- ... 其他标签 ... -->
    
    <!-- 【仅开发环境引入】 模拟 App 通信环境 -->
    <script src="./mock_flutter.js"></script>
    
    <script src="./bridge.js"></script>
</head>

⚠️ 重要：在打包交付给 App 端集成前，请务必注释或删除对 mock_flutter.js 的引用。

2. API 列表

所有的 API 都挂载在全局对象 window.Bridge 上。

2.1 基础导航

返回上一页

通知 App 用户点击了返回按钮 (相当于浏览器的后退)。

Bridge.back();

返回 App 首页

强制关闭当前 Webview，返回 App 的原生首页。

Bridge.toHome();

跳转登录

当 API 返回 401 未授权时，调用此方法唤起 App 原生登录页。

Bridge.toLogin();

设置标题

修改 App 顶部导航栏的标题。

Bridge.setTitle('我的页面标题');

2.2 业务跳转

打开地图导航

调起 App 原生导航（支持高德、百度、腾讯地图）。

/**
 * @param {number} latitude 纬度
 * @param {number} longitude 经度
 * @param {string} name 地点名称
 */
Bridge.openMap(36.666, 117.123, '济南奥体中心');

打开比赛详情 (原生页)

跳转到 App 内的原生比赛详情页。

/**
 * @param {string|number} id 活动ID (mcId)
 * @param {string} type 活动类型 (默认 1)
 */
Bridge.openMatch(101, 1);

打开活动列表 (原生页)

跳转到 App 内的原生多地图/活动列表页。

/**
 * @param {string|number} id 关联ID (mapId)
 * @param {string} mapName 地图名称
 */
Bridge.openActivityList(202, '奥体公园定向');

2.3 功能调用

微信分享

调起 App 的微信分享面板。

Bridge.shareWx({
    title: '快来参加彩图奔跑！',
    url: 'https://colormaprun.com/activity/123',
    image: 'https://colormaprun.com/logo.png',
    scene: 'session' // session: 好友, timeline: 朋友圈
});

跳转微信小程序

Bridge.launchWxMini('gh_bea09156da8d', 'pages/index/index');

保存图片

将 Base64 格式的图片保存到手机相册。

Bridge.saveImage('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...');

2.4 获取数据

获取用户 Token (异步)

注意: 通常 H5 页面加载时 URL 会携带 Token。此方法主要用于特殊情况下的主动获取。

// 1. 注册回调
Bridge.onToken(function(token) {
    console.log('收到 Token:', token);
    // 使用 Token 发起 API 请求...
});

// 2. 发起获取请求
Bridge.getToken();

3. 常见问题

Q: 为什么 Bridge.back() 没有反应？ A: 请检查是否在浏览器环境中。如果在浏览器中，确保引入了 mock_flutter.js。如果在 App 中，请确认 App 的 WebView 能够响应 javascript:history.back() 或 uni.postMessage。

Q: 怎么判断当前是在 App 内？ A: 推荐通过 UserAgent 判断，或者尝试调用 Bridge.getToken() 看是否有回调。但在使用本 SDK 时，建议假设处于 App 环境编写代码，并在本地开启 Mock 进行调试。

API.md 3.9 KB History Raw