# TSGame JSBridge 接口文档 - 位置与媒体服务

**版本**: v1.9  
**更新时间**: 2025年7月13日  
**文档类型**: 接口规范文档 - 第三部分

## 文档说明

本文档是TSGame JSBridge接口规范文档的第三部分，专注于位置服务与媒体播放相关接口，包括GPS定位、音频播放控制等功能。

**适用平台**: Android / HarmonyOS  
**接口范围**: GPS定位服务、音频媒体播放

### 本文档包含的接口

| 接口名称 | 调用方向 | 主要功能 | 使用场景 |
|----------|----------|----------|----------|
| `startlocation` | WebView→App | 开始位置定位 | GPS定位服务 |
| `getlocationinfo` | WebView→App | 获取当前位置信息 | 位置信息查询 |
| `mediaTypeAudio` | WebView→App | 音频播放控制 | 音频媒体播放 |

---

## 1. 开始定位接口 (startlocation)

### 接口概述
当WebView需要开始GPS定位服务时，通过此接口启动位置定位功能。支持连续定位和单次定位两种模式，定位结果会通过`getlocationinfo`接口异步返回或自动回调到WebView。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant LocationClient as 位置服务
    participant AMapSDK as 高德地图SDK
    participant GPS as GPS/网络定位
    
    User->>WebView: 触发定位需求
    WebView->>App: 调用startlocation接口
    App->>App: 解析定位类型参数
    App->>LocationClient: 初始化AMapLocationClient
    LocationClient->>AMapSDK: 配置定位选项
    AMapSDK->>GPS: 启动定位服务
    
    alt 连续定位模式
        GPS->>AMapSDK: 持续返回位置信息
        AMapSDK->>LocationClient: 定位回调(每3秒)
        LocationClient->>App: onLocationChanged事件
        App->>WebView: 调用getlocationinfo传递位置
    else 单次定位模式
        GPS->>AMapSDK: 返回最高精度位置
        AMapSDK->>LocationClient: 单次定位回调
        LocationClient->>App: onLocationChanged事件
        App->>App: 保存位置信息供后续查询
    end
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('startlocation', locationType, function(response) {
    console.log('定位服务已启动');
});
```

#### 参数说明
| 参数 | 类型 | 必需 | 说明 | 取值 |
|------|------|------|------|------|
| locationType | string | ✓ | 定位类型 | "1"=连续定位, "2"或其他=单次定位 |

#### 定位类型说明
| 类型值 | 定位模式 | 说明 | 适用场景 |
|--------|----------|------|----------|
| "1" | 连续定位 | 每3秒更新一次位置信息 | 导航、实时跟踪 |
| "2" | 单次定位 | 获取一次最高精度位置 | 位置标记、签到 |
| 其他值 | 单次定位 | 默认为单次定位模式 | 通用位置获取 |

### 接口调用示例

#### 启动连续定位
```javascript
// 启动连续定位，适用于导航场景
function startContinuousLocation() {
    WebViewJavascriptBridge.callHandler('startlocation', '1', function(response) {
        console.log('连续定位已启动，每3秒更新一次位置');
        
        // 连续定位会自动调用getlocationinfo回调
        // 需要注册位置更新处理函数
        window.onLocationUpdate = function(locationData) {
            updateUserPosition(locationData);
        };
    });
}
```

#### 启动单次定位
```javascript
// 启动单次定位，适用于签到场景
function startOnceLocation() {
    WebViewJavascriptBridge.callHandler('startlocation', '2', function(response) {
        console.log('单次定位已启动，正在获取最精确位置');
        
        // 等待3秒后查询位置信息
        setTimeout(() => {
            getLocationInfo();
        }, 3000);
    });
}

// 获取定位结果
function getLocationInfo() {
    WebViewJavascriptBridge.callHandler('getlocationinfo', '', function(locationJson) {
        if (locationJson) {
            const location = JSON.parse(locationJson);
            console.log('定位成功:', location);
            showLocationOnMap(location);
        } else {
            console.log('定位失败或未完成');
        }
    });
}
```

#### 智能定位管理器
```javascript
// 定位管理器
const LocationManager = {
    isLocating: false,
    locationType: 'once', // 'once' 或 'continuous'
    locationTimer: null,
    
    // 开始定位
    startLocation(type = 'once') {
        if (this.isLocating) {
            console.log('定位服务已在运行中');
            return;
        }
        
        this.locationType = type;
        this.isLocating = true;
        
        const typeParam = type === 'continuous' ? '1' : '2';
        
        WebViewJavascriptBridge.callHandler('startlocation', typeParam, (response) => {
            console.log(`${type}定位已启动`);
            
            if (type === 'continuous') {
                this.startLocationMonitoring();
            } else {
                this.checkLocationResult();
            }
        });
    },
    
    // 停止定位
    stopLocation() {
        this.isLocating = false;
        
        if (this.locationTimer) {
            clearInterval(this.locationTimer);
            this.locationTimer = null;
        }
        
        console.log('定位服务已停止');
    },
    
    // 监控连续定位
    startLocationMonitoring() {
        // 每4秒检查一次位置更新（略大于定位间隔3秒）
        this.locationTimer = setInterval(() => {
            this.getCurrentLocation((location) => {
                if (location) {
                    this.onLocationUpdate(location);
                }
            });
        }, 4000);
    },
    
    // 检查单次定位结果
    checkLocationResult() {
        // 等待3秒让定位完成
        setTimeout(() => {
            this.getCurrentLocation((location) => {
                this.isLocating = false;
                
                if (location) {
                    this.onLocationReceived(location);
                } else {
                    this.onLocationError('定位失败');
                }
            });
        }, 3000);
    },
    
    // 获取当前位置
    getCurrentLocation(callback) {
        WebViewJavascriptBridge.callHandler('getlocationinfo', '', (locationJson) => {
            if (locationJson) {
                try {
                    const location = JSON.parse(locationJson);
                    callback(location);
                } catch (e) {
                    console.error('位置数据解析失败:', e);
                    callback(null);
                }
            } else {
                callback(null);
            }
        });
    },
    
    // 位置更新回调（连续定位）
    onLocationUpdate(location) {
        console.log('位置更新:', location);
        // 更新地图显示
        updateMapPosition(location);
        // 触发位置变化事件
        this.triggerLocationChange(location);
    },
    
    // 位置获取回调（单次定位）
    onLocationReceived(location) {
        console.log('定位完成:', location);
        // 显示位置信息
        showLocationDetails(location);
        // 执行签到等操作
        performLocationBasedAction(location);
    },
    
    // 定位错误处理
    onLocationError(error) {
        console.error('定位错误:', error);
        showMessage('定位失败，请检查位置权限和网络连接');
    },
    
    // 触发位置变化事件
    triggerLocationChange(location) {
        const event = new CustomEvent('locationChanged', {
            detail: location
        });
        window.dispatchEvent(event);
    }
};

// 使用示例
LocationManager.startLocation('continuous'); // 启动连续定位
// LocationManager.startLocation('once');    // 启动单次定位

// 监听位置变化
window.addEventListener('locationChanged', function(event) {
    const location = event.detail;
    console.log('位置已更新:', location.address);
});
```

### HarmonyOS实现要点
- **接口名称**: `startlocation`
- **调用方向**: WebView → App
- **参数格式**: 字符串类型的定位类型（"1"=连续定位, "2"=单次定位）
- **权限要求**: 需要精确位置权限和网络权限
- **SDK依赖**: 使用高德地图SDK (AMapLocationClient)
- **定位模式**: 高精度定位模式 (Hight_Accuracy)
- **连续定位**: 3秒间隔的连续位置更新
- **单次定位**: 3秒内最高精度的一次定位
- **回调机制**: 通过AMapLocationListener.onLocationChanged接收位置更新

---

## 2. 获取位置信息接口 (getlocationinfo)

### 接口概述
当WebView需要获取当前设备的位置信息时，通过此接口查询最近一次定位的结果。必须先调用`startlocation`接口启动定位服务，才能获取到有效的位置数据。

### 工作流程
```mermaid
sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant LocationCache as 位置缓存
    participant LocationData as 位置数据对象
    
    WebView->>App: 调用getlocationinfo接口
    App->>LocationCache: 检查缓存的位置信息
    
    alt 有位置数据
        LocationCache->>LocationData: 获取MaplocationInfo对象
        LocationData->>LocationData: 序列化为JSON
        LocationData->>App: 返回JSON字符串
        App->>WebView: 回调返回位置JSON
    else 无位置数据
        LocationCache->>App: 返回null
        App->>WebView: 回调返回null
    end
    
    WebView->>WebView: 解析位置JSON数据
    WebView->>WebView: 处理位置信息
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('getlocationinfo', '', function(locationJson) {
    if (locationJson) {
        const location = JSON.parse(locationJson);
        console.log('当前位置:', location);
    } else {
        console.log('暂无位置信息');
    }
});
```

#### 参数说明
| 参数 | 类型 | 必需 | 说明 | 取值 |
|------|------|------|------|------|
| data | string | ✓ | 固定传入空字符串 | "" |

#### 返回数据结构
| 字段 | 类型 | 说明 | 示例值 |
|------|------|------|-------|
| latitude | number | 纬度 | 39.908692 |
| longitude | number | 经度 | 116.397477 |
| address | string | 详细地址 | "北京市东城区正义路2号" |
| country | string | 国家 | "中国" |
| province | string | 省份 | "北京市" |
| city | string | 城市 | "北京市" |
| district | string | 城区 | "东城区" |
| street | string | 街道 | "正义路" |
| cityCode | string | 城市编码 | "010" |

### 接口调用示例

#### 基础位置获取
```javascript
// 获取当前位置信息
function getCurrentLocation() {
    WebViewJavascriptBridge.callHandler('getlocationinfo', '', function(locationJson) {
        if (locationJson) {
            try {
                const location = JSON.parse(locationJson);
                displayLocationInfo(location);
            } catch (e) {
                console.error('位置数据解析失败:', e);
            }
        } else {
            console.log('位置信息不可用，请先启动定位服务');
            startLocationFirst();
        }
    });
}

// 显示位置信息
function displayLocationInfo(location) {
    console.log('=== 当前位置信息 ===');
    console.log('纬度:', location.latitude);
    console.log('经度:', location.longitude); 
    console.log('地址:', location.address);
    console.log('城市:', location.city);
    console.log('区县:', location.district);
    
    // 更新页面显示
    updateLocationDisplay(location);
}

// 提示启动定位
function startLocationFirst() {
    if (confirm('需要先启动定位服务，是否立即启动？')) {
        WebViewJavascriptBridge.callHandler('startlocation', '2', function(response) {
            console.log('定位服务已启动，3秒后重新获取位置');
            setTimeout(getCurrentLocation, 3000);
        });
    }
}
```

#### 完整的位置服务流程
```javascript
// 位置服务管理器
const LocationService = {
    // 获取位置信息（带自动定位）
    getLocationWithAutoStart(callback) {
        // 先尝试获取已有的位置信息
        WebViewJavascriptBridge.callHandler('getlocationinfo', '', (locationJson) => {
            if (locationJson) {
                // 已有位置信息，直接返回
                try {
                    const location = JSON.parse(locationJson);
                    callback(null, location);
                } catch (e) {
                    callback('位置数据解析失败', null);
                }
            } else {
                // 没有位置信息，启动定位
                this.startLocationAndGet(callback);
            }
        });
    },
    
    // 启动定位并获取结果
    startLocationAndGet(callback) {
        console.log('正在启动定位服务...');
        
        WebViewJavascriptBridge.callHandler('startlocation', '2', (response) => {
            console.log('定位服务已启动，等待定位完成...');
            
            // 等待定位完成
            this.waitForLocation(callback, 0);
        });
    },
    
    // 等待定位完成
    waitForLocation(callback, attempts) {
        if (attempts >= 10) {
            callback('定位超时', null);
            return;
        }
        
        setTimeout(() => {
            WebViewJavascriptBridge.callHandler('getlocationinfo', '', (locationJson) => {
                if (locationJson) {
                    try {
                        const location = JSON.parse(locationJson);
                        callback(null, location);
                    } catch (e) {
                        callback('位置数据解析失败', null);
                    }
                } else {
                    // 继续等待
                    this.waitForLocation(callback, attempts + 1);
                }
            });
        }, 1000); // 每秒检查一次
    },
    
    // 验证位置数据完整性
    validateLocation(location) {
        const required = ['latitude', 'longitude'];
        const missing = required.filter(field => !location[field]);
        
        return {
            isValid: missing.length === 0,
            missing: missing,
            hasAddress: !!location.address
        };
    },
    
    // 格式化位置显示
    formatLocationDisplay(location) {
        const validation = this.validateLocation(location);
        
        if (!validation.isValid) {
            return '位置信息不完整';
        }
        
        // 构建显示文本
        let display = `${location.latitude.toFixed(6)}, ${location.longitude.toFixed(6)}`;
        
        if (validation.hasAddress) {
            display += `\n${location.address}`;
        }
        
        return display;
    }
};

// 使用示例
LocationService.getLocationWithAutoStart((error, location) => {
    if (error) {
        console.error('获取位置失败:', error);
        showMessage('定位失败: ' + error);
    } else {
        console.log('位置获取成功:', location);
        
        const validation = LocationService.validateLocation(location);
        if (validation.isValid) {
            const displayText = LocationService.formatLocationDisplay(location);
            showLocationInfo(displayText);
        } else {
            console.warn('位置数据不完整:', validation.missing);
        }
    }
});
```

### HarmonyOS实现要点
- **接口名称**: `getlocationinfo`
- **调用方向**: WebView → App
- **参数格式**: 空字符串
- **返回数据**: JSON字符串格式的位置信息对象
- **数据来源**: 由startlocation接口触发的定位结果
- **数据结构**: MaplocationInfo对象的JSON序列化
- **前置条件**: 需要先调用startlocation启动定位服务
- **数据字段**: 包含经纬度、地址、行政区划等完整位置信息
- **缓存机制**: App内存中保存最新一次定位结果

---

## 3. 音频播放接口 (mediaTypeAudio)

### 接口概述
当WebView需要播放音频文件时，通过此接口实现音频的播放控制。支持普通音频和历史音频两种类型，具有防重复播放机制，播放开始时会调用gameui_play_voice通知，播放完成后会自动通知WebView。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant MediaPlayer as 媒体播放器
    participant AudioSystem as 音频系统
    participant Server as 音频服务器
    
    User->>WebView: 触发音频播放
    WebView->>App: 调用mediaTypeAudio接口
    App->>App: 解析音频参数(audiourl/type/user)
    App->>App: 检查防重复播放标志
    
    alt 可以播放音频
        App->>App: 验证音频URL格式
        App->>Server: 下载音频文件(如果是网络URL)
        Server->>App: 返回音频数据
        App->>MediaPlayer: 初始化播放器
        App->>WebView: 调用gameui_play_voice通知播放开始
        MediaPlayer->>AudioSystem: 开始播放音频
        
        Note over MediaPlayer,AudioSystem: 播放过程中
        MediaPlayer->>App: 播放状态回调
        App->>App: 更新播放标志状态
        
        alt 播放完成
            MediaPlayer->>App: 播放完成回调
            App->>WebView: 调用gameui_stop_voice通知
            App->>App: 重置播放状态
        else 播放错误
            MediaPlayer->>App: 播放错误回调
            App->>App: 重置播放状态
            App->>WebView: 错误通知
        end
        
    else 正在播放中
        App->>App: 添加到延时播放队列
        Note over App: 200ms后重试播放
    end
```

### 参数规范

#### 调用格式
```javascript
const audioData = {
    audiourl: "https://example.com/audio.mp3",
    type: "1", 
    user: "user_123"
};

WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
    console.log('音频播放请求已发送');
});
```

#### 参数说明
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|------|------|------|------|--------|
| audiourl | string | ✓ | 音频文件URL地址 | "https://cdn.example.com/sound.mp3" |
| type | string | ✓ | 音频类型 | "1"=普通音频, "2"=历史音频 |
| user | string | ✓ | 用户标识或动画位置 | "user_123", "avatar_position_1" |

#### 音频类型说明
| 类型值 | 播放模式 | 说明 | 适用场景 |
|--------|----------|------|----------|
| "1" | 普通音频 | 新音频播放，支持防重复机制 | 音效、提示音 |
| "2" | 历史音频 | 历史音频重播，无防重复限制 | 聊天记录回放 |

### 接口调用示例

#### 播放游戏音效
```javascript
// 播放游戏胜利音效
function playVictorySound() {
    const audioData = {
        audiourl: "https://game.example.com/sounds/victory.mp3",
        type: "1",
        user: "game_effect_victory"
    };
    
    WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
        console.log('胜利音效播放中...');
    });
}

// 播放按钮点击音效
function playButtonClickSound() {
    const audioData = {
        audiourl: "https://game.example.com/sounds/button_click.mp3", 
        type: "1",
        user: "ui_button_click"
    };
    
    WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), function(response) {
        console.log('按钮音效播放中...');
    });
}
```

#### 完整的音频管理系统
```javascript
// 音频播放管理器
const AudioManager = {
    playingAudios: new Map(), // 正在播放的音频
    audioQueue: [], // 音频播放队列
    isProcessingQueue: false,
    
    // 播放音频
    playAudio(audioUrl, options = {}) {
        const audioData = {
            audiourl: audioUrl,
            type: options.type || "1",
            user: options.userId || this.generateUserId()
        };
        
        // 添加到播放队列
        this.addToQueue(audioData, options.callback);
        
        // 处理队列
        this.processQueue();
        
        return audioData.user;
    },
    
    // 生成唯一用户ID
    generateUserId() {
        return "audio_" + Date.now() + "_" + Math.random().toString(36).substr(2, 9);
    },
    
    // 添加到播放队列
    addToQueue(audioData, callback) {
        this.audioQueue.push({
            audioData: audioData,
            callback: callback,
            timestamp: Date.now()
        });
    },
    
    // 处理播放队列
    processQueue() {
        if (this.isProcessingQueue || this.audioQueue.length === 0) {
            return;
        }
        
        this.isProcessingQueue = true;
        
        const queueItem = this.audioQueue.shift();
        this.executePlayback(queueItem);
    },
    
    // 执行播放
    executePlayback(queueItem) {
        const { audioData, callback } = queueItem;
        
        // 记录播放状态
        this.playingAudios.set(audioData.user, {
            audioData: audioData,
            startTime: Date.now(),
            callback: callback
        });
        
        console.log('开始播放音频:', audioData.audiourl);
        
        WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData), (response) => {
            console.log('音频播放请求已发送:', audioData.user);
            
            if (callback) {
                callback(null, audioData.user);
            }
            
            // 继续处理下一个队列项
            setTimeout(() => {
                this.isProcessingQueue = false;
                this.processQueue();
            }, 200);
        });
    },
    
    // 处理播放开始
    onAudioStart(userId) {
        const playingInfo = this.playingAudios.get(userId);
        
        if (playingInfo) {
            console.log(`音频播放开始: ${userId}`);
            
            // 触发播放开始事件
            this.triggerAudioStartEvent(userId);
            
            // 调用回调
            if (playingInfo.callback) {
                playingInfo.callback(null, 'started');
            }
        } else {
            console.log(`收到播放开始通知，但未找到对应的音频记录: ${userId}`);
        }
    },
    
    // 处理播放完成
    onAudioComplete(userId) {
        const playingInfo = this.playingAudios.get(userId);
        
        if (playingInfo) {
            const duration = Date.now() - playingInfo.startTime;
            console.log(`音频播放完成: ${userId}, 耗时: ${duration}ms`);
            
            // 移除播放记录
            this.playingAudios.delete(userId);
            
            // 触发完成事件
            this.triggerAudioCompleteEvent(userId, duration);
            
            // 调用回调
            if (playingInfo.callback) {
                playingInfo.callback(null, 'completed');
            }
        }
    },
    
    // 触发音频开始事件
    triggerAudioStartEvent(userId) {
        const event = new CustomEvent('audioPlayStart', {
            detail: {
                userId: userId
            }
        });
        window.dispatchEvent(event);
    },
    
    // 触发音频完成事件
    triggerAudioCompleteEvent(userId, duration) {
        const event = new CustomEvent('audioPlayComplete', {
            detail: {
                userId: userId,
                duration: duration
            }
        });
        window.dispatchEvent(event);
    },
    
    // 停止所有音频
    stopAllAudio() {
        this.playingAudios.clear();
        this.audioQueue = [];
        this.isProcessingQueue = false;
        console.log('已停止所有音频播放');
    },
    
    // 获取播放状态
    getPlayingStatus() {
        return {
            playingCount: this.playingAudios.size,
            queueLength: this.audioQueue.length,
            isProcessing: this.isProcessingQueue
        };
    }
};

// 注册音频播放相关监听
if (typeof WebViewJavascriptBridge !== 'undefined') {
    // 注册音频播放开始通知
    WebViewJavascriptBridge.registerHandler('gameui_play_voice', function(userId) {
        console.log('收到音频播放开始通知:', userId);
        AudioManager.onAudioStart(userId);
    });
    
    // 注册音频播放完成通知
    WebViewJavascriptBridge.registerHandler('gameui_stop_voice', function(userId) {
        console.log('收到音频播放完成通知:', userId);
        AudioManager.onAudioComplete(userId);
    });
}

// 使用示例
const userId1 = AudioManager.playAudio('https://example.com/sound1.mp3', {
    type: '1',
    userId: 'background_music',
    callback: (error, result) => {
        if (error) {
            console.error('播放失败:', error);
        } else {
            console.log('播放结果:', result);
        }
    }
});

// 监听播放开始事件
window.addEventListener('audioPlayStart', function(event) {
    const { userId } = event.detail;
    console.log(`音频 ${userId} 开始播放`);
});

// 监听播放完成事件
window.addEventListener('audioPlayComplete', function(event) {
    const { userId, duration } = event.detail;
    console.log(`音频 ${userId} 播放完成，耗时 ${duration}ms`);
});
```

### HarmonyOS实现要点
- **接口名称**: `mediaTypeAudio`
- **调用方向**: WebView → App
- **参数格式**: JSON字符串，包含audiourl、type、user字段
- **音频支持**: 支持各种音频格式(MP3、WAV、AAC等)
- **防重复机制**: type为"1"时启用防重复播放检查
- **播放队列**: 正在播放时新音频延时200ms重试
- **开始通知**: 通过gameui_play_voice回调通知WebView播放开始
- **完成通知**: 通过gameui_stop_voice回调通知WebView播放完成
- **音量控制**: 受voicePlaying接口的全局音量开关影响
- **错误处理**: 包含URL验证、格式检查、播放状态管理

---

## 文档关联

本文档是TSGame JSBridge接口规范的第三部分，完整文档包括：

1. **用户认证与页面管理** - 登录、页面跳转、语音控制
2. **系统功能与交互** - 剪贴板、游戏状态、设备检测
3. **位置与媒体服务** (本文档) - GPS定位、音频播放

---

**文档维护**: TSGame开发团队  
**最后更新**: 2025年7月13日  
**版本**: v1.9  
**联系方式**: 技术支持组