@capgo/capacitor-inappbrowser

概览

@capgo/capacitor-inappbrowser 为 Capacitor 应用提供两种浏览器路径： open() 用于系统浏览器体验，以及 openWebView() 用于受控的原生 WebView，您的应用可以对其进行尺寸调整、隐藏、消息传递、脚本注入、代理，并与 Ionic UI 进行图层叠加。

当页面需求超出简单的外部浏览器时请使用它：例如 OAuth 和结账流程、嵌入式支持门户、支付界面、视频通话、文档门户、交互式 Web 应用，或任何需要应用在实时 Web 内容周围提供原生控制的流程。

包名已更改。

常见用例

• 通过以下方式在实时浏览器页面上展示 Ionic 或 Capacitor UI： toBack, sendToBack(), bringToFront(), transparentBackground，以及 dispatchInputEvent().
• 使用以下方式构建部分屏幕浏览器、底部抽屉 (bottom sheets) 和画中画 (picture-in-picture) WebView： width, height, x, y，以及 updateDimensions().
• 允许用户在 Android 和 iOS 上点击自定义尺寸浏览器窗口之外的 Capacitor 应用。
• Run checkout, login, support, or account-switching flows without persistent website storage using persistWebViewData: false 以及 clearAllBrowsingData().
• Keep multiple browser instances loaded with hidden, hide()，以及 show() 同时保留页面状态。
• 嵌入需要请求代理、文件 upload、download、弹窗控制、Google Pay 支持、 _blank 链接处理以及 app-to-page 消息传递的高级 Web 应用。

核心功能

• open - 在 Android 上通过 Chrome Custom Tabs 打开 URL，或 SFSafariViewController 在 iOS 上协调。
• openWebView - 使用带有自定义工具栏、尺寸控制、原生导航、消息传递、脚本、代理、download、弹窗和数据控制的管理型原生 WebView 打开。
• sendToBack / bringToFront - 将托管浏览器移动到 Capacitor host WebView 的下方或上方。
• dispatchInputEvent - 将点击、触摸和滚动事件转发到位于原生 App UI 后方的浏览器。
• updateDimensions - 在不重新加载页面的情况下，更改托管 WebView 的大小和位置。
• hide / show - 在移除或恢复原生视图显示的同时，保持托管 WebView 的加载状态。
• postMessage / executeScript - 将 Capacitor App 与托管页面内运行的 JavaScript 连接起来。
• clearAllBrowsingData / persistWebViewData - 控制 Cookie、缓存、存储、IndexedDB 和会话持久化。
• handleDownloads, 代理规则和弹窗事件 - 支持文档门户、upload 流程、支付页面和嵌入式 Web App。

公开 API

方法	描述
goBack	如果可能，在 WebView 的历史记录中返回上一页。
open	在新窗口中全屏打开 URL。Android 端使用 Chrome Custom Tabs，iOS 端使用 SFSafariViewController。
clearCookies	清除 URL 的 Cookie。当 id 被省略时，将应用于所有已打开的 WebView。
clearAllCookies	清除所有 Cookie。当 id 被省略时，将应用于所有已打开的 WebView。
clearCache	清除缓存。当 id 被省略时，将应用于所有已打开的 WebView。
clearAllBrowsingData	清除默认存储和受管 WebView 中的 Cookie、缓存、local storage、session storage、IndexedDB 及其他浏览数据。
getCookies	获取指定 URL 的 Cookie。
close	关闭 WebView。当 id 省略时，关闭当前活动的 webview。
hide	隐藏 WebView 而不关闭。使用 show() 重新显示。当 id 若省略，则针对当前活跃的 webview。
show	显示之前隐藏的 webview。当 id 若省略，则针对当前活跃的 webview。
sendToBack	将原生浏览器移至 Capacitor host WebView 后方，以便 app UI 能够覆盖在其上方。
bringToFront	将原本位于 host WebView 后方的浏览器移回至最前端。
dispatchInputEvent	将点击、触摸或滚动输入分发至受管理的浏览器；坐标相对于浏览器视口（viewport）。
openWebView	在带有工具栏的新 webview 中打开 URL，并提供增强功能，如相机访问、文件访问、监听事件、注入 JavaScript、双向通信等。
executeScript	将 JavaScript code 注入 InAppBrowser 窗口。当 id 被省略时，将在所有打开的 webviews 中执行。
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 端，此方法不执行任何操作并直接 resolve。
setEnabledSafeBottomMargin	在运行时设置 webview 已启用的底部安全边距。当 id 若省略，则指向当前的 webview。在 Web 端，此方法不执行任何操作，且会在不改变布局的情况下直接 resolve。
openSecureWindow	Opens a secure OAuth2 window. On web, return the redirected URL through a BroadcastChannel在移动端，请在应用配置中注册自定义重定向 URI。有关 HTML、Info.plist 和 AndroidManifest 的完整示例，请参阅入门指南。

参考值

在打开 in-app browser 或 WebView 时，配合 toolbar 选项使用这些值。

Toolbar 类型

值	用户会发现
activity	包含关闭和分享控件的简单 toolbar。
compact	包含关闭控件的简单 toolbar。
navigation	包含前进和后退控制功能的完整导航工具栏。
blank	无工具栏。

单一事实来源

此参考文档同步自 src/definitions.ts 中的 capacitor-inappbrowser.

从 @capgo/capacitor-inappbrowser 继续

如果你正在使用 @capgo/capacitor-inappbrowser 要规划原生插件工作，请将其与 使用 @capgo/capacitor-inappbrowser 关于使用 @capgo/capacitor-inappbrowser 时的原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。