# TSGame JSBridge 接口文档 - 高级功能与扩展

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

## 文档说明

本文档是TSGame JSBridge接口规范文档的第四部分，专注于高级功能与扩展相关接口，包括录音准备、设备震动控制、社交分享等功能。

**适用平台**: Android / HarmonyOS  
**接口范围**: 录音控制、震动反馈、社交分享

### 本文档包含的接口

| 接口名称 | 调用方向 | 主要功能 | 使用场景 |
|----------|----------|----------|----------|
| `prepareaudio` | WebView→App | 录音准备 | 语音录制准备 |
| `vibrator` | WebView→App | 单次震动 | 触觉反馈 |
| `repeatvibrator` | WebView→App | 重复震动 | 持续触觉反馈 |
| `canclevibrator` | WebView→App | 取消震动 | 停止震动反馈 |
| `friendsSharetypeUrlToptitleDescript` | WebView→App | 社交分享 | 微信/抖音分享 |

---

## 1. 录音准备接口 (prepareaudio)

### 接口概述
当WebView需要进行语音录制时，通过此接口初始化录音设备和准备录音环境。该接口会配置麦克风权限、创建录音文件、初始化MediaRecorder等录音前的准备工作。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant AudioManager as 录音管理器
    participant MediaRecorder as 媒体录制器
    participant FileSystem as 文件系统
    participant Microphone as 麦克风
    
    User->>WebView: 触发录音准备
    WebView->>App: 调用prepareaudio接口
    App->>App: 检查录音权限
    App->>App: 停止当前播放的音频
    
    alt 有权限且满足条件
        App->>AudioManager: 调用prepareAudio方法
        AudioManager->>FileSystem: 创建录音文件目录
        AudioManager->>FileSystem: 生成录音文件名
        AudioManager->>MediaRecorder: 初始化录制器
        MediaRecorder->>Microphone: 设置音频源为麦克风
        MediaRecorder->>MediaRecorder: 配置输出格式(AMR)
        MediaRecorder->>MediaRecorder: 设置音频编码器
        MediaRecorder->>MediaRecorder: 准备录制环境
        MediaRecorder->>AudioManager: 开始录制
        AudioManager->>App: 录音准备完成
        App->>WebView: 返回准备结果
    else 权限不足或条件不满足
        App->>WebView: 返回错误信息
    end
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('prepareaudio', '', function(response) {
    console.log('录音准备完成');
});
```

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

### 接口调用示例

#### 基础录音准备
```javascript
// 录音准备
function prepareRecording() {
    WebViewJavascriptBridge.callHandler('prepareaudio', '', function(response) {
        console.log('录音准备已完成');
        // 录音准备完成后可以开始录制
        showRecordingUI();
    });
}

// 显示录音界面
function showRecordingUI() {
    const recordButton = document.getElementById('recordButton');
    recordButton.textContent = '正在录音...';
    recordButton.classList.add('recording');
}
```

#### 录音状态管理器
```javascript
// 录音管理器
const RecordingManager = {
    isRecording: false,
    recordingStartTime: null,
    maxRecordingTime: 60000, // 最大录音时间60秒
    
    // 开始录音流程
    startRecording() {
        if (this.isRecording) {
            console.log('正在录音中，请先停止当前录音');
            return;
        }
        
        // 检查麦克风权限
        this.checkMicrophonePermission(() => {
            // 准备录音
            this.prepareRecording();
        });
    },
    
    // 检查麦克风权限
    checkMicrophonePermission(callback) {
        // 在实际应用中应该检查权限
        console.log('检查麦克风权限...');
        callback();
    },
    
    // 准备录音
    prepareRecording() {
        console.log('开始录音准备...');
        
        WebViewJavascriptBridge.callHandler('prepareaudio', '', (response) => {
            console.log('录音准备完成');
            this.isRecording = true;
            this.recordingStartTime = Date.now();
            
            // 更新UI
            this.updateRecordingUI(true);
            
            // 设置录音超时
            this.setRecordingTimeout();
        });
    },
    
    // 停止录音
    stopRecording() {
        if (!this.isRecording) {
            console.log('当前没有在录音');
            return;
        }
        
        this.isRecording = false;
        this.recordingStartTime = null;
        
        // 清除超时定时器
        if (this.recordingTimeout) {
            clearTimeout(this.recordingTimeout);
            this.recordingTimeout = null;
        }
        
        // 更新UI
        this.updateRecordingUI(false);
        
        console.log('录音已停止');
    },
    
    // 设置录音超时
    setRecordingTimeout() {
        this.recordingTimeout = setTimeout(() => {
            console.log('录音时间超过限制，自动停止');
            this.stopRecording();
            showMessage('录音时间过长，已自动停止');
        }, this.maxRecordingTime);
    },
    
    // 更新录音UI
    updateRecordingUI(isRecording) {
        const recordButton = document.getElementById('recordButton');
        const recordStatus = document.getElementById('recordStatus');
        
        if (isRecording) {
            recordButton.textContent = '停止录音';
            recordButton.classList.add('recording');
            recordStatus.textContent = '正在录音...';
            
            // 开始录音动画
            this.startRecordingAnimation();
        } else {
            recordButton.textContent = '开始录音';
            recordButton.classList.remove('recording');
            recordStatus.textContent = '录音已完成';
            
            // 停止录音动画
            this.stopRecordingAnimation();
        }
    },
    
    // 录音动画
    startRecordingAnimation() {
        const recordIndicator = document.getElementById('recordIndicator');
        if (recordIndicator) {
            recordIndicator.classList.add('pulse');
        }
    },
    
    stopRecordingAnimation() {
        const recordIndicator = document.getElementById('recordIndicator');
        if (recordIndicator) {
            recordIndicator.classList.remove('pulse');
        }
    },
    
    // 获取录音时长
    getRecordingDuration() {
        if (!this.isRecording || !this.recordingStartTime) {
            return 0;
        }
        
        return Date.now() - this.recordingStartTime;
    }
};

// 录音按钮事件
function handleRecordButtonClick() {
    if (RecordingManager.isRecording) {
        RecordingManager.stopRecording();
    } else {
        RecordingManager.startRecording();
    }
}
```

### HarmonyOS实现要点
- **接口名称**: `prepareaudio`
- **调用方向**: WebView → App
- **参数格式**: 空字符串
- **权限要求**: 需要RECORD_AUDIO权限
- **文件管理**: 创建录音文件目录和生成文件名
- **录制配置**: 音频源(麦克风)、输出格式(AMR)、编码器设置
- **状态管理**: 管理录音准备、开始、停止状态

---

## 2. 单次震动接口 (vibrator)

### 接口概述
当WebView需要提供触觉反馈时，通过此接口触发设备震动指定的时长。常用于按钮点击、操作确认、提醒通知等场景。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant VibratorUtil as 震动工具类
    participant SystemVibrator as 系统震动服务
    
    User->>WebView: 触发震动操作
    WebView->>App: 调用vibrator接口
    App->>App: 解析震动时长参数
    App->>VibratorUtil: 调用震动方法
    VibratorUtil->>SystemVibrator: 获取系统震动服务
    SystemVibrator->>SystemVibrator: 执行震动指定时长
    SystemVibrator->>VibratorUtil: 震动完成
    VibratorUtil->>App: 返回执行结果
    App->>WebView: 返回震动结果
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('vibrator', '500', function(response) {
    console.log('震动已执行');
});
```

#### 参数说明
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|------|------|------|------|--------|
| duration | string | ✓ | 震动时长(毫秒) | "500", "1000", "200" |

### 接口调用示例

#### 基础震动反馈
```javascript
// 按钮点击震动
function buttonClickVibrate() {
    WebViewJavascriptBridge.callHandler('vibrator', '100', function(response) {
        console.log('按钮点击震动完成');
    });
}

// 操作成功震动
function successVibrate() {
    WebViewJavascriptBridge.callHandler('vibrator', '200', function(response) {
        console.log('成功操作震动完成');
    });
}

// 错误提醒震动
function errorVibrate() {
    WebViewJavascriptBridge.callHandler('vibrator', '500', function(response) {
        console.log('错误提醒震动完成');
    });
}
```

#### 震动反馈管理器
```javascript
// 震动管理器
const VibrationManager = {
    // 震动模式配置
    vibrationModes: {
        light: '50',      // 轻微震动
        medium: '150',    // 中等震动
        strong: '300',    // 强烈震动
        long: '800'       // 长时间震动
    },
    
    // 用户震动设置
    isVibrationEnabled: true,
    
    // 执行震动
    vibrate(duration, callback) {
        if (!this.isVibrationEnabled) {
            console.log('用户已禁用震动');
            if (callback) callback('disabled');
            return;
        }
        
        // 验证震动时长
        const numDuration = parseInt(duration);
        if (isNaN(numDuration) || numDuration <= 0) {
            console.error('无效的震动时长:', duration);
            if (callback) callback('invalid_duration');
            return;
        }
        
        // 限制最大震动时长
        const maxDuration = 2000; // 最大2秒
        const safeDuration = Math.min(numDuration, maxDuration);
        
        WebViewJavascriptBridge.callHandler('vibrator', safeDuration.toString(), (response) => {
            console.log(`震动执行完成，时长: ${safeDuration}ms`);
            if (callback) callback(null, safeDuration);
        });
    },
    
    // 预设震动模式
    vibrateWithMode(mode, callback) {
        const duration = this.vibrationModes[mode];
        if (!duration) {
            console.error('未知的震动模式:', mode);
            if (callback) callback('unknown_mode');
            return;
        }
        
        this.vibrate(duration, callback);
    },
    
    // 按钮交互震动
    buttonFeedback() {
        this.vibrateWithMode('light');
    },
    
    // 操作成功震动
    successFeedback() {
        this.vibrateWithMode('medium');
    },
    
    // 错误反馈震动
    errorFeedback() {
        this.vibrateWithMode('strong');
    },
    
    // 警告震动
    warningFeedback() {
        this.vibrateWithMode('long');
    },
    
    // 设置震动开关
    setVibrationEnabled(enabled) {
        this.isVibrationEnabled = enabled;
        console.log('震动设置:', enabled ? '已启用' : '已禁用');
        
        // 保存到本地存储
        localStorage.setItem('vibration_enabled', enabled.toString());
    },
    
    // 从本地存储加载震动设置
    loadVibrationSettings() {
        const saved = localStorage.getItem('vibration_enabled');
        if (saved !== null) {
            this.isVibrationEnabled = saved === 'true';
        }
    }
};

// 页面加载时初始化
document.addEventListener('DOMContentLoaded', function() {
    VibrationManager.loadVibrationSettings();
});

// 使用示例
function setupButtonVibration() {
    // 为所有按钮添加震动反馈
    const buttons = document.querySelectorAll('button, .btn');
    buttons.forEach(button => {
        button.addEventListener('click', function() {
            VibrationManager.buttonFeedback();
        });
    });
}
```

### HarmonyOS实现要点
- **接口名称**: `vibrator`
- **调用方向**: WebView → App
- **参数格式**: 字符串类型的毫秒数
- **权限要求**: 需要VIBRATE权限
- **时长限制**: 建议限制最大震动时长避免过度震动
- **设备兼容**: 检查设备是否支持震动功能

---

## 3. 重复震动接口 (repeatvibrator)

### 接口概述
当需要持续或重复的震动反馈时，通过此接口设置重复震动模式。支持连续震动和停止重复震动的控制。

### 工作流程
```mermaid
sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant VibratorUtil as 震动工具类
    participant SystemVibrator as 系统震动服务
    
    WebView->>App: 调用repeatvibrator接口
    App->>App: 解析重复模式参数
    
    alt 启动重复震动 (repeat=1)
        App->>VibratorUtil: 启动重复震动
        VibratorUtil->>SystemVibrator: 设置震动模式
        SystemVibrator->>SystemVibrator: 开始重复震动
        loop 重复震动循环
            SystemVibrator->>SystemVibrator: 震动-停止-震动
        end
    else 停止重复震动 (repeat=-1)
        App->>VibratorUtil: 停止重复震动
        VibratorUtil->>SystemVibrator: 取消震动模式
        SystemVibrator->>SystemVibrator: 停止所有震动
    end
    
    App->>WebView: 返回操作结果
```

### 参数规范

#### 调用格式
```javascript
// 启动重复震动
WebViewJavascriptBridge.callHandler('repeatvibrator', '1', function(response) {
    console.log('重复震动已启动');
});

// 停止重复震动
WebViewJavascriptBridge.callHandler('repeatvibrator', '-1', function(response) {
    console.log('重复震动已停止');
});
```

#### 参数说明
| 参数 | 类型 | 必需 | 说明 | 取值 |
|------|------|------|------|------|
| repeat | string | ✓ | 重复震动模式 | "1"=启动重复震动, "-1"=停止重复震动 |

### 接口调用示例

#### 重复震动控制
```javascript
// 重复震动控制器
const RepeatVibrationController = {
    isRepeating: false,
    
    // 开始重复震动
    startRepeatVibration() {
        if (this.isRepeating) {
            console.log('重复震动已在运行中');
            return;
        }
        
        WebViewJavascriptBridge.callHandler('repeatvibrator', '1', (response) => {
            console.log('重复震动已启动');
            this.isRepeating = true;
            this.updateUI(true);
        });
    },
    
    // 停止重复震动
    stopRepeatVibration() {
        if (!this.isRepeating) {
            console.log('重复震动未运行');
            return;
        }
        
        WebViewJavascriptBridge.callHandler('repeatvibrator', '-1', (response) => {
            console.log('重复震动已停止');
            this.isRepeating = false;
            this.updateUI(false);
        });
    },
    
    // 切换重复震动状态
    toggleRepeatVibration() {
        if (this.isRepeating) {
            this.stopRepeatVibration();
        } else {
            this.startRepeatVibration();
        }
    },
    
    // 更新UI显示
    updateUI(isRepeating) {
        const toggleButton = document.getElementById('vibrationToggle');
        const statusText = document.getElementById('vibrationStatus');
        
        if (toggleButton) {
            toggleButton.textContent = isRepeating ? '停止震动' : '开始震动';
            toggleButton.classList.toggle('active', isRepeating);
        }
        
        if (statusText) {
            statusText.textContent = isRepeating ? '震动中...' : '震动已停止';
        }
    }
};
```

#### 游戏场景中的重复震动
```javascript
// 游戏震动管理器
const GameVibrationManager = {
    // 不同游戏状态的震动
    gameStates: {
        waiting: false,
        playing: false,
        warning: false
    },
    
    // 等待状态震动（心跳效果）
    startWaitingVibration() {
        if (this.gameStates.waiting) return;
        
        this.gameStates.waiting = true;
        RepeatVibrationController.startRepeatVibration();
        console.log('等待状态震动已启动');
    },
    
    // 停止等待震动
    stopWaitingVibration() {
        if (!this.gameStates.waiting) return;
        
        this.gameStates.waiting = false;
        RepeatVibrationController.stopRepeatVibration();
        console.log('等待状态震动已停止');
    },
    
    // 警告震动（危险提醒）
    startWarningVibration() {
        if (this.gameStates.warning) return;
        
        this.gameStates.warning = true;
        RepeatVibrationController.startRepeatVibration();
        console.log('警告震动已启动');
        
        // 10秒后自动停止
        setTimeout(() => {
            this.stopWarningVibration();
        }, 10000);
    },
    
    // 停止警告震动
    stopWarningVibration() {
        if (!this.gameStates.warning) return;
        
        this.gameStates.warning = false;
        RepeatVibrationController.stopRepeatVibration();
        console.log('警告震动已停止');
    },
    
    // 清理所有震动
    stopAllVibrations() {
        Object.keys(this.gameStates).forEach(state => {
            this.gameStates[state] = false;
        });
        RepeatVibrationController.stopRepeatVibration();
        console.log('所有游戏震动已清理');
    }
};
```

### HarmonyOS实现要点
- **接口名称**: `repeatvibrator`
- **调用方向**: WebView → App
- **参数格式**: 字符串类型的重复模式标识
- **震动模式**: 1=启动重复，-1=停止重复
- **资源管理**: 及时停止重复震动避免电量消耗
- **用户体验**: 提供用户控制震动开关的选项

---

## 4. 取消震动接口 (canclevibrator)

### 接口概述
当需要立即停止所有震动效果时，通过此接口取消当前正在执行的震动，包括单次震动和重复震动。

### 工作流程
```mermaid
sequenceDiagram
    participant WebView as WebView
    participant App as App
    participant VibratorUtil as 震动工具类
    participant SystemVibrator as 系统震动服务
    
    WebView->>App: 调用canclevibrator接口
    App->>VibratorUtil: 调用取消震动方法
    VibratorUtil->>SystemVibrator: 停止所有震动
    SystemVibrator->>SystemVibrator: 取消当前震动
    SystemVibrator->>SystemVibrator: 清理震动队列
    SystemVibrator->>VibratorUtil: 震动已取消
    VibratorUtil->>App: 返回取消结果
    App->>WebView: 返回操作确认
```

### 参数规范

#### 调用格式
```javascript
WebViewJavascriptBridge.callHandler('canclevibrator', '', function(response) {
    console.log('所有震动已取消');
});
```

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

### 接口调用示例

#### 震动紧急停止
```javascript
// 紧急停止所有震动
function emergencyStopVibration() {
    WebViewJavascriptBridge.callHandler('canclevibrator', '', function(response) {
        console.log('紧急停止震动完成');
        updateVibrationStatus('stopped');
    });
}

// 更新震动状态显示
function updateVibrationStatus(status) {
    const statusElement = document.getElementById('vibrationStatus');
    if (statusElement) {
        statusElement.textContent = status === 'stopped' ? '震动已停止' : '震动运行中';
    }
}
```

#### 综合震动管理系统
```javascript
// 震动系统管理器
const VibrationSystemManager = {
    activeVibrations: new Set(),
    
    // 注册震动
    registerVibration(vibrationId) {
        this.activeVibrations.add(vibrationId);
        console.log(`震动已注册: ${vibrationId}`);
    },
    
    // 注销震动
    unregisterVibration(vibrationId) {
        this.activeVibrations.delete(vibrationId);
        console.log(`震动已注销: ${vibrationId}`);
    },
    
    // 执行单次震动
    executeSingleVibration(duration, vibrationId = null) {
        const id = vibrationId || 'single_' + Date.now();
        this.registerVibration(id);
        
        WebViewJavascriptBridge.callHandler('vibrator', duration.toString(), (response) => {
            this.unregisterVibration(id);
            console.log(`单次震动完成: ${id}`);
        });
        
        return id;
    },
    
    // 开始重复震动
    startRepeatVibration(vibrationId = null) {
        const id = vibrationId || 'repeat_' + Date.now();
        this.registerVibration(id);
        
        WebViewJavascriptBridge.callHandler('repeatvibrator', '1', (response) => {
            console.log(`重复震动开始: ${id}`);
        });
        
        return id;
    },
    
    // 停止重复震动
    stopRepeatVibration(vibrationId) {
        if (vibrationId) {
            this.unregisterVibration(vibrationId);
        }
        
        WebViewJavascriptBridge.callHandler('repeatvibrator', '-1', (response) => {
            console.log('重复震动已停止');
        });
    },
    
    // 取消所有震动
    cancelAllVibrations() {
        console.log('正在取消所有震动...');
        
        WebViewJavascriptBridge.callHandler('canclevibrator', '', (response) => {
            // 清理所有注册的震动
            this.activeVibrations.clear();
            console.log('所有震动已取消');
            
            // 更新UI状态
            this.updateAllVibrationUI(false);
            
            // 触发震动停止事件
            this.triggerVibrationStoppedEvent();
        });
    },
    
    // 更新所有震动相关UI
    updateAllVibrationUI(isActive) {
        // 更新所有震动按钮状态
        const vibrationButtons = document.querySelectorAll('.vibration-btn');
        vibrationButtons.forEach(btn => {
            btn.classList.toggle('active', isActive);
            btn.disabled = false;
        });
        
        // 更新状态指示器
        const indicators = document.querySelectorAll('.vibration-indicator');
        indicators.forEach(indicator => {
            indicator.classList.toggle('active', isActive);
        });
    },
    
    // 触发震动停止事件
    triggerVibrationStoppedEvent() {
        const event = new CustomEvent('vibrationStopped', {
            detail: {
                timestamp: Date.now(),
                stoppedCount: this.activeVibrations.size
            }
        });
        window.dispatchEvent(event);
    },
    
    // 获取当前震动状态
    getVibrationStatus() {
        return {
            activeCount: this.activeVibrations.size,
            activeVibrations: Array.from(this.activeVibrations),
            hasActiveVibrations: this.activeVibrations.size > 0
        };
    }
};

// 监听震动停止事件
window.addEventListener('vibrationStopped', function(event) {
    console.log('震动停止事件:', event.detail);
    showMessage('所有震动已停止');
});

// 页面卸载时清理震动
window.addEventListener('beforeunload', function() {
    VibrationSystemManager.cancelAllVibrations();
});
```

### HarmonyOS实现要点
- **接口名称**: `canclevibrator`
- **调用方向**: WebView → App
- **参数格式**: 空字符串
- **清理范围**: 取消所有类型的震动（单次、重复）
- **即时生效**: 立即停止正在执行的震动
- **资源释放**: 清理震动相关的系统资源

---

## 5. 社交分享接口 (friendsSharetypeUrlToptitleDescript)

### 接口概述
当WebView需要分享内容到社交平台时，通过此接口实现微信好友、微信朋友圈、抖音等平台的内容分享功能。支持链接分享和自定义分享内容。

### 工作流程
```mermaid
sequenceDiagram
    participant User as 用户
    participant WebView as WebView
    participant App as App
    participant SharePanel as 分享面板
    participant WeChatSDK as 微信SDK
    participant Platform as 分享平台
    
    User->>WebView: 触发分享操作
    WebView->>App: 调用friendsSharetypeUrlToptitleDescript接口
    App->>App: 解析分享参数JSON
    App->>App: 检查分享类型(好友/朋友圈)
    
    alt 朋友圈分享 (sharefriend="2")
        App->>WeChatSDK: 直接调用微信分享
        WeChatSDK->>Platform: 打开微信朋友圈
        Platform->>User: 显示分享界面
        User->>Platform: 确认分享
        Platform->>WeChatSDK: 分享完成回调
        WeChatSDK->>App: 返回分享结果
    else 好友分享 (sharefriend="1")
        App->>SharePanel: 显示分享选择面板
        SharePanel->>User: 展示可用分享方式
        User->>SharePanel: 选择分享平台
        SharePanel->>WeChatSDK: 调用对应平台SDK
        WeChatSDK->>Platform: 执行分享操作
        Platform->>User: 完成分享流程
    end
    
    App->>WebView: 返回分享结果
```

### 参数规范

#### 调用格式
```javascript
const shareData = {
    sharefriend: "1",  // 1=好友分享, 2=朋友圈分享
    webpageUrl: "https://example.com/game",
    title: "游戏分享标题",
    description: "游戏分享描述",
    type: "1",
    sharetype: "1"
};

WebViewJavascriptBridge.callHandler('friendsSharetypeUrlToptitleDescript', JSON.stringify(shareData), function(response) {
    console.log('分享请求已发送');
});
```

#### 参数说明
| 参数 | 类型 | 必需 | 说明 | 示例值 |
|------|------|------|------|--------|
| sharefriend | string | ✓ | 分享类型 | "1"=好友分享, "2"=朋友圈分享 |
| webpageUrl | string | ✓ | 分享链接地址 | "https://game.example.com/share" |
| title | string | ✓ | 分享标题 | "精彩游戏邀请您体验" |
| description | string | ✓ | 分享描述 | "快来加入我们的游戏吧！" |
| type | string | ✗ | 分享内容类型 | "1"=链接分享, "3"=图片分享 |
| sharetype | string | ✗ | 分享方式类型 | "1"=普通分享, "3"=图片链接分享 |

#### 分享类型说明
| sharefriend值 | 分享目标 | 说明 | 用户体验 |
|---------------|----------|------|----------|
| "1" | 好友分享 | 显示分享选择面板 | 可选择多种分享方式 |
| "2" | 朋友圈分享 | 直接调用微信朋友圈 | 直接跳转到微信 |

### 接口调用示例

#### 游戏成就分享
```javascript
// 分享游戏成就到朋友圈
function shareAchievementToMoments(achievementData) {
    const shareData = {
        sharefriend: "2", // 朋友圈分享
        webpageUrl: `https://game.example.com/achievement/${achievementData.id}`,
        title: `我在游戏中获得了"${achievementData.title}"成就！`,
        description: `${achievementData.description} 快来挑战吧！`,
        type: "1",
        sharetype: "1"
    };
    
    WebViewJavascriptBridge.callHandler('friendsSharetypeUrlToptitleDescript', JSON.stringify(shareData), function(response) {
        console.log('成就分享到朋友圈已发送');
        trackShareEvent('achievement', 'moments');
    });
}

// 分享邀请给好友
function shareInviteToFriends(inviteCode) {
    const shareData = {
        sharefriend: "1", // 好友分享
        webpageUrl: `https://game.example.com/invite/${inviteCode}`,
        title: "游戏邀请",
        description: `我邀请你一起来玩游戏！邀请码：${inviteCode}`,
        type: "1",
        sharetype: "1"
    };
    
    WebViewJavascriptBridge.callHandler('friendsSharetypeUrlToptitleDescript', JSON.stringify(shareData), function(response) {
        console.log('邀请分享已发送');
        trackShareEvent('invite', 'friends');
    });
}
```

#### 完整的分享管理系统
```javascript
// 分享管理器
const ShareManager = {
    // 分享配置
    shareConfig: {
        baseUrl: 'https://game.example.com',
        defaultImage: 'https://game.example.com/images/share-default.jpg',
        appName: '精彩游戏'
    },
    
    // 分享模板
    shareTemplates: {
        achievement: {
            title: '我在{appName}中获得了"{achievementName}"成就！',
            description: '快来挑战这个{difficulty}难度的成就吧！'
        },
        invite: {
            title: '{appName}游戏邀请',
            description: '我邀请你一起来玩{appName}！使用邀请码{inviteCode}可以获得特殊奖励。'
        },
        score: {
            title: '我在{appName}中获得了{score}分！',
            description: '快来超越我的记录吧！'
        }
    },
    
    // 生成分享链接
    generateShareUrl(type, params = {}) {
        const baseUrl = this.shareConfig.baseUrl;
        const queryParams = new URLSearchParams({
            shareType: type,
            timestamp: Date.now(),
            ...params
        });
        
        return `${baseUrl}/share/${type}?${queryParams.toString()}`;
    },
    
    // 渲染分享模板
    renderTemplate(templateKey, data) {
        const template = this.shareTemplates[templateKey];
        if (!template) {
            console.error('未找到分享模板:', templateKey);
            return null;
        }
        
        const result = {
            title: this.replacePlaceholders(template.title, data),
            description: this.replacePlaceholders(template.description, data)
        };
        
        return result;
    },
    
    // 替换模板占位符
    replacePlaceholders(text, data) {
        return text.replace(/\{(\w+)\}/g, (match, key) => {
            return data[key] || match;
        });
    },
    
    // 执行分享
    share(shareType, targetType, shareData) {
        // 生成分享内容
        const content = this.renderTemplate(shareType, shareData);
        if (!content) {
            console.error('生成分享内容失败');
            return;
        }
        
        // 生成分享链接
        const shareUrl = this.generateShareUrl(shareType, shareData);
        
        // 构建分享参数
        const shareParams = {
            sharefriend: targetType, // "1"=好友, "2"=朋友圈
            webpageUrl: shareUrl,
            title: content.title,
            description: content.description,
            type: "1",
            sharetype: "1"
        };
        
        console.log('执行分享:', shareParams);
        
        WebViewJavascriptBridge.callHandler(
            'friendsSharetypeUrlToptitleDescript', 
            JSON.stringify(shareParams), 
            (response) => {
                console.log('分享执行完成');
                this.onShareComplete(shareType, targetType, shareData);
            }
        );
    },
    
    // 分享完成回调
    onShareComplete(shareType, targetType, shareData) {
        // 记录分享事件
        this.trackShare(shareType, targetType);
        
        // 显示分享完成提示
        this.showShareSuccessMessage(targetType);
        
        // 触发分享完成事件
        this.triggerShareEvent(shareType, targetType, shareData);
    },
    
    // 分享事件跟踪
    trackShare(shareType, targetType) {
        const eventData = {
            event: 'share',
            shareType: shareType,
            targetType: targetType === '1' ? 'friends' : 'moments',
            timestamp: Date.now()
        };
        
        console.log('分享事件跟踪:', eventData);
        // 这里可以调用分析SDK记录事件
    },
    
    // 显示分享成功消息
    showShareSuccessMessage(targetType) {
        const target = targetType === '1' ? '好友' : '朋友圈';
        showMessage(`分享到${target}成功！`);
    },
    
    // 触发分享事件
    triggerShareEvent(shareType, targetType, shareData) {
        const event = new CustomEvent('shareCompleted', {
            detail: {
                shareType: shareType,
                targetType: targetType,
                shareData: shareData,
                timestamp: Date.now()
            }
        });
        window.dispatchEvent(event);
    },
    
    // 快捷分享方法
    shareToFriends(shareType, shareData) {
        this.share(shareType, '1', shareData);
    },
    
    shareToMoments(shareType, shareData) {
        this.share(shareType, '2', shareData);
    }
};

// 使用示例
function shareGameAchievement(achievement) {
    const shareData = {
        appName: ShareManager.shareConfig.appName,
        achievementName: achievement.name,
        difficulty: achievement.difficulty,
        achievementId: achievement.id
    };
    
    // 分享到朋友圈
    ShareManager.shareToMoments('achievement', shareData);
}

function shareInvitation(inviteCode) {
    const shareData = {
        appName: ShareManager.shareConfig.appName,
        inviteCode: inviteCode
    };
    
    // 分享给好友
    ShareManager.shareToFriends('invite', shareData);
}

// 监听分享完成事件
window.addEventListener('shareCompleted', function(event) {
    console.log('分享完成事件:', event.detail);
});
```

### HarmonyOS实现要点
- **接口名称**: `friendsSharetypeUrlToptitleDescript`
- **调用方向**: WebView → App
- **参数格式**: JSON字符串，包含分享相关的所有参数
- **平台支持**: 微信好友、微信朋友圈、可扩展其他平台
- **SDK集成**: 需要集成微信SDK等第三方分享SDK
- **用户体验**: 根据分享类型提供不同的交互流程
- **错误处理**: 处理分享失败、用户取消等情况

---

## 文档关联

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

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

---

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