跳到主要内容
版本：v3

@capacitor/app

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

安装​

npm install @capacitor/app
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);
};

API​

exitApp()​

exitApp() => never

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

Ionic 本身会处理此操作，因此如果您使用 Ionic，则无需调用此方法。

返回： never

起始版本： 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> & PluginListenerHandle

监听应用活跃状态的变化（应用是在前台还是后台）。

参数类型
eventName'appStateChange'
listenerFunc
StateChangeListener

返回： 

Promise<PluginListenerHandle> & PluginListenerHandle

起始版本： 1.0.0

addListener('appUrlOpen', ...)​

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

监听应用的 URL 打开事件。这包括自定义 URL scheme 链接以及应用处理的 URL（iOS 上的 Universal Links 和 Android 上的 App Links）。

参数类型
eventName'appUrlOpen'
listenerFunc
URLOpenListener

返回： 

Promise<PluginListenerHandle> & PluginListenerHandle

起始版本： 1.0.0

addListener('appRestoredResult', ...)​

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

如果应用使用之前持久化的插件调用数据启动，例如在 Android 上一个 activity 返回给已关闭的应用时，此调用将返回应用启动时携带的任何数据，并转换为插件调用的结果形式。

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

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

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

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

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

参数类型
eventName'appRestoredResult'
listenerFunc
RestoredListener

返回： 

Promise<PluginListenerHandle> & PluginListenerHandle

起始版本： 1.0.0

addListener('backButton', ...)​

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

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

参数类型
eventName'backButton'
listenerFunc
BackButtonListener

返回： 

Promise<PluginListenerHandle> & PluginListenerHandle

起始版本： 1.0.0

removeAllListeners()​

removeAllListeners() => Promise<void>

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

起始版本： 1.0.0

接口​

AppInfo​

属性类型描述起始版本
namestring应用的名称。1.0.0
idstring应用的标识符。在 iOS 上是 Bundle Identifier。在 Android 上是 Application ID。1.0.0
buildstring构建版本。在 iOS 上是 CFBundleVersion。在 Android 上是 versionCode。1.0.0
versionstring应用版本。在 iOS 上是 CFBundleShortVersionString。在 Android 上是 package 的 versionName。1.0.0

AppState​

属性类型描述起始版本
isActiveboolean应用是否处于活跃状态。1.0.0

AppLaunchUrl​

属性类型描述起始版本
urlstring用于打开应用的 URL。1.0.0

PluginListenerHandle​

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

URLOpenListenerEvent​

属性类型描述起始版本
urlstring应用被打开时使用的 URL。1.0.0
iosSourceApplicationany打开应用的源应用（仅 iOS）https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623128-sourceapplication1.0.0
iosOpenInPlaceboolean应用是否应就地打开传递的文档或必须先复制它。https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623123-openinplace1.0.0

RestoredListenerEvent​

属性类型描述起始版本
pluginIdstring此结果对应的 pluginId。例如 Camera。1.0.0
methodNamestring此结果对应的 methodName。例如 getPhoto。1.0.0
dataany从插件传递的结果数据。这将是您通常调用插件方法时所期望的结果。例如 CameraPhoto。1.0.0
successboolean指示插件调用是否成功的布尔值。1.0.0
error{ message: string; }如果插件调用未成功，将包含错误消息。1.0.0

BackButtonListenerEvent​

属性类型描述起始版本
canGoBackboolean指示浏览器是否可以返回上一页历史记录。当历史堆栈在第一条记录时返回 false。1.0.0

类型别名​

StateChangeListener​

(state: AppState): void

URLOpenListener​

(event: URLOpenListenerEvent): void

RestoredListener​

(event: RestoredListenerEvent): void

BackButtonListener​

(event: BackButtonListenerEvent): void

Contents

编辑此页