位置分享小程序 Android WebView 对接文档

1. 项目概述

1.1 项目简介

位置分享小程序是一个基于Vue 3开发的H5应用，提供实时位置定位、地图显示、POI搜索和位置分享功能。该应用可通过Android WebView集成，实现Android应用与H5应用的双向通信。 线上H5地址 (opens new window) 安卓DEMO下载 (opens new window) 安卓DEMO源码下载 (opens new window)

1.2 主要功能

• 实时定位：获取用户当前位置信息
• 地图显示：基于Mapbox GL JS的地图渲染
• POI搜索：支持关键词搜索和周边兴趣点查询
• 位置分享：生成位置卡片，包含详细地址信息和地图截图
• Android集成：支持Android WebView调用和回调

1.3 功能特性

• ✅ 支持安卓调用WebView方法传递经纬度和状态
• ✅ 自动根据状态显示不同页面（位置选择器/位置详情）
• ✅ 地图截图功能，自动截取地图中间区域
• ✅ 小卡片使用截图展示，提升视觉效果
• ✅ 优先使用安卓传入的经纬度数据
• ✅ 完整的错误处理和日志输出
• ✅ 异步处理，支持应用实例延迟初始化

1.4 技术栈

• 前端框架：Vue 3 + Composition API
• 构建工具：Vite
• 地图引擎：Mapbox GL JS
• Android集成：WebView JavaScript Bridge

2. Android WebView 集成接口

2.1 Android调用H5方法

2.1.1 接收位置数据和状态

方法名： window.receiveLocationData(lat, lng, status)

参数说明：

参数名	类型	必填	说明
lat	Number/String	是	纬度坐标
lng	Number/String	是	经度坐标
status	String	是	当前状态，可选值：send_location、view_my_location、view_other_location

状态说明：

• send_location：发送自己定位（显示位置选择器）
• view_my_location：查看自己发出定位（显示位置详情）
• view_other_location：查看他人发出定位（显示位置详情）

使用示例：

// Android端调用示例
webView.evaluateJavascript(
    "window.receiveLocationData(43.825592, 87.616848, 'send_location')",
    null
);

// 发送自己定位
window.receiveLocationData(47.352663, 87.831563, 'send_location');

// 查看自己发出定位
window.receiveLocationData(47.352663, 87.831563, 'view_my_location');

// 查看他人发出定位
window.receiveLocationData(47.352663, 87.831563, 'view_other_location');

2.2 H5调用Android方法

2.2.1 发送位置数据

当用户在H5中选择并发送位置时，会调用Android端提供的方法，传递位置数据。

回调数据格式：

{
  name: "位置名称",           // String，位置名称
  lat: 43.825592,           // Number，纬度
  lng: 87.616848,           // Number，经度
  address: "详细地址",       // String，详细地址
  full_address: "完整地址",  // String，完整地址
  province: "省份",          // String，省份
  city: "城市",              // String，城市
  county: "区县",            // String，区县
  kind: "位置类型",          // String，位置类型
  screenshot: "base64图片",  // String，地图截图（base64格式）【注意此截图没有定位图标，使用时需要在中心位置自行添加】
  timestamp: 1703123456789  // Number，时间戳（毫秒）
}

Android端接收示例：

public class WebViewActivity extends AppCompatActivity {
    private WebView webView;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_webview);
        
        webView = findViewById(R.id.webview);
        webView.getSettings().setJavaScriptEnabled(true);
        
        // 添加JavaScript接口
        webView.addJavascriptInterface(new WebAppInterface(), "tcAPI");
        
        // 加载H5页面
        webView.loadUrl("http://wuhan.gishub.com.cn:10000/case/xinjiangcard/");
        
        // 等待页面加载完成后设置回调
        webView.setWebViewClient(new WebViewClient() {
            @Override
            public void onPageFinished(WebView view, String url) {
                super.onPageFinished(view, url);
                // 设置回调方法名
                webView.evaluateJavascript(
                    "window.setAndroidCallback('onLocationSelected')", 
                    null
                );
            }
        });
    }
    
    // JavaScript接口类
    public class WebAppInterface {
        @JavascriptInterface
        public void onLocationSelected(String locationData) {
            // 解析JSON数据
            try {
                JSONObject data = new JSONObject(locationData);
                String name = data.getString("name");
                double lat = data.getDouble("lat");
                double lng = data.getDouble("lng");
                String address = data.getString("address");
                String fullAddress = data.getString("full_address");
                String province = data.getString("province");
                String city = data.getString("city");
                String county = data.getString("county");
                String kind = data.getString("kind");
                String screenshot = data.getString("screenshot");
                long timestamp = data.getLong("timestamp");
                
                // 处理位置数据
                Log.d("LocationData", "收到位置数据: " + locationData);
                
                // 在主线程中更新UI
                runOnUiThread(() -> {
                    // 处理位置数据，例如显示在界面上或保存到数据库
                    Toast.makeText(WebViewActivity.this, 
                        "收到位置: " + name, Toast.LENGTH_SHORT).show();
                });
            } catch (JSONException e) {
                Log.e("LocationData", "解析位置数据失败", e);
            }
        }
    }
}

3. 页面状态说明

3.1 页面显示逻辑

H5应用会根据Android传入的status参数自动显示对应页面：

状态值	显示页面	功能说明
send_location	LocationPicker	位置选择器，用户可选择或搜索位置
view_my_location	LocationDetail	位置详情页，显示我的位置信息
view_other_location	LocationDetail	位置详情页，显示他人位置信息

3.2 页面切换

• 当Android调用receiveLocationData时，H5会自动切换到对应页面
• 页面切换时会隐藏原有的聊天列表和底部按钮
• 用户可以通过页面内的关闭按钮返回主界面

4. 地图截图功能

4.1 截图时机

• 仅在发送位置时进行截图
• 查看位置详情时不截图
• 截图包含当前地图的中心区域

4.2 截图格式

• 格式：PNG
• 编码：Base64
• 质量：80%
• 尺寸：地图实际显示尺寸

4.3 截图显示

• 截图会在位置卡片中显示
• 截图中心会显示红色位置标记图标
• 如果没有截图，则显示实时地图

4.4 使用场景

• 发送位置时: 用户选择位置并点击发送时，自动截图并包含在发送数据中
• 小卡片展示: 使用截图替代地图组件，提升加载速度

5. 集成流程

5.1 初始化步骤

1. Android端加载H5页面
2. 设置回调方法：window.setAndroidCallback()
3. 等待H5页面加载完成

5.2 位置发送流程

1. Android调用：window.receiveLocationData(lat, lng, 'send_location')
2. H5显示位置选择器页面
3. 用户选择位置并点击发送
4. H5调用Android回调方法，传递位置数据（包含截图）
5. Android接收并处理位置数据

5.3 位置查看流程

1. Android调用：window.receiveLocationData(lat, lng, 'view_my_location'/'view_other_location')
2. H5显示位置详情页面
3. 用户查看位置信息
4. 用户可关闭详情页返回主界面

6. 完整示例代码

6.1 Android端调用示例

// 发送位置
webView.evaluateJavascript(
    "window.receiveLocationData(47.352663, 87.831563, 'send_location')", 
    null
);

// 设置回调方法名
webView.evaluateJavascript(
    "window.setAndroidCallback('onLocationSelected')", 
    null
);

6.2 JavaScript端处理示例

  
{
  name: "位置名称",
  lat: 47.352663,
  lng: 87.831563,
  address: "详细地址",
  full_address: "完整地址",
  province: "省份",
  city: "城市",
  county: "区县",
  kind: "位置类型",
  screenshot: "base64图片数据",
  timestamp: 1703123456789
}

7. 注意事项