iOS混合开发中，WKWebView承载了大量H5页面与原生交互的需求。当我们需要向网页注入JavaScript代码时，注入时机直接决定了脚本能否正常获取到DOM元素、能否绑定事件以及能否与原生层通信。不少功能故障，例如按钮点击无反应、页面变量未定义，其实都源于注入时刻页面结构尚未准备好。
WKUserScriptInjectionTime的两种时机与配置方式
WKWebView提供了WKUserScript类来声明需要注入的脚本，其中最重要的参数之一就是injectionTime。系统定义了WKUserScriptInjectionTimeAtDocumentStart和WKUserScriptInjectionTimeAtDocumentEnd两个枚举值。前者表示在文档开始解析时注入，此时<html>刚创建，DOM树几乎为空；后者表示在文档解析完成但子资源可能未加载时注入，此时DOM结构已经可见。
在Objective-C或Swift中，我们一般通过WKUserContentController添加脚本。下面是一段典型的Swift配置代码，展示了如何以不同时机注入两段脚本：
import WebKit
let config = WKWebViewConfiguration()
let controller = WKUserContentController()
let startScript = WKUserScript(
source: "window.__nativeReady = false;",
injectionTime: .atDocumentStart,
forMainFrameOnly: true
)
let endScript = WKUserScript(
source: "window.__nativeReady = true; document.dispatchEvent(new Event('nativeReady'));",
injectionTime: .atDocumentEnd,
forMainFrameOnly: true
)
controller.addUserScript(startScript)
controller.addUserScript(endScript)
config.userContentController = controller
从上面的代码可以看出，atDocumentStart适合设置全局标志位或劫持某些原型方法，而atDocumentEnd更适合执行依赖完整DOM的操作。如果错误地使用atDocumentStart去获取某个<div>的文本内容，得到的值一定是空，因为节点还不存在。合理选择时机是排除注入类Bug的第一步。
DOM加载完成的监听方案与双侧配合
即便使用了atDocumentEnd，也不能保证所有子资源（如图片、异步接口）已就绪，但对于DOM节点来说已经足够。如果H5自身有复杂的框架初始化过程，仅仅依赖atDocumentEnd仍可能早于业务代码挂载组件。此时需要在JS内主动监听DOMContentLoaded或者load事件。
我们可以在注入的脚本中包装一层监听逻辑，确保真正DOM解析完毕后再运行主逻辑。下面的JavaScript示例演示了如何安全等待DOM完成：
(function () {
function runWhenDOMReady(callback) {
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', callback, false);
} else {
callback();
}
}
runWhenDOMReady(function () {
var btn = document.getElementById('submitBtn');
if (btn) {
btn.addEventListener('click', function () {
window.webkit.messageHandlers.clickHandler.postMessage('submit');
});
}
});
})();
这种写法的好处是无论脚本在何时被注入，只要页面还在加载中就会等事件触发，否则立即执行。相比单纯依赖WKUserScriptInjectionTimeAtDocumentEnd，它更贴合H5自身的生命周期。同时，原生侧也可以通过WKNavigationDelegate的didFinishNavigation来辅助判断页面跳转完成，但不建议在该回调中再使用evaluateJavaScript做关键绑定，因为此时JS上下文可能已多次重建。
常见误区与稳定的注入架构建议
一个被广泛忽略的误区是：开发者常常把atDocumentStart当作万能钩子，试图在其中动态创建<script>标签去加载远程JS。由于此时网络栈与文档解析并行，远程脚本返回时DOM可能仍未生成，回调顺序难以保证。另一个误区是频繁调用evaluateJavaScript去轮询某个元素是否存在，这种方式既浪费CPU也容易造成内存压力。
更稳定的做法是将注入脚本分为两层：底层在atDocumentStart注入通信桥与状态标记，业务层在atDocumentEnd注入并配合DOMContentLoaded监听。如下表对比了不同策略的适用场景：
| 注入时机 | 可访问DOM | 适用操作 |
|---|---|---|
| AtDocumentStart | 否 | 设置全局变量、劫持方法 |
| AtDocumentEnd | 是（结构层） | 绑定事件、读取节点 |
| DOMContentLoaded后 | 是（完整结构） | 业务初始化、与原生通信 |
综合来看，解决iOS端WKWebView的JS注入时机问题，核心在于理解WKUserScriptInjectionTime只是原生提供的两个粗略锚点，真正的DOM就绪必须以网页自身事件为准。采用分层注入加事件监听的架构，可以显著降低因时机错配导致的交互失效，让混合开发中的原生与H5协作更加顺畅。
WKWebViewWKUserScriptInjectionTimeDOM加载监听修改时间：2026-08-18 21:40:27