概览
“概览”章节@capgo/capacitor-inappbrowser 为 Capacitor 应用提供两种浏览器路径: open() 用于系统浏览器体验,以及 openWebView() 用于受管理的原生 WebView,您的应用可以调整其大小、隐藏、发送消息、执行脚本、代理请求,并与 Ionic UI 进行图层叠加。
当页面需要超越简单外部浏览器的功能时使用它:OAuth 和结账流程、嵌入式支持门户、支付界面、视频通话、文档门户、交互式 Web 应用,或任何需要您的应用围绕实时 Web 内容提供原生控制的流程。
包名已更改。常见用例
“常见用例”章节- 使用以下命令在实时浏览器页面上方呈现 Ionic 或 Capacitor UI:
toBack,sendToBack(),bringToFront(),transparentBackground,以及dispatchInputEvent(). - 使用以下命令构建部分屏幕浏览器、底部抽屉和画中画 WebView:
width,height,x,y,以及updateDimensions(). - 在 Android 和 iOS 上,让用户点击 Capacitor 应用时,在自定义尺寸的浏览器窗口中打开。
- 使用 运行结账、登录、支持或账户切换流程,无需持久化网站存储
persistWebViewData: false以及clearAllBrowsingData(). - 同时加载多个浏览器实例
hidden,hide(),以及show()同时保留页面状态。 - 嵌入需要请求代理、文件上传、下载、弹窗控制、Google Pay 支持的复杂 Web 应用,
_blank以及链接处理和 App 与页面间的消息传递。
核心功能
标题为“核心功能”的章节open- 在 Android 上使用 Chrome Custom Tabs 打开 URL,或在SFSafariViewController在 iOS 上协调。openWebView- 打开受管理的原生 WebView,支持自定义工具栏、尺寸调整、原生导航、消息传递、脚本执行、代理、下载、弹窗及数据控制。sendToBack/bringToFront- 将受管理的浏览器移动到 Capacitor 宿主 WebView 的后方或前方。dispatchInputEvent- 将点击、触摸和滚动事件转发给位于原生应用 UI 后方的浏览器。updateDimensions- 在不重新加载页面的情况下,更改受管理 WebView 的大小和位置。hide/show- 在移除或恢复原生呈现层时,保持受管理的 WebView 处于加载状态。postMessage/executeScript- 连接 Capacitor 应用与在受管理页面内运行的 JavaScript。clearAllBrowsingData/persistWebViewData- 控制 Cookie、缓存、存储、IndexedDB 和会话持久化。handleDownloads、代理规则和弹窗事件 - 支持文档门户、上传流程、支付页面和嵌入式 Web 应用。
公开 API
标题为“公开 API”的章节| 方法 | 描述 |
|---|---|
goBack | 如果可能,在 WebView 历史记录中后退。 |
open | 在新窗口中全屏打开 URL。在 Android 上使用 Chrome 自定义标签页,在 iOS 上使用 SFSafariViewController。 |
clearCookies | 清除 URL 的 Cookie。当 id 被省略时,适用于所有打开的 WebView。 |
clearAllCookies | 清除所有 Cookie。当 id 被省略时,适用于所有打开的 WebView。 |
clearCache | 清除缓存。当 id 被省略时,适用于所有打开的 WebView。 |
clearAllBrowsingData | 从默认存储和受管理的 WebView 中清除 Cookie、缓存、本地存储、会话存储、IndexedDB 及其他浏览数据。 |
getCookies | 获取指定 URL 的 Cookie。 |
close | 关闭 WebView。当 id 省略时,关闭当前活动的 webview。 |
hide | 隐藏 webview 而不关闭它。使用 show() 将其重新显示。当 id 若省略,则针对当前活跃的 webview。 |
show | 显示之前隐藏的 webview。当 id 若省略,则针对当前活跃的 webview。 |
sendToBack | 将原生浏览器移至 Capacitor 宿主 WebView 之后,以便应用 UI 显示在其上方。 |
bringToFront | 将位于宿主 WebView 之后的浏览器移回前台。 |
dispatchInputEvent | 向受管理的浏览器分发点击、触摸或滚动输入;坐标相对于浏览器视口。 |
openWebView | 在新的 webview 中打开 url,带有工具栏和增强功能,如摄像头访问、文件访问、监听事件、注入 JavaScript、双向通信等。 |
executeScript | 向 InAppBrowser 窗口注入 JavaScript code。当 id 省略时,会在所有打开的 webview 中执行。 |
postMessage | 向 webview(应用内浏览器)发送事件。在页面中监听 window.addEventListener('messageFromNative', listenerFunc)。该 detail payload 必须是可 JSON 序列化的。当 id 若省略,则广播到所有已打开的 webview。 |
takeScreenshot | 将当前 webview 视口截取为 PNG 截图。当 id 若省略,则针对当前活跃的 webview。 |
setUrl | 设置 webview 的 URL。当 id 若省略,则针对当前活跃的 webview。 |
addListener | 监听 URL 变化,仅适用于 openWebView。 |
addListener | 监听 buttonNearDoneClick;payload 包含 webview id. |
addListener | 监听关闭点击,仅适用于 openWebView。 |
addListener | 当需要显示免责声明且用户点击确认按钮时触发,可与 openWebView 的 shareDisclaimer 和 closeModal 配合使用。 |
addListener | 当 webview 向 App 回传事件时触发。使用 window.mobileApp.postMessage(...) 在页面中,并确保 payload 可 JSON 序列化。 |
addListener | 每当通过 API 插件、原生截图按钮或注入的 JavaScript bridge 捕获截图时触发。 |
addListener | 页面加载完成时触发。 |
addListener | 页面加载出错时触发。 |
addListener | 原生下载处理将文件保存到本地后触发。可通过以下方式启用: handleDownloads: true 打开 webview 时。 |
addListener | 原生下载处理失败时触发。可通过以下方式启用: handleDownloads: true 打开 webview 时。 |
addListener | 每当页面打开弹窗/新窗口时触发。将返回的 popup id 与以下配合使用: executeScript, postMessage, show, hide,以及 close. |
addListener | 监听由原生运行时委托的代理请求。建议优先使用 addProxyHandler() 而不是直接调用此方法。 |
addListener | 监听托管页面输出的 JavaScript console 日志。可通过以下方式启用: captureConsoleLogs: true 打开 webview 时。 |
handleProxyRequest | 内部方法,供 addProxyHandler() 将代理决策返回给原生层。请转发原始的 phase 回复手册时 proxyRequest 监听器相同。 |
removeAllListeners | 移除该插件的所有监听器。 |
reload | 重新加载当前网页。 |
updateDimensions | 更新 webview 的尺寸。允许在运行时更改 webview 的大小和位置。当 id 若省略,则针对当前活跃的 webview。 |
setEnabledSafeTopMargin | 在运行时设置 webview 的启用安全顶部边距。当 id 被省略时,将指向当前活动的 webview。在 Web 上,此方法为空操作,解析时不会更改布局。 |
setEnabledSafeBottomMargin | 在运行时设置 webview 的安全底部边距。当 id 被省略时,将指向当前活动的 webview。在 Web 上,此方法为空操作,解析时不会更改布局。 |
openSecureWindow | 打开一个安全的 OAuth2 窗口。在 Web 上,通过 BroadcastChannel返回重定向后的 URL;在移动端,请在应用配置中注册自定义重定向 URI。完整的 HTML、Info.plist 和 AndroidManifest 示例请参阅入门指南。 |
参考值
标题为“参考值”的章节在打开应用内浏览器或 WebView 时,将这些值与工具栏选项配合使用。
工具栏类型
标题为“工具栏类型”的章节| 值 | 用户会发现 |
|---|---|
activity | 带有关闭和分享控件的简单工具栏。 |
compact | 带有关闭控件的简单工具栏。 |
navigation | 带有后退和前进控件的完整导航工具栏。 |
blank | 无工具栏。 |
单一事实来源
标题为“单一事实来源”的部分此参考文档同步自 src/definitions.ts 中的 capacitor-inappbrowser.
继续了解 @capgo/capacitor-inappbrowser
标题为“继续了解 @capgo/capacitor-inappbrowser”的章节如果你正在使用 @capgo/capacitor-inappbrowser 要规划原生插件工作,请将其与 使用 @capgo/capacitor-inappbrowser 关于使用 @capgo/capacitor-inappbrowser 时的原生能力, Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 关于“添加或更新插件”中的实现细节,以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。