版本：v6

@capacitor/app

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

安装

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

iOS

为了能够通过自定义 URL 方案（custom 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

为了能够通过自定义 URL 方案（custom 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);
};

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

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 上的通用链接和 Android 上的应用链接）。

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

返回值：

Promise<PluginListenerHandle>

自： 1.0.0

addListener('appRestoredResult', ...)

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

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

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

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

为了避免这种情况，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

PluginListenerHandle

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

属性	类型	描述	起始版本
`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()​

addListener('appStateChange', ...)​

addListener('pause', ...)​

addListener('appUrlOpen', ...)​

addListener('appRestoredResult', ...)​

addListener('backButton', ...)​

removeAllListeners()​

接口​

AppInfo​

AppState​

AppLaunchUrl​

PluginListenerHandle​

RestoredListenerEvent​

BackButtonListenerEvent​

类型别名​

StateChangeListener​

URLOpenListener​

RestoredListener​

BackButtonListener​

Contents

安装

iOS

Android

示例

API

exitApp()

getInfo()

getState()

getLaunchUrl()

minimizeApp()

addListener('appStateChange', ...)

addListener('pause', ...)

addListener('appUrlOpen', ...)

addListener('appRestoredResult', ...)

addListener('backButton', ...)

removeAllListeners()

接口

AppInfo

AppState

AppLaunchUrl

PluginListenerHandle

RestoredListenerEvent

BackButtonListenerEvent

类型别名

StateChangeListener

URLOpenListener

RestoredListener

BackButtonListener