OC中WKWebView调用JS并获取返回值的实现方法

作者:像素漫游

时间:2026-11-21

浏览:336

详细讲解在Objective-C中通过WKWebView的evaluateJavaScript:completionHandler:调用JavaScript脚本并获取返回值的实现方法,涵盖生命周期调用时机、数据类型自动映射转换、异常捕获与iOS 14异步Promise处理方案。

文章目录

在 Objective-C 中,WKWebView 调用 JavaScript 并获取返回值的标准方法是使用 evaluateJavaScript:completionHandler:。该方法异步向当前网页执行 JS 脚本字符串,并在脚本运行结束后在主线程通过 Block 回调返回原生对象(id _Nullable result)与错误信息(NSError * _Nullable error)。掌握该机制的核心在于控制正确的执行生命周期、理解 WebKit 跨语言类型自动转换映射,以及妥善防御 JS 语法异常和异步 Promise 丢失问题。

OC中WKWebView调用JS并获取返回值的实现方法
图 0:Objective-C WKWebView 与 JavaScript 通信架构概要

一、核心 API 规范与底层通信机制

在 iOS 8.0 及 macOS 10.10 引入 WebKit 框架后,WKWebView 取代了传统的 UIWebView。由于 WKWebView 运行在独立的渲染进程(WebProcess)中,主应用(UIProcess)与网页运行时的通信必须通过跨进程通信(IPC)机制进行。因此,所有与 JavaScript 的交互都被设计为完全非阻塞的异步 API。

Objective-C 端调用的核心方法原型如下:

// WKWebView.h
- (void)evaluateJavaScript:(NSString *)javaScriptString 
         completionHandler:(void (^ _Nullable)(id _Nullable result, NSError * _Nullable error))completionHandler;

该方法的调用行为包含以下三个重要特征:

  • 参数传递:入参 javaScriptString 必须是合法的 JavaScript 脚本字符串,可以是单行表达式(如 document.title)、函数调用(如 calculateTotal(10, 20)),也可以是自执行函数闭包(IIFE)。
  • 主线程安全调度:虽然底层通信为跨进程异步操作,但 WebKit 会确保 completionHandler 回调自动回到主线程(Main Queue)执行。开发者在 Block 内部可以直接刷新 UI 控件,无需手动切换线程。
  • 返回值抽象:JavaScript 的求值结果会被转换为 Objective-C 的基础 Foundation 对象,并通过 result 形参交付;若执行失败或抛出异常,则 result 为 nil,同时提供 error 详细错误。
OC中WKWebView调用JS并获取返回值的实现方法
图 1:WKWebView 与 JavaScript 跨进程通信与数据流转架构

二、标准调用流程与生命周期时机控制

初学者最容易遇到的问题是调用时机过早。如果在 WKWebView 尚未完成网页加载、DOM 树未就绪或对应的 JavaScript 文件未下载完毕时就调用 evaluateJavaScript:,会导致 JavaScript 找不到指定的全局变量或方法,从而触发未定义异常。

正确的调用流程需要遵循以下 4 个阶段:

OC中WKWebView调用JS并获取返回值的实现方法
图 2:OC 调用 JS 并解析返回值的 4 步标准操作流程

1. 注册导航代理与加载页面

在初始化 WKWebView 时,必须指派 navigationDelegate 并遵循 WKNavigationDelegate 协议:

// 初始化并绑定导航代理
WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
self.webView.navigationDelegate = self;
[self.view addSubview:self.webView];

// 开始加载网页资源
NSURL *url = [NSURL URLWithString:@"https://example.com"];
[self.webView loadRequest:[NSURLRequest requestWithURL:url]];

2. 在加载完成回调中或交互事件中发起调用

通过实现 webView:didFinishNavigation: 回调,确保当前网页的 DOM 解析与默认脚本执行完毕后再发起调用:

- (void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation {
    // 页面已完全就绪,执行 JS 获取文档标题
    [webView evaluateJavaScript:@"document.title" completionHandler:^(id _Nullable result, NSError * _Nullable error) {
        if (error) {
            NSLog(@"执行 JS 出错: %@", error.localizedDescription);
            return;
        }
        if ([result isKindOfClass:[NSString class]]) {
            NSString *webTitle = (NSString *)result;
            self.navigationItem.title = webTitle;
        }
    }];
}
提示:如果调用是由原生按钮点击、滑动手势等用户交互触发的,可以在动作响应方法中直接调用 evaluateJavaScript:completionHandler:,但同样建议预先判断当前页面的 webView.isLoading 状态,避免在重载或跳转期间误调。

三、JavaScript 与 Objective-C 的数据类型映射规则

JavaScript 作为动态弱类型语言,其返回值在传递给 Objective-C 时,会被 WebKit 内部序列化机制自动映射为 Cocoa Foundation 框架中的对应类型。开发者在消费 result 对象时,切忌直接强转,必须使用 isKindOfClass: 进行类型判定。

OC中WKWebView调用JS并获取返回值的实现方法
图 3:JavaScript 与 Objective-C 数据类型对应转换规则
JavaScript 数据类型 对应 Objective-C 类型 返回值示例 OC 解析与使用说明
String NSString @"Hello World" 直接强转为 NSString * 读取文本。
Number(整型/浮点型) NSNumber @1024 / @3.14159 调用 [num integerValue] 或 [num doubleValue]。
Boolean NSNumber @YES / @NO 底层为封装了布尔值的 NSNumber,取 [num boolValue]。
Array NSArray @[@"item1", @2] 数组内部各元素同样遵守本表的递归转换规则。
Object(JSON 字面量) NSDictionary @{@"id": @1, @"name": @"Alice"} 字典键通常为 NSString,值按对应类型解析。
null / undefined nil(根结果)/ NSNull(容器内) nil 若整个 JS 表达式返回 null 或无返回值,Block 的 result 为 nil 且 error 也为 nil;若作为数组或字典的内部值,则体现为 [NSNull null]。
Function / Symbol 不支持直接传递 nil 无法序列化的对象无法直接返回,建议在 JS 端将其转换为字符串或数值。

安全解析复杂 JSON 对象的代码模式

[self.webView evaluateJavaScript:@"getUserProfile()" completionHandler:^(id _Nullable result, NSError * _Nullable error) {
    if (error) {
        NSLog(@"执行失败: %@", error);
        return;
    }
    
    // 必须做类型防御校验
    if ([result isKindOfClass:[NSDictionary class]]) {
        NSDictionary *profile = (NSDictionary *)result;
        NSString *userName = profile[@"username"];
        NSNumber *userId = profile[@"id"];
        NSLog(@"解析到用户信息: name=%@, id=%@", userName, userId);
    } else if (result == nil) {
        NSLog(@"JS 未返回有效对象 (null 或 undefined)");
    }
}];

四、常见问题排查与关键防御策略

在实际工程开发中,调用 JS 获取返回值涉及跨语言通信、执行上下文差异和内存管理等多个维度。以下梳理了四大常见痛点及标准防御策略:

OC中WKWebView调用JS并获取返回值的实现方法
图 4:WKWebView 调用 JS 常见问题排查与防御策略总结

1. JavaScript 运行时异常捕获

当 JavaScript 脚本内部发生语法错误、访问未声明变量(ReferenceError)或调用不存在的方法(TypeError)时,evaluateJavaScript 的 result 会被置为 nil,同时返回一个包含错误信息的 NSError 对象。

  • 错误域(Domain):WKErrorDomain
  • 常见错误码(Code):WKErrorJavaScriptExceptionOccurred(值为 4,代表 JS 抛出未捕获异常)
  • 获取详细日志:在 error.userInfo[@"WKJavaScriptExceptionMessage"] 中可提取具体的 JS 报错原因及堆栈定位。

2. 异步函数与 Promise 返回值的处理方案

现代前端代码广泛使用 async/await 或返回 Promise。传统的 evaluateJavaScript:completionHandler: 是同步表达式求值,它不会等待 Promise resolve。如果调用的 JS 方法返回一个 Promise 对象,原生端只会接收到一个空的 NSDictionary({})或 nil。

针对 Promise 异步返回值,有两种成熟的解决途径:

  • 方案 A(iOS 14.0+ 原生 API):使用 callAsyncJavaScript:
    WebKit 在 iOS 14.0+ / macOS 11.0+ 提供了原生支持 Promise 的现代化 API。系统会自动 await 函数返回的 Promise,并在 resolve 后将最终数据交付回调:
    if (@available(iOS 14.0, *)) {
        NSString *asyncScript = @"return await fetchUserInfo(userId);";
        NSDictionary *arguments = @{@"userId": @10086};
        
        [self.webView callAsyncJavaScript:asyncScript
                               arguments:arguments
                          inContentWorld:WKContentWorld.pageWorld
                       completionHandler:^(id _Nullable result, NSError * _Nullable error) {
            if (!error) {
                NSLog(@"异步获取到数据: %@", result);
            }
        }];
    }
  • 方案 B(全系统兼容方案):通过 WKScriptMessageHandler 反向回传
    在低版本系统中,若必须调用包含异步请求的 JS 方法,可在 JS 代码中通过 .then() 获取结果后,主动调用 window.webkit.messageHandlers.<handlerName>.postMessage(data) 将数据通知原生端,由原生的 userContentController:didReceiveScriptMessage: 方法接收并消费。

3. 避免 Block 强引用循环

由于 evaluateJavaScript:completionHandler: 的 Block 会被 WebKit 在执行期间持有,如果在 Block 内部直接使用 self 或访问成员变量(如 _webView),在网络异常或长时间运行的耗时脚本场景下,容易造成控制器无法正常释放。

// 防御强引用循环标准范式
__weak typeof(self) weakSelf = self;
[self.webView evaluateJavaScript:@"getArticleContent()" completionHandler:^(id _Nullable result, NSError * _Nullable error) {
    __strong typeof(weakSelf) strongSelf = weakSelf;
    if (!strongSelf) return;
    
    if (!error && [result isKindOfClass:[NSString class]]) {
        [strongSelf updateContentLabel:(NSString *)result];
    }
}];

五、工程实战:完整封装与安全调用示例

在实际生产环境中,建议将 JS 脚本的执行与参数注入封装为通用工具方法,避免拼接原生字符串时因特殊字符(如单双引号、换行符)导致脚本解析失败或出现代码注入漏洞。以下给出推荐的安全调用模式:

// ViewController.m 完整安全调用示范
#import "ViewController.h"
#import <WebKit/WebKit.h>

@interface ViewController () <WKNavigationDelegate>
@property (nonatomic, strong) WKWebView *webView;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.view.backgroundColor = [UIColor whiteColor];
    
    WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
    self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
    self.webView.navigationDelegate = self;
    [self.view addSubview:self.webView];
    
    // 加载本地或远程网页
    NSURL *url = [NSURL URLWithString:@"https://m.baidu.com"];
    [self.webView loadRequest:[NSURLRequest requestWithURL:url]];
}

#pragma mark - WKNavigationDelegate

- (void)webView:(WKWebView *)webView didFinishNavigation:(WKNavigation *)navigation {
    // 1. 执行简单表达式读取页面高度
    [webView evaluateJavaScript:@"document.body.scrollHeight" completionHandler:^(id _Nullable result, NSError * _Nullable error) {
        if (!error && [result isKindOfClass:[NSNumber class]]) {
            CGFloat contentHeight = [(NSNumber *)result doubleValue];
            NSLog(@"网页内容真实高度: %.2f", contentHeight);
        }
    }];
    
    // 2. 安全传参并调用 JS 函数
    [self callJavaScriptFunction:@"sumNumbers" 
                       arguments:@[@12, @30] 
                      completion:^(id _Nullable result, NSError * _Nullable error) {
        if (!error) {
            NSLog(@"函数计算返回结果: %@", result);
        } else {
            NSLog(@"调用出错: %@", error.localizedDescription);
        }
    }];
}

/**
 * 安全封装:通过 JSON 序列化保证入参安全转义
 */
- (void)callJavaScriptFunction:(NSString *)functionName 
                     arguments:(NSArray *)args 
                    completion:(void (^)(id _Nullable, NSError * _Nullable))completion {
    NSError *jsonError = nil;
    NSData *jsonData = [NSJSONSerialization dataWithJSONObject:args options:0 error:&jsonError];
    if (jsonError) {
        if (completion) completion(nil, jsonError);
        return;
    }
    
    // 将参数转换为 JS 数组字面量
    NSString *argsJsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
    // 利用 apply 执行函数
    NSString *jsCode = [NSString stringWithFormat:@"%@.apply(null, %@)", functionName, argsJsonString];
    
    [self.webView evaluateJavaScript:jsCode completionHandler:completion];
}

@end
安全建议:当需要向 evaluateJavaScript 拼接由外部输入、网络下发或用户输入的动态数据时,务必通过 NSJSONSerialization 将参数序列化,切勿直接使用 stringWithFormat: 进行裸字符串拼接,以杜绝 XSS 和脚本语法中断等潜在隐患。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章