跳到主要内容
版本：v6

@capacitor/app

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

安装​

npm install @capacitor/app
npx cap sync

iOS 平台​

要能够通过自定义方案打开应用，您需要先注册该方案。您可以通过编辑 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('App state changed. Is active?', isActive);
});

App.addListener('appUrlOpen', data => {
  console.log('App opened with URL:', data);
});

App.addListener('appRestoredResult', data => {
  console.log('Restored state:', data);
});

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

  console.log('App opened with URL: ' + url);
};

配置​

属性类型描述默认值自版本
disableBackButtonHandlerboolean禁用插件的默认返回按钮处理。仅适用于 Android。false7.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;

API 参考​

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

getAppLanguage()​

getAppLanguage() => Promise<AppLanguageCode>

获取应用特定的语言区域代码。

返回： Promise<AppLanguageCode>

自版本： 8.1.0

toggleBackButtonHandler(...)​

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

在运行时启用或禁用插件的返回按钮处理。

仅适用于 Android。

ParamType
optionsToggleBackButtonHandlerOptions

自版本： 7.1.0

addListener('appStateChange', ...)​

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

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

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

ParamType
eventName'appStateChange'
listenerFuncStateChangeListener

返回： 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 时触发。

ParamType
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 时触发。

ParamType
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）。

ParamType
eventName'appUrlOpen'
listenerFuncURLOpenListener

返回： Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('appRestoredResult', ...)​

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

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

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

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

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

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

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

ParamType
eventName'appRestoredResult'
listenerFuncRestoredListener

返回： Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('backButton', ...)​

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

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

ParamType
eventName'backButton'
listenerFuncBackButtonListener

返回： Promise<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 上是包的 versionName。1.0.0

AppState​

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

AppLaunchUrl​

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

AppLanguageCode​

属性类型描述自版本
valuestring两个或三个字符的语言代码。8.1.0

ToggleBackButtonHandlerOptions​

属性类型描述自版本
enabledboolean指示是否启用或禁用默认返回按钮处理。7.1.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

目录

编辑此页