WKWebView setContentOffset(animated:false)不生效，如何判断安全调用时机？

核心原因 #

didFinish 代理触发仅代表主HTML文档加载完成，但页面内的样式、图片等资源可能还未渲染完毕，此时WKWebView的scrollView还未计算出准确的contentSize。调用setContentOffset(animated:false)时，scrollView因未明确可滚动范围，会直接忽略该指令；而animated:true会将滚动操作加入动画队列，等contentSize就绪后自动执行，延迟调用本质是赌资源渲染完成的时机，但容易出现卡顿。

可行解决方案 #

1. 通过JS监听页面完全渲染完成，通知原生代码

在加载HTML时注入JavaScript，等待文档完全渲染（包括布局计算完成）后，通过WKScriptMessageHandler通知原生代码，此时再调用setContentOffset(animated:false)：

首先配置WKWebView的UserContentController：

let userContentController = WKUserContentController()
userContentController.add(self, name: "scrollReady")
let configuration = WKWebViewConfiguration()
configuration.userContentController = userContentController
let webView = WKWebView(frame: .zero, configuration: configuration)

注入监听JS到HTML字符串中：

let js = """
function waitForFullRender() {
  if (document.readyState === 'complete') {
    // 用requestAnimationFrame确保布局计算完成
    requestAnimationFrame(() => {
      window.webkit.messageHandlers.scrollReady.postMessage({
        contentHeight: document.body.scrollHeight,
        contentWidth: document.body.scrollWidth
      });
    });
  } else {
    setTimeout(waitForFullRender, 50);
  }
}
waitForFullRender();
"""
// 将JS插入到HTML头部
let finalHTML = "<script>\(js)</script>" + originalHTML
webView.loadHTMLString(finalHTML, baseURL: nil)

实现WKScriptMessageHandler代理方法，收到通知后设置偏移：

func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
  if message.name == "scrollReady" {
    // 这里设置目标偏移量
    let targetOffset = CGPoint(x: 0, y: yourTargetY)
    webView.scrollView.setContentOffset(targetOffset, animated: false)
  }
}

2. 监听scrollView的contentSize稳定状态

通过KVO监听scrollView的contentSize，直到其不再变化（稳定），再执行滚动操作：

添加KVO监听：

private var lastContentSize: CGSize = .zero
private let scrollContext = UnsafeMutableRawPointer.allocate(byteCount: 1, alignment: 1)

override func viewDidLoad() {
  super.viewDidLoad()
  webView.scrollView.addObserver(self, forKeyPath: "contentSize", options: [.new], context: scrollContext)
}

实现KVO回调：

override func observeValue(forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey : Any]?, context: UnsafeMutableRawPointer?) {
  guard context == scrollContext, keyPath == "contentSize" else {
    super.observeValue(forKeyPath: keyPath, of: object, change: change, context: context)
    return
  }
  
  guard let newSize = change?[.newKey] as? CGSize, newSize != .zero else { return }
  
  // 判断contentSize是否稳定（连续两次变化差值小于1像素，视为稳定）
  let sizeDiff = abs(newSize.height - lastContentSize.height) + abs(newSize.width - lastContentSize.width)
  if sizeDiff < 1 {
    // contentSize稳定，执行滚动
    let targetOffset = CGPoint(x: 0, y: yourTargetY)
    webView.scrollView.setContentOffset(targetOffset, animated: false)
    // 移除监听，避免重复触发
    webView.scrollView.removeObserver(self, forKeyPath: "contentSize", context: scrollContext)
  } else {
    lastContentSize = newSize
  }
}

3. 循环检查文档高度直到稳定

在didFinish代理中，通过evaluateJavaScript定期获取文档高度，直到高度不再变化：

func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
  checkDocumentHeightStability(webView: webView, lastHeight: 0, attempt: 0)
}

private func checkDocumentHeightStability(webView: WKWebView, lastHeight: CGFloat, attempt: Int) {
  // 限制尝试次数，避免无限循环
  guard attempt < 20 else {
    // 兜底用animated:true执行
    webView.scrollView.setContentOffset(targetOffset, animated: true)
    return
  }
  
  webView.evaluateJavaScript("document.body.scrollHeight") { [weak self] result, error in
    guard let self = self, let height = result as? CGFloat else { return }
    
    if abs(height - lastHeight) < 1 {
      // 高度稳定，设置偏移
      self.webView.scrollView.setContentOffset(self.targetOffset, animated: false)
    } else {
      // 延迟50ms再次检查
      DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
        self.checkDocumentHeightStability(webView: webView, lastHeight: height, attempt: attempt + 1)
      }
    }
  }
}

额外注意事项 #

• 确保WKWebView已经被添加到视图层级中，未添加到视图的webView可能无法正确计算布局。
• 如果EPUB章节有自定义样式，确保样式加载完成后再计算偏移，避免因样式导致的布局变化。

内容的提问来源于stack exchange，提问作者rassar