彻底搞懂WebViewJavascriptBridge：iOS/OSX平台的JS-原生通信黑科技-优快云博客

彻底搞懂WebViewJavascriptBridge：iOS/OSX平台的JS-原生通信黑科技

【免费下载链接】WebViewJavascriptBridge An iOS/OSX bridge for sending messages between Obj-C and JavaScript in UIWebViews/WebViews 项目地址: https://gitcode.com/gh_mirrors/we/WebViewJavascriptBridge

你是否还在为iOS/OSX应用中WebView（网页视图）与原生代码的通信问题头疼？是否遇到过消息传递延迟、数据格式不兼容或者回调处理混乱的情况？本文将带你深入剖析WebViewJavascriptBridge的核心原理，通过实例代码和架构分析，让你彻底掌握这一跨平台通信利器的实现细节。读完本文后，你将能够：

理解JS与原生（Obj-C/Swift）通信的底层机制
掌握WebViewJavascriptBridge的初始化与消息传递流程
学会自定义通信协议和错误处理策略
优化大型应用中的消息队列管理

项目概述：跨平台通信的桥梁

WebViewJavascriptBridge是一个专为iOS和OSX平台设计的开源框架，它解决了WebView中JavaScript（JS）与原生代码（Objective-C/Swift）之间安全高效通信的核心问题。该项目的核心文件位于WebViewJavascriptBridge/目录下，包含了基础通信协议实现、平台适配代码和消息队列管理系统。

项目提供了完整的示例应用，包括iOS和OSX平台的演示代码，可在Example Apps/目录中找到。这些示例展示了如何实现基本的消息传递、回调处理和错误捕获，是学习和集成该框架的最佳起点。

核心架构：消息传递的三层模型

WebViewJavascriptBridge采用分层设计思想，将复杂的跨语言通信问题分解为三个主要层次：协议层、桥接层和应用层。这种架构确保了通信的可靠性和可扩展性，同时简化了上层应用的开发复杂度。

协议层：通信规则的制定者

协议层定义了JS与原生代码通信的基本规则和数据格式，是整个框架的基础。在WebViewJavascriptBridgeBase.h文件中，我们可以看到核心协议常量的定义：

#define kOldProtocolScheme @"wvjbscheme"
#define kNewProtocolScheme @"https"
#define kQueueHasMessage   @"__wvjb_queue_message__"
#define kBridgeLoaded      @"__bridge_loaded__"

这些常量定义了通信所使用的URL协议（wvjbscheme和https）以及特殊消息标记（wvjb_queue_message__和__bridge_loaded）。其中，kBridgeLoaded用于标记桥接初始化完成，而kQueueHasMessage则表示有消息队列需要处理。

协议层还定义了消息的基本结构，包括WVJBMessage类型和WVJBHandler、WVJBResponseCallback等核心回调类型。这些定义确保了JS和原生代码能够理解彼此发送的数据格式和处理方式。

桥接层：跨语言通信的实现者

桥接层是框架的核心，负责实际的消息转发和格式转换工作。它主要由WebViewJavascriptBridge.h和WebViewJavascriptBridge.m实现，提供了统一的API接口，同时适配了iOS和OSX平台的差异。

在iOS平台上，桥接层通过UIWebView的代理方法拦截URL请求来实现消息传递。关键代码位于webView:shouldStartLoadWithRequest:navigationType:方法中：

- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType {
    if (webView != _webView) { return YES; }
    
    NSURL *url = [request URL];
    if ([_base isWebViewJavascriptBridgeURL:url]) {
        if ([_base isBridgeLoadedURL:url]) {
            [_base injectJavascriptFile];
        } else if ([_base isQueueMessageURL:url]) {
            NSString *messageQueueString = [self _evaluateJavascript:[_base webViewJavascriptFetchQueyCommand]];
            [_base flushMessageQueue:messageQueueString];
        } else {
            [_base logUnkownMessage:url];
        }
        return NO;
    } 
    // ... 其他处理代码
}

这段代码展示了桥接层如何拦截特定URL请求，并根据URL类型执行相应操作：如果是桥接加载请求，则注入JS文件；如果是消息队列请求，则获取并处理消息队列。

对于OSX平台，桥接层使用WebView的policyDelegate来实现类似的URL拦截功能，确保了跨平台的一致性。

应用层：开发者的直接接口

应用层为开发者提供了简洁易用的API，隐藏了底层实现细节。主要接口包括注册处理器、调用处理器和设置回调等方法：

- (void)registerHandler:(NSString*)handlerName handler:(WVJBHandler)handler;
- (void)callHandler:(NSString*)handlerName data:(id)data responseCallback:(WVJBResponseCallback)responseCallback;

这些方法定义在WebViewJavascriptBridge.h中，允许开发者轻松实现JS与原生代码的双向通信。同时，框架还提供了WKWebView的适配版本，定义在WKWebViewJavascriptBridge.h中，支持现代WebKit框架。

初始化流程：桥接建立的全过程

WebViewJavascriptBridge的初始化是一个涉及JS和原生代码协同工作的复杂过程。理解这一过程对于正确使用框架至关重要。让我们通过时序图来详细了解初始化的每一个步骤。

初始化时序图

mermaid

初始化关键步骤解析

HTML页面加载：原生应用首先加载包含桥接逻辑的HTML页面，这通常是通过UIWebView或WKWebView的loadRequest方法实现的。
JS桥接函数定义：在HTML页面中，JS代码定义了setupWebViewJavascriptBridge函数，如ExampleApp.html所示：

function setupWebViewJavascriptBridge(callback) {
    if (window.WebViewJavascriptBridge) { return callback(WebViewJavascriptBridge); }
    if (window.WVJBCallbacks) { return window.WVJBCallbacks.push(callback); }
    window.WVJBCallbacks = [callback];
    var WVJBIframe = document.createElement('iframe');
    WVJBIframe.style.display = 'none';
    WVJBIframe.src = 'https://__bridge_loaded__';
    document.documentElement.appendChild(WVJBIframe);
    setTimeout(function() { document.documentElement.removeChild(WVJBIframe) }, 0)
}

这个函数负责创建一个隐藏的iframe，其src属性设置为特殊的https://__bridge_loaded__URL，用于通知原生代码JS环境已准备就绪。

原生代码拦截请求：当WebView尝试加载https://__bridge_loaded__URL时，原生代码的WebView代理方法会拦截这个请求。在WebViewJavascriptBridge.m中，我们可以看到相关处理逻辑：

if ([_base isBridgeLoadedURL:url]) {
    [_base injectJavascriptFile];
}

注入JS桥接代码：原生代码调用injectJavascriptFile方法，向WebView注入JS桥接代码。这段代码定义了window.WebViewJavascriptBridge对象及其核心方法，如registerHandler、callHandler等，实现了JS侧的桥接逻辑。
回调函数执行：JS桥接代码初始化完成后，会执行之前通过setupWebViewJavascriptBridge注册的回调函数，通知应用层桥接已准备就绪。此时，应用层就可以开始使用桥接进行通信了。

消息传递：数据如何跨越语言边界

WebViewJavascriptBridge的核心功能是实现JS与原生代码之间的安全高效通信。这一过程涉及消息的创建、发送、接收和处理等多个环节，每个环节都有其独特的实现细节。

消息结构：统一的数据格式

所有通过WebViewJavascriptBridge传递的消息都遵循统一的数据格式，确保JS和原生代码能够正确解析。在原生代码中，消息被定义为WVJBMessage类型（实际上是NSDictionary），包含以下几个主要字段：

handlerName：字符串类型，表示要调用的处理器名称
data：任意类型，表示要传递的数据
callbackId：字符串类型，用于标识回调函数
responseId：字符串类型，用于标识响应对应的请求
responseData：任意类型，表示响应数据

这种统一的消息格式使得框架能够处理各种复杂的通信场景，包括简单消息传递、带回调的请求-响应模式等。

JS调用原生代码：从网页到应用

当JS需要调用原生代码时，它会调用WebViewJavascriptBridge的callHandler方法。以下是ExampleApp.html中的示例代码：

bridge.callHandler('testObjcCallback', {'foo': 'bar'}, function(response) {
    log('JS got response', response)
})

这个调用会触发一系列内部操作，最终导致原生代码中对应的处理器被执行。其完整流程如下：

JS侧将消息添加到消息队列中
创建隐藏iframe，src设为wvjbscheme://wvjb_queue_message
WebView拦截到这个特殊URL请求
原生代码调用webViewJavascriptFetchQueyCommand获取消息队列
解析消息队列，找到对应的处理器并执行
如果有回调，将处理结果通过responseCallback返回给JS

在原生代码中，消息的处理主要由flushMessageQueue:方法完成，该方法位于WebViewJavascriptBridgeBase.h中。这个方法会解析从JS获取的消息队列字符串，将其转换为原生对象，然后分发给相应的处理器。

原生调用JS代码：从应用到网页

原生代码调用JS代码的流程与JS调用原生类似，但方向相反。原生代码通过调用callHandler:data:responseCallback:方法来触发JS侧的处理器：

[self.bridge callHandler:@"testJavascriptHandler" data:@{@"key": @"value"} responseCallback:^(id responseData) {
    NSLog(@"ObjC got response: %@", responseData);
}];

这个调用会经历以下步骤：

原生代码创建包含handlerName、data和callbackId的消息
将消息序列化为JSON字符串
通过stringByEvaluatingJavaScriptFromString:方法将JS代码注入WebView
JS侧的桥接代码解析消息，找到对应的处理器并执行
如果有回调，JS会通过类似的机制将结果返回给原生代码

原生调用JS的一个关键区别是，它不需要使用iframe来触发通信，而是直接通过stringByEvaluatingJavaScriptFromString:方法执行JS代码。这是因为原生代码可以主动向WebView注入JS，而JS无法直接调用原生代码，只能通过URL请求间接触发。

回调机制：请求-响应模式的实现

WebViewJavascriptBridge支持请求-响应模式的通信，即发送方可以指定一个回调函数，接收方处理完成后调用该回调函数返回结果。这种机制在需要获取操作结果的场景中非常有用。

回调机制的实现依赖于callbackId和responseId的匹配。当发送方发送一个带回调的消息时，会生成一个唯一的callbackId，并将其与回调函数一起存储。接收方处理完成后，会发送一个包含responseId（等于原callbackId）和responseData的响应消息。发送方收到响应后，通过responseId找到对应的回调函数并执行。

这种设计使得回调函数可以跨越语言边界被正确调用，即使在复杂的异步场景下也能保证消息的正确匹配。

高级特性：让通信更安全高效

除了基本的消息传递功能，WebViewJavascriptBridge还提供了一些高级特性，帮助开发者构建更安全、更高效的跨语言通信系统。

日志系统：调试与监控的利器

WebViewJavascriptBridge内置了完善的日志系统，可以帮助开发者调试和监控通信过程。通过调用+enableLogging方法，开发者可以启用日志功能：

[WebViewJavascriptBridge enableLogging];

日志系统会记录所有重要的通信事件，包括消息发送、接收、处理结果等。开发者还可以通过+setLogMaxLength:方法设置日志的最大长度，避免日志过大影响应用性能。

日志功能在开发和调试阶段非常有用，但在生产环境中应该禁用，以减少性能开销和信息泄露风险。

安全性考虑：防范潜在风险

WebView中的JS与原生代码通信可能带来安全风险，WebViewJavascriptBridge通过多种机制来降低这些风险：

URL验证：所有通过框架传递的URL都会经过严格验证，只有符合特定格式的URL才会被处理，如kOldProtocolScheme或kNewProtocolScheme开头的URL。
消息验证：每个消息都会经过验证，确保其包含必要的字段，并且格式正确。
超时机制：框架内置了安全超时机制，防止恶意JS代码通过无限循环等方式阻塞原生应用。开发者可以通过disableJavscriptAlertBoxSafetyTimeout方法禁用这一机制，但需谨慎使用。
权限控制：通过注册处理器机制，框架实现了类似API的权限控制，只有注册过的处理器才能被调用，减少了未授权访问的风险。

性能优化：提升通信效率

在大型应用中，频繁的JS-原生通信可能成为性能瓶颈。WebViewJavascriptBridge提供了多种机制来优化通信效率：

消息队列：所有消息都通过队列进行管理，避免了频繁的跨语言调用开销。
批处理：多个消息可以被批量处理，减少了WebView和原生代码之间的交互次数。
延迟执行：一些非关键操作会被延迟执行，避免影响主线程响应速度。
内存管理：框架对回调函数等资源进行了精细的管理，避免了内存泄漏。

开发者还可以通过以下方式进一步优化通信性能：

减少不必要的通信，尽量在同一侧完成相关操作
合并小消息，减少通信次数
避免在通信过程中传输大量数据，必要时考虑分块传输
将耗时操作放在后台线程执行，避免阻塞UI

实战指南：从零开始集成WebViewJavascriptBridge

掌握了WebViewJavascriptBridge的核心原理后，接下来我们将通过一个实际示例，展示如何在iOS应用中集成和使用这个框架。这个示例将涵盖从环境准备到高级功能使用的各个方面。

环境准备与框架集成

首先，我们需要将WebViewJavascriptBridge集成到iOS项目中。推荐的方式是通过CocoaPods，只需在Podfile中添加以下行：

pod 'WebViewJavascriptBridge'

然后运行pod install命令即可完成安装。如果你更喜欢手动集成，可以直接将WebViewJavascriptBridge/目录下的所有文件添加到项目中。

基本使用步骤

以下是在iOS应用中使用WebViewJavascriptBridge的基本步骤：

导入头文件：在需要使用桥接功能的ViewController中导入头文件

#import "WebViewJavascriptBridge.h"

创建WebView和Bridge实例：在viewDidLoad方法中创建UIWebView和对应的Bridge实例

UIWebView *webView = [[UIWebView alloc] initWithFrame:self.view.bounds];
[self.view addSubview:webView];

self.bridge = [WebViewJavascriptBridge bridgeForWebView:webView];
[self.bridge setWebViewDelegate:self];

注册原生处理器：注册供JS调用的处理器

[self.bridge registerHandler:@"showAlert" handler:^(id data, WVJBResponseCallback responseCallback) {
    NSString *message = data[@"message"];
    UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"来自JS的消息" 
                                                    message:message 
                                                   delegate:nil 
                                          cancelButtonTitle:@"确定" 
                                          otherButtonTitles:nil];
    [alert show];
    
    if (responseCallback) {
        responseCallback(@{@"status": @"success"});
    }
}];

加载包含桥接逻辑的HTML页面：

NSURL *htmlURL = [[NSBundle mainBundle] URLForResource:@"index" withExtension:@"html"];
[webView loadRequest:[NSURLRequest requestWithURL:htmlURL]];

JS侧初始化并调用原生代码：在HTML页面中添加JS代码

setupWebViewJavascriptBridge(function(bridge) {
    // 注册JS处理器
    bridge.registerHandler('jsHandler', function(data, responseCallback) {
        console.log('JS处理器被调用，数据：', data);
        responseCallback({result: '处理完成'});
    });
    
    // 调用原生处理器
    var button = document.getElementById('callNative');
    button.onclick = function() {
        bridge.callHandler('showAlert', {message: 'Hello from JS'}, function(response) {
            console.log('原生调用结果：', response);
        });
    };
});

调试与问题排查

在集成和使用WebViewJavascriptBridge的过程中，可能会遇到各种问题。以下是一些常见问题的排查方法：

启用详细日志：通过调用[WebViewJavascriptBridge enableLogging]启用详细日志，帮助追踪消息传递过程。
检查URL拦截：确保WebView的delegate设置正确，并且没有其他代码干扰URL请求的处理。
验证JS注入：使用Safari的Web检查器查看是否成功注入了桥接JS代码。
检查消息格式：确保传递的消息是有效的JSON格式，避免包含循环引用等无法序列化的数据。
处理错误回调：实现全局错误处理函数，捕获和记录通信过程中的异常。

高级功能使用

WebViewJavascriptBridge还提供了一些高级功能，可以帮助开发者应对更复杂的场景：

移除处理器：通过removeHandler:方法移除不再需要的处理器，释放资源。
禁用安全超时：在某些特殊情况下，可以通过disableJavscriptAlertBoxSafetyTimeout方法禁用JS警告框的安全超时。
自定义日志长度：通过setLogMaxLength:方法设置日志的最大长度，控制日志输出量。
WKWebView支持：对于需要使用WKWebView的场景，可以使用WKWebViewJavascriptBridge.h中定义的WKWebViewJavascriptBridge类。

总结与展望：WebView通信的未来

WebViewJavascriptBridge作为一个成熟的跨平台通信框架，已经在众多iOS和OSX应用中得到了广泛应用。它通过巧妙的设计解决了JS与原生代码通信的核心问题，同时保持了API的简洁易用。

框架优势与局限性

WebViewJavascriptBridge的主要优势包括：

跨平台支持：同时支持iOS和OSX平台，代码复用率高
简单易用：API设计简洁直观，学习成本低
安全可靠：内置安全机制，防止恶意访问和数据泄露
性能优化：通过消息队列和批处理机制提升通信效率
扩展性强：支持自定义处理器和复杂的数据类型

然而，该框架也存在一些局限性：

依赖WebView：只能在WebView环境中使用，无法用于纯原生应用
兼容性问题：虽然支持UIWebView和WKWebView，但两者的实现有差异
通信延迟：由于采用URL拦截机制，通信存在一定延迟
功能有限：只提供基本的消息传递功能，不包含高级特性如实时通信

未来发展方向

随着移动应用开发技术的不断演进，WebViewJavascriptBridge也在不断发展。未来可能的改进方向包括：

更好的WKWebView支持：进一步优化WKWebView的实现，利用其新特性提升性能
Swift API：提供更完善的Swift接口，适应iOS开发的Swift化趋势
WebSocket支持：集成WebSocket技术，实现更低延迟的实时通信
类型安全：引入更严格的类型检查，减少运行时错误
模块化设计：采用更模块化的设计，允许开发者按需引入功能

替代方案比较

除了WebViewJavascriptBridge，还有其他一些方案可以实现JS与原生代码的通信：

JavaScriptCore：iOS 7+提供的原生JS引擎，可以直接执行JS代码
WKScriptMessageHandler：WKWebView提供的消息传递机制
自定义URL Scheme：通过自定义URL协议实现通信，与WebViewJavascriptBridge原理类似
插件化框架：如Cordova、React Native等，提供更完整的跨平台解决方案

与这些方案相比，WebViewJavascriptBridge的主要优势在于其简单性和兼容性，特别适合需要轻量级解决方案的场景。而对于复杂应用，可能需要考虑更全面的框架如React Native。

无论选择哪种方案，理解JS与原生代码通信的基本原理都是至关重要的。WebViewJavascriptBridge作为这一领域的经典实现，其设计思想和实现细节对于任何移动应用开发者都具有重要的参考价值。

希望本文能够帮助你深入理解WebViewJavascriptBridge的内部机制，并在实际项目中灵活运用这一强大的工具。如果你有任何问题或建议，欢迎通过项目的GitHub仓库参与讨论和贡献。

官方文档：README.md API参考：WebViewJavascriptBridge.h 示例代码：Example Apps/

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考