# ColorMapRun H5 交互 SDK 开发文档 (Bridge)
本文档描述了 H5 页面如何与彩图奔跑 App (Flutter) 进行交互。所有的交互方法都封装在 `bridge.js` 中。
## 1. 快速开始
### 1.1 文件引入
在您的 `index.html` 或项目入口文件中，引入 `bridge.js`。
```html
```
**注意**：本 SDK 内部会自动处理兼容性（优先检测 `uni.webView`，自动降级适配旧版 App URL 拦截），因此您**不需要**关心 App 是新版还是旧版，直接调用 API 即可。
### 1.2 本地调试 (Mock)
在开发阶段（浏览器环境），App 环境不可用。请在 `` 中引入 `mock_flutter.js` 来模拟 App 行为。
```html
```
**⚠️ 重要**：在打包交付给 App 端集成前，**请务必注释或删除对 `mock_flutter.js` 的引用**。
---
## 2. API 列表
所有的 API 都挂载在全局对象 `window.Bridge` 上。
### 2.1 基础导航
#### 返回上一页
通知 App 用户点击了返回按钮 (相当于浏览器的后退)。
```javascript
Bridge.back();
```
#### 返回 App 首页
强制关闭当前 Webview，返回 App 的原生首页。
```javascript
Bridge.toHome();
```
#### 跳转登录
当 API 返回 401 未授权时，调用此方法唤起 App 原生登录页。
```javascript
Bridge.toLogin();
```
#### 设置标题
修改 App 顶部导航栏的标题。
```javascript
Bridge.setTitle('我的页面标题');
```
### 2.2 业务跳转
#### 打开地图导航
调起 App 原生导航（支持高德、百度、腾讯地图）。
```javascript
/**
* @param {number} latitude 纬度
* @param {number} longitude 经度
* @param {string} name 地点名称
*/
Bridge.openMap(36.666, 117.123, '济南奥体中心');
```
#### 打开比赛详情 (原生页)
跳转到 App 内的原生比赛详情页。
```javascript
/**
* @param {string|number} id 活动ID (mcId)
* @param {string} type 活动类型 (默认 1)
*/
Bridge.openMatch(101, 1);
```
#### 打开活动列表 (原生页)
跳转到 App 内的原生多地图/活动列表页。
```javascript
/**
* @param {string|number} id 关联ID (mapId)
* @param {string} mapName 地图名称
*/
Bridge.openActivityList(202, '奥体公园定向');
```
### 2.3 功能调用
#### 微信分享
调起 App 的微信分享面板。
```javascript
Bridge.shareWx({
title: '快来参加彩图奔跑！',
url: 'https://colormaprun.com/activity/123',
image: 'https://colormaprun.com/logo.png',
scene: 'session' // session: 好友, timeline: 朋友圈
});
```
#### 跳转微信小程序
```javascript
Bridge.launchWxMini('gh_bea09156da8d', 'pages/index/index');
```
#### 保存图片
将 Base64 格式的图片保存到手机相册。
```javascript
Bridge.saveImage('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...');
```
### 2.4 获取数据
#### 获取用户 Token (异步)
**注意**: 通常 H5 页面加载时 URL 会携带 Token。此方法主要用于特殊情况下的主动获取。
```javascript
// 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 进行调试。