Playwright中page的实现类深度解析-PageImpl 方法作用解析
PageImpl 方法作用解析
PageImpl 是 Playwright Java 中 Page 接口的核心实现类，继承自 ChannelOwner，负责封装浏览器页面的所有操作逻辑，内部依赖 BrowserContext、Frame、Keyboard、Mouse 等组件，方法可按功能分为 事件管理、页面生命周期、元素操作、导航控制、网络路由、等待事件 等大类，以下是每个方法的详细作用解析。
一、事件监听与管理相关方法
用于添加/移除页面各类事件的处理器，基于 ListenerCollection 管理监听器，核心是将事件处理器绑定到对应的事件类型，触发时通知监听器。
| 方法 | 作用 | 关键实现细节 |
|---|---|---|
onClose(Consumer<Page> handler) | 添加页面关闭事件处理器，页面关闭时触发 | 通过 listeners.add(EventType.CLOSE, handler) 注册监听器 |
offClose(Consumer<Page> handler) | 移除页面关闭事件的处理器 | 通过 listeners.remove(EventType.CLOSE, handler) 移除 |
onConsoleMessage(Consumer<ConsoleMessage> handler) | 添加控制台消息事件处理器（如 console.log） | 绑定 EventType.CONSOLE 事件，接收 ConsoleMessage 实例 |
offConsoleMessage(Consumer<ConsoleMessage> handler) | 移除控制台消息事件的处理器 | 从 EventType.CONSOLE 事件中移除监听器 |
onCrash(Consumer<Page> handler) | 添加页面崩溃事件处理器 | 绑定 EventType.CRASH 事件，页面崩溃时触发 |
offCrash(Consumer<Page> handler) | 移除页面崩溃事件的处理器 | 从 EventType.CRASH 事件中移除监听器 |
onDialog(Consumer<Dialog> handler) | 添加对话框事件处理器（如 alert/prompt） | 绑定 EventType.DIALOG 事件，必须通过 Dialog.accept()/dismiss() 处理对话框，否则页面冻结 |
offDialog(Consumer<Dialog> handler) | 移除对话框事件的处理器 | 从 EventType.DIALOG 事件中移除监听器 |
onDOMContentLoaded(Consumer<Page> handler) | 添加DOMContentLoaded 事件处理器 | 绑定 EventType.DOMCONTENTLOADED，DOM 加载完成时触发 |
offDOMContentLoaded(Consumer<Page> handler) | 移除 DOMContentLoaded 事件的处理器 | 从 EventType.DOMCONTENTLOADED 事件中移除监听器 |
onDownload(Consumer<Download> handler) | 添加文件下载事件处理器 | 绑定 EventType.DOWNLOAD，创建 DownloadImpl 实例并通知监听器 |
offDownload(Consumer<Download> handler) | 移除文件下载事件的处理器 | 从 EventType.DOWNLOAD 事件中移除监听器 |
onFileChooser(Consumer<FileChooser> handler) | 添加文件选择器事件处理器（如 <input type=file>） | 绑定 EventType.FILECHOOSER，创建 FileChooserImpl 实例并通知 |
offFileChooser(Consumer<FileChooser> handler) | 移除文件选择器事件的处理器 | 从 EventType.FILECHOOSER 事件中移除监听器 |
onFrameAttached(Consumer<Frame> handler) | 添加帧附加事件处理器 | 绑定 EventType.FRAMEATTACHED，帧附加到页面时触发（更新帧列表） |
offFrameAttached(Consumer<Frame> handler) | 移除帧附加事件的处理器 | 从 EventType.FRAMEATTACHED 事件中移除监听器 |
onFrameDetached(Consumer<Frame> handler) | 添加帧分离事件处理器 | 绑定 EventType.FRAMEDETACHED，帧从页面分离时触发（更新帧列表） |
offFrameDetached(Consumer<Frame> handler) | 移除帧分离事件的处理器 | 从 EventType.FRAMEDETACHED 事件中移除监听器 |
onFrameNavigated(Consumer<Frame> handler) | 添加帧导航事件处理器 | 绑定 EventType.FRAMENAVIGATED，帧导航到新 URL 时触发 |
offFrameNavigated(Consumer<Frame> handler) | 移除帧导航事件的处理器 | 从 EventType.FRAMENAVIGATED 事件中移除监听器 |
onLoad(Consumer<Page> handler) | 添加页面 load 事件处理器 | 绑定 EventType.LOAD，页面资源完全加载时触发 |
offLoad(Consumer<Page> handler) | 移除页面 load 事件的处理器 | 从 EventType.LOAD 事件中移除监听器 |
onPageError(Consumer<String> handler) | 添加页面错误事件处理器（如 JS 未捕获异常） | 绑定 EventType.PAGEERROR，接收错误信息字符串 |
offPageError(Consumer<String> handler) | 移除页面错误事件的处理器 | 从 EventType.PAGEERROR 事件中移除监听器 |
onPopup(Consumer<Page> handler) | 添加弹窗页面事件处理器 | 绑定 EventType.POPUP，页面打开新弹窗时触发 |
offPopup(Consumer<Page> handler) | 移除弹窗页面事件的处理器 | 从 EventType.POPUP 事件中移除监听器 |
onRequest(Consumer<Request> handler) | 添加请求发送事件处理器 | 绑定 EventType.REQUEST，页面发送请求时触发 |
offRequest(Consumer<Request> handler) | 移除请求发送事件的处理器 | 从 EventType.REQUEST 事件中移除监听器 |
onRequestFailed(Consumer<Request> handler) | 添加请求失败事件处理器（如网络错误） | 绑定 EventType.REQUESTFAILED，请求超时/失败时触发（HTTP 4xx/5xx 不算失败） |
offRequestFailed(Consumer<Request> handler) | 移除请求失败事件的处理器 | 从 EventType.REQUESTFAILED 事件中移除监听器 |
onRequestFinished(Consumer<Request> handler) | 添加请求完成事件处理器 | 绑定 EventType.REQUESTFINISHED，请求成功完成时触发 |
offRequestFinished(Consumer<Request> handler) | 移除请求完成事件的处理器 | 从 EventType.REQUESTFINISHED 事件中移除监听器 |
onResponse(Consumer<Response> handler) | 添加响应接收事件处理器 | 绑定 EventType.RESPONSE，页面收到响应头时触发 |
offResponse(Consumer<Response> handler) | 移除响应接收事件的处理器 | 从 EventType.RESPONSE 事件中移除监听器 |
onWebSocket(Consumer<WebSocket> handler) | 添加WebSocket 连接事件处理器 | 绑定 EventType.WEBSOCKET，WebSocket 连接建立时触发 |
offWebSocket(Consumer<WebSocket> handler) | 移除 WebSocket 连接事件的处理器 | 从 EventType.WEBSOCKET 事件中移除监听器 |
onWorker(Consumer<Worker> handler) | 添加WebWorker 启动事件处理器 | 绑定 |