OC中WKWebView调用JS并获取返回值的实现方法
详细讲解在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 丢失问题。
一、核心 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详细错误。
二、标准调用流程与生命周期时机控制
初学者最容易遇到的问题是调用时机过早。如果在 WKWebView 尚未完成网页加载、DOM 树未就绪或对应的 JavaScript 文件未下载完毕时就调用 evaluateJavaScript:,会导致 JavaScript 找不到指定的全局变量或方法,从而触发未定义异常。
正确的调用流程需要遵循以下 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: 进行类型判定。
| 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 获取返回值涉及跨语言通信、执行上下文差异和内存管理等多个维度。以下梳理了四大常见痛点及标准防御策略:
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 和脚本语法中断等潜在隐患。
Vue项目中通过index.html引入外部JS后怎么在组件内访问
2026-11-21 17:58:10
JS怎么兼容旧浏览器解析URL参数
2026-11-21 16:38:43
JS动态设置背景颜色后怎么恢复默认样式
2026-11-21 12:54:18
HTML引入JS文件的正确写法:script标签基础语法
2026-11-21 08:51:36
怎么使用节流优化JavaScript高频滚轮事件
2026-11-20 23:57:39








