开始使用

1. 安装包

   npm

   npm i @capgo/inappbrowser

   pnpm

   pnpm add @capgo/inappbrowser

   yarn

   yarn add @capgo/inappbrowser

   bun

   bun add @capgo/inappbrowser

2. 与原生项目同步

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

使用

导入插件并使用其两个主要入口点：

import { InAppBrowser, ToolBarType, BackgroundColor } from '@capgo/inappbrowser';

// 1) 简单的自定义标签 / SFSafariViewController
const openExternal = async () => {
  await InAppBrowser.open({
    url: 'https://capgo.app',
    isPresentAfterPageLoad: true,
    preventDeeplink: false,
  });
};

// 2) 带导航、标题、分享、消息传递等的完整 WebView
const openWebView = async () => {
  await InAppBrowser.openWebView({
    url: 'https://capgo.app',
    title: 'Capgo',
    toolbarType: ToolBarType.NAVIGATION,
    backgroundColor: BackgroundColor.BLACK,
    activeNativeNavigationForWebview: true,
    showReloadButton: true,
    shareSubject: 'Check this page',
    shareDisclaimer: {
      title: 'Disclaimer',
      message: 'You are about to share content',
      confirmBtn: 'Continue',
      cancelBtn: 'Cancel',
    },
  });
};

// 应用和打开的 WebView 之间的消息传递
const setupListeners = async () => {
  await InAppBrowser.addListener('urlChangeEvent', (event) => {
    console.log('URL changed to:', event.url);
  });

  await InAppBrowser.addListener('messageFromWebview', (event) => {
    console.log('Message from web:', event.detail);
  });

  await InAppBrowser.addListener('closeEvent', () => {
    console.log('WebView closed');
  });
};

// 向 WebView 发送数据
const sendData = async () => {
  await InAppBrowser.postMessage({ detail: { action: 'refresh-profile' } });
};

// 关闭和重新加载助手
const closeBrowser = () => InAppBrowser.close();
const reloadPage = () => InAppBrowser.reload();

API 参考

open(options: OpenOptions)

在自定义标签 / SFSafariViewController 中打开 URL。

interface OpenOptions {
  /** 要加载的目标 URL */
  url: string;
  /** 页面加载完成后呈现 */
  isPresentAfterPageLoad?: boolean;
  /** 防止深层链接打开外部应用 */
  preventDeeplink?: boolean;
}

await InAppBrowser.open({ url: 'https://example.com', preventDeeplink: true });

openWebView(options: OpenWebViewOptions)

加载具有导航 UI、标题、凭据、脚本和消息传递的全功能 WebView。

interface OpenWebViewOptions {
  url: string;
  headers?: Record<string, string>;
  credentials?: { username: string; password: string };
  materialPicker?: boolean;
  shareDisclaimer?: {
    title: string;
    message: string;
    confirmBtn: string;
    cancelBtn: string;
  };
  toolbarType?: ToolBarType;
  shareSubject?: string;
  title?: string;
  backgroundColor?: BackgroundColor;
  activeNativeNavigationForWebview?: boolean;
  disableGoBackOnNativeApplication?: boolean;
  isPresentAfterPageLoad?: boolean;
  isInspectable?: boolean;
  isAnimated?: boolean;
  showReloadButton?: boolean;
  closeModal?: boolean;
  closeModalTitle?: string;
  closeModalDescription?: string;
  closeModalOk?: string;
  closeModalCancel?: string;
  visibleTitle?: boolean;
  toolbarColor?: string;
  toolbarTextColor?: string;
  showArrow?: boolean;
  ignoreUntrustedSSLError?: boolean;
  preShowScript?: string;
  preShowScriptInjectionTime?: 'documentStart' | 'pageLoad';
  proxyRequests?: string;
  buttonNearDone?: {
    ios: { iconType: 'sf-symbol' | 'asset'; icon: string };
    android: { iconType: 'asset' | 'vector'; icon: string; width?: number; height?: number };
  };
  textZoom?: number;
  preventDeeplink?: boolean;
  authorizedAppLinks?: string[];
  enabledSafeBottomMargin?: boolean;
  useTopInset?: boolean;
  enableGooglePaySupport?: boolean;
  blockedHosts?: string[];
  width?: number;
  height?: number;
  x?: number;
  y?: number;
}

await InAppBrowser.openWebView({
  url: 'https://new-page.com',
  toolbarType: ToolBarType.NAVIGATION,
  showReloadButton: true,
});

ToolBarType 值：activity（关闭 + 分享）、compact（仅关闭）、navigation（后退/前进 + 关闭）、blank（无工具栏）。BackgroundColor 值：white 或 black。

close(options?)

关闭 WebView/自定义标签。

选项：

• isAnimated?: boolean - 是否为关闭操作添加动画

reload()

重新加载当前的 WebView 页面。

goBack()

在 WebView 历史记录中后退并返回 { canGoBack: boolean }。

setUrl({ url: string })

替换当前的 WebView URL。

executeScript({ code: string })

向 WebView 注入 JavaScript。

postMessage({ detail: Record<string, any> })

从原生应用向 WebView 发送数据（通过 window.addEventListener('messageFromNative', ...) 在 JS 中接收）。

getCookies({ url, includeHttpOnly? })

返回 URL 的 cookie。

clearCookies({ url }) / clearAllCookies() / clearCache()

Cookie 和缓存管理助手。

updateDimensions(options: DimensionOptions)

在运行时更改 WebView 大小/位置（width、height、x、y）。

removeAllListeners()

注销插件的所有监听器。

事件

urlChangeEvent

在浏览器中 URL 更改时触发。

interface UrlChangeEvent {
  url: string;
}

InAppBrowser.addListener('urlChangeEvent', (event) => {
  console.log('New URL:', event.url);
});

messageFromWebview

在 WebView 内调用 window.mobileApp.postMessage(...) 时触发。

InAppBrowser.addListener('messageFromWebview', (event) => {
  console.log('Payload from web:', event.detail);
});

closeEvent

浏览器关闭时触发。

InAppBrowser.addListener('closeEvent', () => {
  console.log('Browser closed');
});

buttonNearDoneClick

按下使用 buttonNearDone 添加的自定义按钮时触发。

InAppBrowser.addListener('buttonNearDoneClick', (event) => {
  console.log('Button near done tapped', event);
});

confirmBtnClicked

接受确认对话框（免责声明或关闭模态框）时触发。

InAppBrowser.addListener('confirmBtnClicked', (event) => {
  console.log('Confirm accepted, current URL:', event.url);
});

browserPageLoaded / pageLoadError

WebView 加载成功或失败的生命周期事件。

InAppBrowser.addListener('browserPageLoaded', () => console.log('Page loaded'));
InAppBrowser.addListener('pageLoadError', () => console.log('Page failed to load'));

高级用法

OAuth 流程实现

import { InAppBrowser } from '@capgo/inappbrowser';

export class OAuthService {
  private listeners: any[] = [];

  async authenticate(authUrl: string, redirectUri: string) {
    return new Promise<string>((resolve, reject) => {
      // 监听 URL 更改
      const urlListener = InAppBrowser.addListener('urlChangeEvent', (event) => {
        if (event.url.startsWith(redirectUri)) {
          // 从 URL 提取 OAuth 代码/令牌
          const url = new URL(event.url);
          const code = url.searchParams.get('code');

          if (code) {
            InAppBrowser.close();
            resolve(code);
          } else {
            const error = url.searchParams.get('error');
            reject(new Error(error || 'OAuth failed'));
          }
        }
      });

      this.listeners.push(urlListener);

      // 打开 OAuth 提供商
      InAppBrowser.open({
        url: authUrl,
        preventDeeplink: true,
      });
    });
  }

  cleanup() {
    this.listeners.forEach(listener => listener.remove());
    this.listeners = [];
  }
}

自定义浏览器 UI

const openCustomBrowser = async () => {
  await InAppBrowser.open({
    url: 'https://example.com',
    isPresentAfterPageLoad: true,
    preventDeeplink: false,
  });
};

处理外部链接

import { InAppBrowser } from '@capgo/inappbrowser';

export class LinkHandler {
  async openExternalLink(url: string) {
    // 检查 URL 是否应在浏览器中打开
    if (this.shouldOpenInBrowser(url)) {
      await InAppBrowser.open({
        url,
        preventDeeplink: true,
      });
    } else {
      // 在内部处理
      window.location.href = url;
    }
  }

  private shouldOpenInBrowser(url: string): boolean {
    // 外部域
    const externalDomains = ['youtube.com', 'twitter.com', 'facebook.com'];
    const urlDomain = new URL(url).hostname;

    return externalDomains.some(domain => urlDomain.includes(domain));
  }
}

最佳实践

1. 始终移除监听器

   const listener = await InAppBrowser.addListener('urlChangeEvent', handler);
   // 完成后
   listener.remove();

2. 处理浏览器状态

   let browserOpen = false;
   
   const launch = async () => {
     browserOpen = true;
     await InAppBrowser.openWebView({ url: 'https://example.com' });
   };
   
   InAppBrowser.addListener('closeEvent', () => {
     browserOpen = false;
   });

3. 在打开前验证 URL

   const isValidUrl = (url: string): boolean => {
     try {
       new URL(url);
       return true;
     } catch {
       return false;
     }
   };
   
   if (isValidUrl(url)) {
     await InAppBrowser.open({ url });
   }

4. 为平台自定义

   import { Capacitor } from '@capacitor/core';
   
   const options = {
     url: 'https://example.com',
     preventDeeplink: Capacitor.getPlatform() === 'ios',
   };

平台说明

iOS

• 使用 SFSafariViewController
• 支持 iOS 11.0+
• 尊重安全区域插图
• 支持自定义呈现样式

Android

• 使用 Chrome Custom Tabs
• 如果 Chrome 不可用，则回退到 WebView
• 支持 Android 5.0（API 21）+
• 通过 toolbarType、toolbarColor、buttonNearDone 等支持工具栏自定义

Web

• 在新的浏览器标签/窗口中打开
• 有限的自定义选项
• 无 URL 更改事件