Hybrid App中JS通过JSBridge调用原生Android/iOS拨号

一、为什么通过 JSBridge 而不是简单的 href="tel:"

在传统移动端网页中，通常可以在超链接中使用 <a href="tel:10086">拨打电话</a>。然而在由容器托管的 Hybrid App 环境中，这种原始方式存在显著的不确定性：

• Android WebView 默认不响应：Android 原生 WebView 默认不会自动将 tel: 协议重定向到系统应用，除非在 WebViewClient.shouldOverrideUrlLoading 中显式进行 URL 协议匹配与 Intent 转换，否则点击可能没有任何视觉响应或触发未知加载错误。
• iOS WKWebView 弹窗不可控：在 iOS 环境下，直接打开 tel: 可能会触发系统默认的提示对话框，且该行为受系统版本演进而经常调整（如从早期的 telprompt: 到现代规范的 tel: 处理），开发者无法在前端代码中准确捕获用户是点击了“呼叫”还是“取消”。
• 缺乏生命周期与状态回调：H5 页面无法获知拨号意图是否成功派发、当前设备是否具备蜂窝通话模块（例如在 iPad 或纯 Wi-Fi 终端上），也无法进行埋点统计与统一的风控拦截。

通过标准 JSBridge 暴露专门的拨号方法，将逻辑收敛到宿主容器。前端仅负责传递目标号码及策略参数，原生层完成参数过滤、硬件检测与意图拉起，并向前端返回结构化的执行状态。

二、JSBridge 通信协议设计与前端 SDK 封装

在实现具体代码前，必须先确定跨端通信的数据契约。采用类似 JSON-RPC 的结构，明确方法名（action）、传参对象（params）及唯一回调标识（callbackId）。

1. 协议数据结构

// 前端 -> 客户端 报文结构
{
  "action": "contact.makePhoneCall",
  "callbackId": "call_1698800000000_1",
  "params": {
    "phoneNumber": "10086",
    "directDial": false // false 表示打开系统拨号盘；true 表示直接呼叫（需额外权限）
  }
}

// 客户端 -> 前端 回调报文结构
{
  "responseId": "call_1698800000000_1",
  "code": 0,           // 0 成功，-1 异常，-2 设备不支持，-3 权限被拒绝
  "message": "dialpad_opened",
  "data": {}
}

2. 前端通用 JS-SDK 封装

为了让业务方像调用普通异步函数一样使用拨号能力，前端可以通过 Promise 进行包装：

// bridge-dial.js
class NativeBridge {
  static callbackMap = new Map();

  static init() {
    // 挂载供原生层调用的全局回调接收点
    window.onNativeResponse = (responseString) => {
      try {
        const res = typeof responseString === 'string' 
          ? JSON.parse(responseString) 
          : responseString;
        const { responseId, code, message, data } = res;
        
        if (this.callbackMap.has(responseId)) {
          const { resolve, reject } = this.callbackMap.get(responseId);
          this.callbackMap.delete(responseId);
          if (code === 0) {
            resolve({ message, data });
          } else {
            reject(new Error(`[Bridge Error ${code}]: ${message}`));
          }
        }
      } catch (err) {
        console.error('解析原生回调失败', err);
      }
    };
  }

  /**
   * 拨打电话统一入口
   * @param {string} phoneNumber 电话号码
   * @param {boolean} directDial 是否尝试直接拨通（默认调起拨号盘）
   */
  static makePhoneCall(phoneNumber, directDial = false) {
    return new Promise((resolve, reject) => {
      if (!phoneNumber || typeof phoneNumber !== 'string') {
        return reject(new Error('Invalid phone number'));
      }

      // 清除首尾空格和非标准符号，但保留分机与通配符号如 +, *
      const cleanNumber = phoneNumber.trim().replace(/[^\d+*#]/g, '');
      const callbackId = `dial_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;

      // 注册超时，避免原生无响应导致前端 Promise 永久挂起
      const timer = setTimeout(() => {
        if (NativeBridge.callbackMap.has(callbackId)) {
          NativeBridge.callbackMap.delete(callbackId);
          reject(new Error('Call native timeout'));
        }
      }, 5000);

      NativeBridge.callbackMap.set(callbackId, {
        resolve: (val) => { clearTimeout(timer); resolve(val); },
        reject: (err) => { clearTimeout(timer); reject(err); }
      });

      const payload = JSON.stringify({
        action: 'contact.makePhoneCall',
        callbackId,
        params: { phoneNumber: cleanNumber, directDial }
      });

      // 跨平台消息发送
      if (window.AndroidBridge && typeof window.AndroidBridge.postMessage === 'function') {
        // Android WebView 注入接口
        window.AndroidBridge.postMessage(payload);
      } else if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.NativeBridge) {
        // iOS WKWebView MessageHandler 接口
        window.webkit.messageHandlers.NativeBridge.postMessage(JSON.parse(payload));
      } else {
        NativeBridge.callbackMap.delete(callbackId);
        clearTimeout(timer);
        reject(new Error('JSBridge is not available in current environment'));
      }
    });
  }
}

// 初始化
NativeBridge.init();

三、Android 端原生实现细节

在 Android 平台上，处理电话拨打存在两种截然不同的系统行为：Intent.ACTION_DIAL 与 Intent.ACTION_CALL。

1. ACTION_DIAL 与 ACTION_CALL 的本质差异

• Intent.ACTION_DIAL（强烈推荐）：该意图会将电话号码自动填充进系统拨号盘界面，但不会立即外呼，把最终呼叫确认权交给用户。该操作属于常规意图，不需要声明或动态申请 android.permission.CALL_PHONE 危险权限，在所有应用市场（含 Google Play 和国内主流商厦）均能顺利合规过审。
• Intent.ACTION_CALL（受限使用）：该意图绕过拨号界面直接对外呼出。这属于严重影响用户资费和隐私的高危操作，必须在 AndroidManifest.xml 静态声明并在运行时向用户弹窗索取危险权限。除非特定呼叫中心或无障碍辅助类 App，常规商业 App 申请该权限极易被拒审。

2. Android 原生代码实现（Java / Kotlin 兼容思路）

package com.example.hybrid.bridge;

import android.app.Activity;
import android.content.Context;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.net.Uri;
import android.webkit.JavascriptInterface;
import android.webkit.WebView;
import org.json.JSONObject;

public class DialBridgeModule {
    private final Activity activity;
    private final WebView webView;

    public DialBridgeModule(Activity activity, WebView webView) {
        this.activity = activity;
        this.webView = webView;
    }

    @JavascriptInterface
    public void postMessage(String jsonString) {
        try {
            JSONObject json = new JSONObject(jsonString);
            String action = json.optString("action");
            String callbackId = json.optString("callbackId");
            JSONObject params = json.optJSONObject("params");

            if ("contact.makePhoneCall".equals(action)) {
                String phoneNumber = params != null ? params.optString("phoneNumber") : "";
                handleMakePhoneCall(phoneNumber, callbackId);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private void handleMakePhoneCall(final String phoneNumber, final String callbackId) {
        activity.runOnUiThread(() -> {
            if (phoneNumber == null || phoneNumber.trim().isEmpty()) {
                sendCallback(callbackId, -1, "Phone number is empty");
                return;
            }

            // 特殊符号如 # 必须通过 Uri.encode 转义，否则会被截断为 URL fragment
            String uriString = "tel:" + Uri.encode(phoneNumber.trim());
            Intent intent = new Intent(Intent.ACTION_DIAL, Uri.parse(uriString));

            // 检测系统是否具备处理拨号 Intent 的 Activity（例如纯 Wi-Fi 平板可能没有电话功能）
            PackageManager pm = activity.getPackageManager();
            if (intent.resolveActivity(pm) == null) {
                sendCallback(callbackId, -2, "No telephony application available on this device");
                return;
            }

            try {
                activity.startActivity(intent);
                sendCallback(callbackId, 0, "Dialpad opened successfully");
            } catch (Exception e) {
                sendCallback(callbackId, -1, "Failed to start dialer: " + e.getMessage());
            }
        });
    }

    private void sendCallback(String callbackId, int code, String message) {
        activity.runOnUiThread(() -> {
            try {
                JSONObject res = new JSONObject();
                res.put("responseId", callbackId);
                res.put("code", code);
                res.put("message", message);
                
                String jsScript = String.format("window.onNativeResponse && window.onNativeResponse(%s);", res.toString());
                webView.evaluateJavascript(jsScript, null);
            } catch (Exception e) {
                e.printStackTrace();
            }
        });
    }
}

四、iOS 端原生实现细节

在 iOS 环境下，推荐使用现代的 WKWebView 及其配套的 WKScriptMessageHandler 机制，避免使用早已废弃的 UIWebView 或拦截 shouldStartLoadWithRequest 自定义 URL Scheme 的老旧手段。

1. URL Scheme 与系统拨号机制

iOS 系统支持 tel: 协议。调用 UIApplication.shared.open 时，iOS 内部会自动弹出包含目标号码的呼叫确认框（包含“呼叫”与“取消”按钮）。在 iOS 10 之前曾有私有的 telprompt: 协议，但由于其属于非官方公开接口，在上架审核中存在被拒风险；现代 iOS 应用应统一采用标准的 tel: 协议，系统会全自动处理合规提示。

2. iOS 原生代码实现（Swift）

import UIKit
import WebKit

class DialScriptMessageHandler: NSObject, WKScriptMessageHandler {
    weak var viewController: UIViewController?
    weak var webView: WKWebView?

    init(viewController: UIViewController, webView: WKWebView) {
        self.viewController = viewController
        self.webView = webView
        super.init()
    }

    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        guard message.name == "NativeBridge",
              let body = message.body as? [String: Any],
              let action = body["action"] as? String,
              let callbackId = body["callbackId"] as? String else {
            return
        }

        if action == "contact.makePhoneCall" {
            let params = body["params"] as? [String: Any]
            let phoneNumber = params?["phoneNumber"] as? String ?? ""
            handleMakePhoneCall(phoneNumber: phoneNumber, callbackId: callbackId)
        }
    }

    private func handleMakePhoneCall(phoneNumber: String, callbackId: String) {
        let trimmedNumber = phoneNumber.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmedNumber.isEmpty else {
            sendCallback(callbackId: callbackId, code: -1, message: "Phone number is empty")
            return
        }

        // 字符转义处理，防止特殊符号失效
        guard let escapedNumber = trimmedNumber.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed),
              let url = URL(string: "tel:\(escapedNumber)") else {
            sendCallback(callbackId: callbackId, code: -1, message: "Invalid URL format")
            return
        }

        // 检查系统能否打开 tel: 协议（例如 iPad、iPod Touch 或无通话功能设备）
        guard UIApplication.shared.canOpenURL(url) else {
            sendCallback(callbackId: callbackId, code: -2, message: "Device does not support telephone calls")
            return
        }

        DispatchQueue.main.async {
            UIApplication.shared.open(url, options: [:]) { [weak self] success in
                if success {
                    self?.sendCallback(callbackId: callbackId, code: 0, message: "Dialer opened")
                } else {
                    self?.sendCallback(callbackId: callbackId, code: -1, message: "Failed to open tel url")
                }
            }
        }
    }

    private func sendCallback(callbackId: String, code: Int, message: String) {
        DispatchQueue.main.async { [weak self] in
            let resPayload: [String: Any] = [
                "responseId": callbackId,
                "code": code,
                "message": message
            ]

            guard let jsonData = try? JSONSerialization.data(withJSONObject: resPayload, options: []),
                  let jsonString = String(data: jsonData, encoding: .utf8) else {
                return
            }

            let js = "window.onNativeResponse && window.onNativeResponse(\(jsonString));"
            self?.webView?.evaluateJavaScript(js, completionHandler: nil)
        }
    }
}

五、生产环境核心避坑与合规清单

为了确保线上生产环境的稳定运行，需重点排查以下四项设计细节：

1. 号码清洗与 URI 字符编码： 前端可能传入带有空格、短横线（如 021-1234 5678）的展示型字符串。调用前需过滤掉无关排版字符。原生层在拼接 tel: 时，必须使用 Uri.encode()（Android）或 addingPercentEncoding()（iOS）对特殊符号 *、#、, 进行编码。
2. 非通话设备防御性拦截： iPad、Android 平板、车机或开发模拟器通常未装配调制解调器（Modem）或通话应用。在派发 Intent 前，务必通过 intent.resolveActivity(pm) 或 canOpenURL() 检查系统响应能力；若检测失败，应返回明确的错误码（如 -2: DEVICE_NOT_SUPPORTED），以便前端提示“当前设备不支持通话”或自动降级为复制电话号码。
3. 原生线程安全与 WebView 调用机制： 在 Android 中，@JavascriptInterface 标注的方法运行于独立的 Binder/JavaBridge 线程中，直接在其中操作 UI 或启动 Activity 可能会抛出异常或导致卡顿。所有 UI 交互及后续的 webView.evaluateJavascript 均须通过 activity.runOnUiThread 切回主线程执行。
4. 双卡设备（Dual SIM）处理： 无论 Android 的 ACTION_DIAL 还是 iOS 的 tel:，在双卡手机上，系统拨号盘都会自动弹出 SIM 1 / SIM 2 的选择卡槽供用户选择。通过 JSBridge 唤起系统拨号盘能自然继承操作系统的双卡分发逻辑，无需在 App 内部费力实现复杂的双卡底层订阅查询。

总结

在 Hybrid App 中实现打电话功能，表面上看似只需要一个简单的 tel: 协议，但在跨平台容器架构中，必须通过体系化的 JSBridge 来屏蔽双端底层系统行为的差异。将调用形式规范为“向系统拨号盘填入号码（ACTION_DIAL / tel:）”，不仅彻底免除了申请危险权限带来的拒审风险，还能赋予前端完整的异步状态感知与容灾降级能力，为用户提供流畅且安全的呼叫交互体验。