版本：v7

@capacitor/app

App API 处理高级别的应用状态和事件。例如，此 API 在应用进入和离开前台时发出事件，处理深层链接、打开其他应用以及管理持久化的插件状态。

安装

npm install @capacitor/app@latest-7
npx cap sync

iOS

要能够通过自定义 scheme 打开应用，您需要先注册该 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 打开应用，您需要先注册该 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>

监听应用或 Activity 状态的变化。

在 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>

监听应用或 Activity 暂停时的事件。

在 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>

监听应用或 Activity 恢复时的事件。

在 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 scheme 链接以及您的应用处理的 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 上当一个 Activity 返回到一个已被关闭的应用时，此调用将返回任何应用启动时携带的数据，转换为插件调用的结果形式。

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

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

为避免这种情况，Capacitor 在启动时存储所有恢复的 Activity 结果。您应该为 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 上是 package 的 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`	此结果对应的 pluginId。例如 `Camera`。	1.0.0
`methodName`	`string`	此结果对应的 methodName。例如 `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('appStateChange', ...)​

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('appStateChange', ...)

addListener('pause', ...)

addListener('resume', ...)

addListener('appUrlOpen', ...)

addListener('appRestoredResult', ...)

addListener('backButton', ...)

removeAllListeners()

接口

AppInfo

AppState

AppLaunchUrl

ToggleBackButtonHandlerOptions

PluginListenerHandle

URLOpenListenerEvent

RestoredListenerEvent

BackButtonListenerEvent

类型别名

StateChangeListener

URLOpenListener

RestoredListener

BackButtonListener