快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx 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-webview-guardian` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-webview-guardian
bunx cap sync

导入

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

快速入门

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.startMonitoring();
console.log(result);

示例：stopMonitoring

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.stopMonitoring();
console.log(result);

示例：getState

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.getState();
console.log(result);

常见坑点

• 监听器: 在页面卸载时移除句柄。
• 原生同步：运行 bunx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

API 概览

startMonitoring

开始监听前台事件并自动检查 WebView 健康状态。

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.startMonitoring();
console.log(result);

stopMonitoring

停止所有自动前台监控。

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.stopMonitoring();
console.log(result);

getState

返回当前已知的最新监控状态。

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.getState();
console.log(result);

checkNow

立即强制触发一次 WebView 健康探测。

import { WebviewGuardian } from '@capgo/capacitor-webview-guardian';

const result = await WebviewGuardian.checkNow();
console.log(result);

类型参考

StartMonitoringOptions

export interface StartMonitoringOptions {
  /**
   * Delay (in ms) before running a health check after the app re-enters the foreground.
   * Defaults to 600ms to let the bridge finish resuming.
   */
  foregroundDebounceMs?: number;

  /**
   * Script executed via `evaluateJavascript`/`evaluateJavaScript` to confirm the WebView is alive.
   * Defaults to `document.readyState`.
   */
  pingScript?: string;

  /**
   * Automatically reloads the WebView when a terminated render process is detected.
   * Disable to receive `webviewCrashed` events and restart manually.
   */
  autoRestart?: boolean;

  /**
   * Strategy used when restarting the WebView. Defaults to `reload`.
   */
  restartStrategy?: RestartStrategy;

  /**
   * Custom HTTPS/HTTP URL to load when `restartStrategy` is `customUrl`.
   */
  customRestartUrl?: string;

  /**
   * Emits verbose logging in the native layer when true.
   */
  debug?: boolean;

  /**
   * Whether an immediate health check should be executed right after enabling monitoring.
   * Defaults to `true`.
   */
  runInitialCheck?: boolean;
}

GuardianState

export interface GuardianState {
  monitoring: boolean;
  reason: string;
  timestamp: string;
  lastHealthyAt?: string;
  lastRestartAt?: string;
  lastCrashAt?: string;
  pendingRestartReason?: string;
  error?: string;
}

CheckNowOptions

export interface CheckNowOptions {
  /**
   * Text tag describing why a manual check is being requested.
   */
  reason?: string;
}

CheckResult

export interface CheckResult {
  healthy: boolean;
  restarted: boolean;
  reason: string;
  timestamp: string;
  error?: string;
  pendingRestart?: boolean;
}

GuardianEvent

export type GuardianEvent = GuardianState;

RestartStrategy

export type RestartStrategy = 'reload' | 'reloadFromOrigin' | 'customUrl';

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 来规划原生媒体和界面行为，并将其与 使用 @capgo/capacitor-webview-guardian 在使用 @capgo/capacitor-webview-guardian 时，获取原生能力的方法： 使用 @capgo/capacitor-live-activities 用于使用 @capgo/capacitor-live-activities 时的原生能力， @capgo/capacitor-live-activities 在 @capgo/capacitor-live-activities 中的实现细节， 使用 @capgo/capacitor-video-player 有关使用 @capgo/capacitor-video-player 时的原生能力，以及 @capgo/capacitor-video-player 关于 @capgo/capacitor-video-player. 中的实现细节