版本：v8

@capacitor/app

App API 负责处理应用的高级状态和事件。例如，当应用进入或离开前台时，该 API 会发出事件，同时处理深度链接、打开其他应用以及管理持久化的插件状态。

安装

npm install @capacitor/app
npx cap sync

iOS

要能够通过自定义协议（scheme）打开应用，你需要先注册该协议。你可以通过编辑 Info.plist 文件并添加以下行来实现。

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.getcapacitor.capacitor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>mycustomscheme</string>
    </array>
  </dict>
</array>

Android

要能够通过自定义协议（scheme）打开应用，你需要先注册该协议。你可以通过在 AndroidManifest.xml 的 activity 部分内添加以下行来实现。

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="@string/custom_url_scheme" />
</intent-filter>

custom_url_scheme 的值存储在 strings.xml 中。当添加 Android 平台时，@capacitor/cli 会将应用的包名作为默认值添加，但可以通过编辑 strings.xml 文件来替换。

示例

import { App } from '@capacitor/app';

App.addListener('appStateChange', ({ isActive }) => {
  console.log('应用状态已改变。是否处于活动状态？', isActive);
});

App.addListener('appUrlOpen', data => {
  console.log('应用通过 URL 打开：', data);
});

App.addListener('appRestoredResult', data => {
  console.log('恢复的状态：', data);
});

const checkAppLaunchUrl = async () => {
  const { url } = await App.getLaunchUrl();

  console.log('应用通过 URL 打开：' + url);
};

配置

属性	类型	描述	默认值	始于
`disableBackButtonHandler`	`boolean`	禁用插件默认的后退按钮处理。仅适用于 Android。	`false`	7.1.0

示例

在 capacitor.config.json 中：

{
  "plugins": {
    "App": {
      "disableBackButtonHandler": true
    }
  }
}

在 capacitor.config.ts 中：

/// <reference types="@capacitor/app" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    App: {
      disableBackButtonHandler: true,
    },
  },
};

export default config;

exitApp()

exitApp() => Promise<void>

强制退出应用。此方法应仅与 Android 的 backButton 处理器结合使用，以便在导航完成后退出应用。

如果使用 Ionic，Ionic 会自行处理此操作，因此你不需要调用此方法。

始于： 1.0.0

getInfo()

getInfo() => Promise<AppInfo>

返回关于应用的信息。

返回：

Promise<AppInfo>

始于： 1.0.0

getState()

getState() => Promise<AppState>

获取当前应用状态。

返回：

Promise<AppState>

始于： 1.0.0

getLaunchUrl()

getLaunchUrl() => Promise<AppLaunchUrl | undefined>

获取应用启动时使用的 URL（如果有）。

返回：

Promise<AppLaunchUrl>

始于： 1.0.0

minimizeApp()

minimizeApp() => Promise<void>

最小化应用。

仅适用于 Android。

始于： 1.1.0

toggleBackButtonHandler(...)

toggleBackButtonHandler(options: ToggleBackButtonHandlerOptions) => Promise<void>

在运行时启用或禁用插件的后退按钮处理功能。

仅适用于 Android。

参数	类型
`options`	`ToggleBackButtonHandlerOptions`

始于： 7.1.0

--------------------### addListener('appStateChange', ...)

addListener(eventName: 'appStateChange', listenerFunc: StateChangeListener) => Promise<PluginListenerHandle>

监听应用或活动状态的变化。

在 iOS 上，当原生的 UIApplication.willResignActiveNotification 和 UIApplication.didBecomeActiveNotification 事件触发时，此监听器将被触发。在 Android 上，当 Capacitor 的 Activity onResume 和 onStop 方法被调用时，此监听器将被触发。在 Web 上，当文档的 visibilitychange 事件触发时，此监听器将被触发。

参数	类型
`eventName`	`'appStateChange'`
`listenerFunc`	`StateChangeListener`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('pause', ...)

addListener(eventName: 'pause', listenerFunc: () => void) => Promise<PluginListenerHandle>

监听应用或活动进入暂停状态时的事件。

在 iOS 上，当原生的 UIApplication.didEnterBackgroundNotification 事件触发时，此监听器将被触发。在 Android 上，当 Capacitor 的 Activity onPause 方法被调用时，此监听器将被触发。在 Web 上，当文档的 visibilitychange 事件触发且 document.hidden 为 true 时，此监听器将被触发。

参数	类型
`eventName`	`'pause'`
`listenerFunc`	`() => void`

返回值：

Promise<PluginListenerHandle>

自版本： 4.1.0

addListener('resume', ...)

addListener(eventName: 'resume', listenerFunc: () => void) => Promise<PluginListenerHandle>

监听应用或活动恢复运行时的事件。

在 iOS 上，当原生的 UIApplication.willEnterForegroundNotification 事件触发时，此监听器将被触发。在 Android 上，当 Capacitor 的 Activity onResume 方法被调用时，此监听器将被触发，但仅在 resume 事件首次触发之后触发。在 Web 上，当文档的 visibilitychange 事件触发且 document.hidden 为 false 时，此监听器将被触发。

参数	类型
`eventName`	`'resume'`
`listenerFunc`	`() => void`

返回值：

Promise<PluginListenerHandle>

自版本： 4.1.0

addListener('appUrlOpen', ...)

addListener(eventName: 'appUrlOpen', listenerFunc: URLOpenListener) => Promise<PluginListenerHandle>

监听应用的 URL 打开事件。此功能同时处理自定义 URL 方案链接以及您的应用所处理的 URL（在 iOS 上是 Universal Links，在 Android 上是 App Links）。

参数	类型
`eventName`	`'appUrlOpen'`
`listenerFunc`	`URLOpenListener`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('appRestoredResult', ...)

addListener(eventName: 'appRestoredResult', listenerFunc: RestoredListener) => Promise<PluginListenerHandle>

如果应用启动时携带了之前持久化的插件调用数据（例如在 Android 上当活动返回到一个已关闭的应用时），此调用将返回应用启动时携带的任何数据，这些数据会转换为插件调用的结果形式。

在 Android 上，由于低端设备的内存限制，如果您的应用启动了一个新的活动，操作系统可能会终止您的应用以减少内存消耗。

例如，这意味着 Camera API（它启动一个新的 Activity 来拍照）可能无法将数据返回给您的应用。

为避免这种情况，Capacitor 会在启动时存储所有已恢复的活动结果。您应该为 appRestoredResult 添加一个监听器，以便处理在您的应用未运行时传递的任何插件调用结果。

一旦您获得该结果（如果有的话），您可以更新 UI，为用户恢复一个逻辑上的体验，例如导航或选择正确的选项卡。

我们建议每个使用依赖外部 Activity（例如 Camera）的插件的 Android 应用都处理此事件和流程。

参数	类型
`eventName`	`'appRestoredResult'`
`listenerFunc`	`RestoredListener`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('backButton', ...)

addListener(eventName: 'backButton', listenerFunc: BackButtonListener) => Promise<PluginListenerHandle>

监听硬件返回按钮事件（仅限 Android）。监听此事件将禁用默认的返回按钮行为，因此您可能需要手动调用 window.history.back()。如果您想关闭应用，请调用 App.exitApp()。

参数	类型
`eventName`	`'backButton'`
`listenerFunc`	`BackButtonListener`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

移除此插件的所有原生监听器。

自版本： 1.0.0

接口#### AppInfo

属性名	类型	描述	起始版本
`name`	`string`	应用名称。	1.0.0
`id`	`string`	应用的唯一标识符。在 iOS 上是 Bundle Identifier，在 Android 上是 Application ID。	1.0.0
`build`	`string`	构建版本号。在 iOS 上是 CFBundleVersion，在 Android 上是 versionCode。	1.0.0
`version`	`string`	应用版本号。在 iOS 上是 CFBundleShortVersionString，在 Android 上是 versionName。	1.0.0

AppState

属性名	类型	描述	起始版本
`isActive`	`boolean`	应用当前是否处于活动状态。	1.0.0

AppLaunchUrl

属性名	类型	描述	起始版本
`url`	`string`	用于打开应用的 URL。	1.0.0

ToggleBackButtonHandlerOptions

属性名	类型	描述	起始版本
`enabled`	`boolean`	指示是否启用或禁用默认的返回按钮处理逻辑。	7.1.0

PluginListenerHandle

属性名	类型
`remove`	`() => Promise<void>`

URLOpenListenerEvent

属性名	类型	描述	起始版本
`url`	`string`	打开应用时使用的 URL。	1.0.0
`iosSourceApplication`	`any`	打开应用的源应用程序 (仅限 iOS)。参考：https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623128-sourceapplication	1.0.0
`iosOpenInPlace`	`boolean`	指示应用是应该就地打开传入的文档，还是必须先复制它。参考：https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623123-openinplace	1.0.0

RestoredListenerEvent

属性名	类型	描述	起始版本
`pluginId`	`string`	此结果对应的插件 ID。例如：`Camera`。	1.0.0
`methodName`	`string`	此结果对应的方法名称。例如：`getPhoto`。	1.0.0
`data`	`any`	从插件传递过来的结果数据。这通常是你正常调用插件方法时期望得到的结果。例如：`CameraPhoto`。	1.0.0
`success`	`boolean`	布尔值，指示插件调用是否成功。	1.0.0
`error`	`{ message: string; }`	如果插件调用失败，这里会包含错误信息。	1.0.0

BackButtonListenerEvent

属性名	类型	描述	起始版本
`canGoBack`	`boolean`	指示浏览器是否可以回退到上一个历史记录。当历史堆栈位于第一个条目时，此值为 false。	1.0.0

类型别名

StateChangeListener

(state: AppState): void

URLOpenListener

(event: URLOpenListenerEvent): void

RestoredListener

(event: RestoredListenerEvent): void

BackButtonListener

(event: BackButtonListenerEvent): void

安装​

iOS​

Android​

示例​

配置​

示例​

API​

exitApp()​

getInfo()​

getState()​

getLaunchUrl()​

minimizeApp()​

toggleBackButtonHandler(...)​

addListener('pause', ...)​

addListener('resume', ...)​

addListener('appUrlOpen', ...)​

addListener('appRestoredResult', ...)​

addListener('backButton', ...)​

removeAllListeners()​

接口#### AppInfo​

AppState​

AppLaunchUrl​

ToggleBackButtonHandlerOptions​

PluginListenerHandle​

URLOpenListenerEvent​

RestoredListenerEvent​

BackButtonListenerEvent​

类型别名​

StateChangeListener​

URLOpenListener​

RestoredListener​

BackButtonListener​

Contents

安装

iOS

Android

示例

配置

示例

API

exitApp()

getInfo()

getState()

getLaunchUrl()

minimizeApp()

toggleBackButtonHandler(...)

addListener('pause', ...)

addListener('resume', ...)

addListener('appUrlOpen', ...)

addListener('appRestoredResult', ...)

addListener('backButton', ...)

removeAllListeners()

接口#### AppInfo

AppState

AppLaunchUrl

ToggleBackButtonHandlerOptions

PluginListenerHandle

URLOpenListenerEvent

RestoredListenerEvent

BackButtonListenerEvent

类型别名

StateChangeListener

URLOpenListener

RestoredListener

BackButtonListener