快速入门
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-inappbrowser`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/inappbrowser/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
安装
“安装”章节你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins然后使用以下 prompt:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-inappbrowser` plugin in my project.如果你更想手动设置,请运行以下命令安装插件,并按照下方各平台的说明操作:
npm install @capgo/capacitor-inappbrowsernpx cap sync导入
“导入”章节import { InAppBrowser } from '@capgo/capacitor-inappbrowser';快速开始:在托管 WebView 中使用托管结账
章节标题:“快速开始:在受管 WebView 中使用托管结账”import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.openWebView({ url: 'https://billing.example.com/checkout', toolbarType: 'navigation', title: 'Checkout',});
InAppBrowser.addListener('urlChangeEvent', (event) => { if (event.url.includes('/success')) { InAppBrowser.close(); }});使用 open() 而是当你想使用 Safari View Controller 或 Chrome Custom Tabs,又不想嵌入完整的原生 WebView 栈时。
选择浏览器模式
章节标题:“选择浏览器模式”使用 open() 当你需要平台浏览器界面时:Android 上的 Chrome 自定义标签页(Custom Tabs)以及 SFSafariViewController 在 iOS 上。使用 openWebView() 当你的应用需要控制原生 WebView 时:自定义尺寸、工具栏、应用消息、JavaScript 注入、下载、代理、弹出窗口、隐藏实例或 UI 层叠。
常见用例
“常见用例”章节在实时浏览器页面之上显示 Ionic UI
章节标题:“在实时浏览器页面上方显示 Ionic UI”在 Capacitor 宿主 WebView 背后打开受管理的 WebView,使用 toBack。这样,你的 Ionic UI 就可以在页面之上渲染,同时网页内容保持在背后加载。使用 dispatchInputEvent() 当覆盖层需要与页面交互时,将手势转发给浏览器。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
const { id } = await InAppBrowser.openWebView({ url: 'https://example.com/checkout', toBack: true, transparentBackground: true,});
await InAppBrowser.dispatchInputEvent({ id, type: 'click', x: 160, y: 420,});
await InAppBrowser.bringToFront({ id });在浏览器需要显示的位置,将相关应用背景设为透明。当浏览器位于应用后方时,除非显式转发,否则原生手势仍由 Capacitor WebView 处理。
构建半屏浏览器或底部弹窗
章节标题:“构建半屏浏览器或 Bottom Sheet”设置 height, width, x,以及 y 让 Capacitor 应用的一部分在原生浏览器周围保持可见。在 Android 和 iOS 上,浏览器边框外的触摸会穿透到底层 Capacitor WebView。
const bottomGap = 200;
const { id } = await InAppBrowser.openWebView({ url: 'https://example.com/offers', height: window.innerHeight - bottomGap, y: 0,});
await InAppBrowser.updateDimensions({ id, height: window.innerHeight, y: 0,});适用于迷你浏览器、优惠面板、客服组件、由浏览器承载的 Bottom Sheet,或任何需要在 Web 内容外保持原生应用控件可点击的流程。
让 Checkout、Auth 或 Support 会话保持私密
章节标题:“保持结账、身份验证或客服会话私密”设置 persistWebViewData: false 适用于需要避免持久化网站数据(在平台支持的情况下)的受管 WebView。调用 clearAllBrowsingData() 在退出登录、切换账号、测试会话,或需要清除默认存储和已打开受管 WebView 的流程之后。
const { id } = await InAppBrowser.openWebView({ url: 'https://example.com/login', persistWebViewData: false,});
await InAppBrowser.clearAllBrowsingData();await InAppBrowser.close({ id });在 Android 上,Cookie 使用系统 WebView 的 Cookie 存储,因此 clearAllBrowsingData() 是清理 Cookie 及其他共享浏览器数据的步骤。
随时准备好多个浏览器实例
标题为“保持多个浏览器实例就绪”的章节使用 hidden, hide(),以及 show() 用于预加载或保留多个受管 WebView,而无需让每个都显示在屏幕上。隐藏的 WebView 仍可接收 executeScript(), postMessage(), setUrl(),以及 close 调用。
const first = await InAppBrowser.openWebView({ url: 'https://example.com/a', hidden: true });const second = await InAppBrowser.openWebView({ url: 'https://example.com/b', hidden: true });
await InAppBrowser.show({ id: first.id });await InAppBrowser.hide({ id: first.id });await InAppBrowser.show({ id: second.id });嵌入高级 Web App 流程
章节标题:“嵌入高级 Web 应用流程”组合代理规则, handleDownloads, openBlankTargetInWebView, hiddenPopupWindow, enableGooglePaySupport, postMessage(),以及 executeScript() 适用于文档门户、上传流程、支付页面、客服台以及其他需要在不离开应用的情况下进行原生控制的嵌入式 Web 应用。
const { id } = await InAppBrowser.openWebView({ url: 'https://example.com/portal', handleDownloads: true, openBlankTargetInWebView: true, hiddenPopupWindow: true, outboundProxyRules: [ { urlRegex: '^https://example\\.com/api/', action: 'delegateToJs', }, ],});
await InAppBrowser.postMessage({ id, detail: { source: 'app', action: 'refresh' },});API 概览
章节标题:“API 概览”goBack
“goBack”章节如果可能,则在 WebView 历史记录中返回上一页
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.goBack();open
“open”章节在新窗口中以全屏方式打开 URL;Android 上使用 Chrome Custom Tabs,iOS 上使用 SFSafariViewController
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.open({} as OpenOptions);clearCookies
标题为 “clearCookies” 的章节清除指定 url 的 cookies
当 id 被省略时,将应用于所有打开的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.clearCookies({} as ClearCookieOptions);clearAllCookies
标题为 “clearAllCookies” 的章节清除所有 cookies
当 id 被省略时,将应用于所有打开的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.clearAllCookies();clearCache
标题为 “clearCache” 的章节清除缓存
当 id 被省略时,将应用于所有打开的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.clearCache();clearAllBrowsingData
“clearAllBrowsingData” 章节清除默认存储区和已打开的受管 WebView 中的所有浏览数据,包括 Cookie、缓存、local storage、session storage、IndexedDB、表单数据,以及平台支持时的 HTTP 认证数据。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.clearAllBrowsingData();getCookies
“getCookies” 章节获取指定 URL 的 Cookie。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.getCookies({} as GetCookieOptions);close
“close” 章节关闭 webview。
当 id 省略时,关闭当前活动的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.close();hide
“hide” 章节隐藏 webview 而不关闭它。
使用 show() 重新显示。
当 id 若省略,则针对当前活跃的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.hide();show
“show” 章节显示之前隐藏的 webview。
当 id 若省略,则针对当前活跃的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.show();sendToBack
“sendToBack” 章节将原生浏览器移至 Capacitor 宿主 WebView 后方。当你的 Ionic UI 需要显示在实时浏览器页面之上时,请使用此功能。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.sendToBack({ id: 'webview-id', transparentBackground: true });bringToFront
“bringToFront” 章节将位于宿主 WebView 后方的浏览器移回最前端。当 id 若省略,则针对当前活跃的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.bringToFront({ id: 'webview-id' });dispatchInputEvent
标题为 “dispatchInputEvent” 的章节向受管理的浏览器分发点击、触摸或滚动事件。坐标相对于浏览器视口,单位为 CSS 像素。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.dispatchInputEvent({ id: 'webview-id', type: 'click', x: 160, y: 420,});openWebView
标题为 “openWebView” 的章节在新的 webview 中打开 URL,支持工具栏及增强功能,如摄像头访问、文件访问、事件监听、注入 JavaScript、双向通信等。
JavaScript 接口: 使用此方法打开 webview 时,会自动注入一个 JavaScript 接口,提供以下功能:
window.mobileApp.close():从 JavaScript 关闭 webviewwindow.mobileApp.postMessage({detail: {message: "myMessage"}}):从 webview 向应用发送消息,detail 对象即是要发送到 webview 的数据window.mobileApp.takeScreenshot()何时allowScreenshotsFromWebPage为 true 时
Promise 的时序会因平台而异,当 isPresentAfterPageLoad 被使用时。
Android 解析为 { id } 在对话框可控制后解析,而 iOS 解析为 { id } 在创建原生 webview 后立即解析。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.openWebView({} as OpenWebViewOptions);executeScript
标题为 “executeScript” 的章节将 JavaScript code 注入到 InAppBrowser 窗口中。
当 id 省略时,会在所有打开的 webview 中执行。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.executeScript({} as { code: string; id?: string });postMessage
标题为 “postMessage” 的章节向 webview(应用内浏览器)发送事件。在 webview 的 JavaScript 中,用以下方式监听: window.addEventListener('messageFromNative', listenerFunc).
detail 是发送到 webview 的 payload。由于要经过 Capacitor bridge,它必须可 JSON 序列化。
当 id 若省略,则广播到所有已打开的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.postMessage({} as { detail: Record<string, any>; id?: string });takeScreenshot
标题为 “takeScreenshot” 的章节将当前 webview 视口截取为 PNG 截图。
当 id 若省略,则针对当前活跃的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.takeScreenshot();setUrl
标题为 “setUrl” 的章节设置 webview 的 URL。
当 id 若省略,则针对当前活跃的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.setUrl({} as { url: string; id?: string });handleProxyRequest
标题为 “handleProxyRequest” 的章节由……使用的内部方法 addProxyHandler() 以将代理决策返回给原生层。
转发原始 phase 回复手册时 proxyRequest 监听器相同。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.handleProxyRequest({} as { requestId: string; decision?: ProxyDecision | null; response?: ProxyResponse | null; webviewId?: string; phase?: 'outbound' | 'inbound'; });reload
标题为 “reload” 的章节重新加载当前网页。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.reload();updateDimensions
标题为 “updateDimensions” 的章节更新 webview 的尺寸。
允许在运行时更改 webview 的大小和位置。
当 id 若省略,则针对当前活跃的 webview。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.updateDimensions({} as DimensionOptions & { id?: string });setEnabledSafeTopMargin
标题为 “setEnabledSafeTopMargin” 的章节在运行时设置 webview 是否启用顶部安全边距。
当 id 被省略时,将指向当前活动的 webview。
在 Web 上,此方法为空操作,解析时不会更改布局。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.setEnabledSafeTopMargin({} as { enabled: boolean; id?: string });setEnabledSafeBottomMargin
标题为“setEnabledSafeBottomMargin”的章节在运行时设置 webview 的安全底部边距。
当 id 被省略时,将指向当前活动的 webview。
在 Web 上,此方法为空操作,解析时不会更改布局。
import { InAppBrowser } from '@capgo/capacitor-inappbrowser';
await InAppBrowser.setEnabledSafeBottomMargin({} as { enabled: boolean; id?: string });openSecureWindow
标题为“openSecureWindow”的章节打开一个用于 OAuth2 认证的安全窗口。 对于 Web,您应在重定向页面中包含 code,以使用广播通道将重定向 URL 发送给应用 例如:
<html><head></head><body><script> const searchParams = new URLSearchParams(location.search) if (searchParams.has("code")) { new BroadcastChannel("my-channel-name").postMessage(location.href); window.close(); }</script></body></html>