跳转到正文

@capgo/capacitor-inappbrowser

适用于 Capacitor 的原生应用内浏览器,支持受管理的 WebView、原生 UI 分层、私密会话、代理、下载、弹窗和应用消息传递。

@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 应用。
方法描述
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 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 关于“添加或更新插件”中的实现细节,以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。