版本：v6

@capacitor/app

App 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

若要通过自定义协议打开应用，需先注册该协议。您可以在 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);
};

exitApp()

exitApp() => Promise<void>

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

如果您使用 Ionic 框架，Ionic 已自行处理此逻辑，通常无需调用此方法。

Since: 1.0.0

getInfo()

getInfo() => Promise<AppInfo>

获取应用相关信息。

Returns:

Promise<AppInfo>

Since: 1.0.0

getState()

getState() => Promise<AppState>

获取当前应用状态。

Returns:

Promise<AppState>

Since: 1.0.0

getLaunchUrl()

getLaunchUrl() => Promise<AppLaunchUrl | undefined>

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

Returns:

Promise<AppLaunchUrl>

Since: 1.0.0

minimizeApp()

minimizeApp() => Promise<void>

最小化应用。

仅适用于 Android 平台。

Since: 1.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`

Returns:

Promise<PluginListenerHandle>

Since: 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`

Returns:

Promise<PluginListenerHandle>

Since: 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`

Returns:

Promise<PluginListenerHandle>

Since: 4.1.0

addListener('appUrlOpen', ...)

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

监听应用通过 URL 打开的事件。该方法同时处理自定义 URL scheme 链接和应用处理的 URL（iOS 上的通用链接和 Android 上的应用链接）。

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

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

addListener('appRestoredResult', ...)

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

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

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

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

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

一旦获得结果（如果有），您可以更新 UI 以恢复用户的逻辑体验，例如导航或选择正确的标签页。

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

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

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

addListener('backButton', ...)

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

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

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

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

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

Since: 1.0.0

Interfaces

AppInfo

属性	类型	描述	Since
`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

属性	类型	描述	Since
`isActive`	`boolean`	指示应用是否处于活动状态	1.0.0

AppLaunchUrl

属性	类型	描述	Since
`url`	`string`	用于打开应用的 URL	1.0.0

PluginListenerHandle

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

URLOpenListenerEvent

属性	类型	描述	Since
`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

属性	类型	描述	Since
`pluginId`	`string`	此结果对应的 pluginId。例如 `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

属性	类型	描述	Since
`canGoBack`	`boolean`	指示浏览器是否可以返回历史记录。当历史堆栈位于第一条记录时为 false	1.0.0

Type Aliases

StateChangeListener


  (state: AppState): void

URLOpenListener


  (event: URLOpenListenerEvent): void

RestoredListener


  (event: RestoredListenerEvent): void

BackButtonListener


  (event: BackButtonListenerEvent): void

安装​

iOS​

Android​

示例​

API​

exitApp()​

getInfo()​

getState()​

getLaunchUrl()​

minimizeApp()​

addListener('appStateChange', ...)​

addListener('pause', ...)​

addListener('resume', ...)​

addListener('appUrlOpen', ...)​

addListener('appRestoredResult', ...)​

addListener('backButton', ...)​

removeAllListeners()​

Interfaces​

AppInfo​

AppState​

AppLaunchUrl​

PluginListenerHandle​

URLOpenListenerEvent​

RestoredListenerEvent​

BackButtonListenerEvent​

Type Aliases​

StateChangeListener​

URLOpenListener​

RestoredListener​

BackButtonListener​

Contents

安装

iOS

Android

示例

API

exitApp()

getInfo()

getState()

getLaunchUrl()

minimizeApp()

addListener('appStateChange', ...)

addListener('pause', ...)

addListener('resume', ...)

addListener('appUrlOpen', ...)

addListener('appRestoredResult', ...)

addListener('backButton', ...)

removeAllListeners()

Interfaces

AppInfo

AppState

AppLaunchUrl

PluginListenerHandle

URLOpenListenerEvent

RestoredListenerEvent

BackButtonListenerEvent

Type Aliases

StateChangeListener

URLOpenListener

RestoredListener

BackButtonListener