跳到主要内容
版本：v3

@capacitor/app

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

安装​

npm install @capacitor/app
npx cap sync

iOS 配置​

如需通过自定义 URL 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 配置​

如需通过自定义 URL 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 和通用链接（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 时，操作系统可能为减少内存消耗而终止应用进程。

例如，Camera API 会启动新 activity 拍摄照片，可能无法将数据返回给应用。

为避免此问题，Capacitor 会在启动时存储所有恢复的 activity 结果。建议添加 appRestoredResult 监听器来处理应用未运行时传递的插件调用结果。

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

建议所有依赖外部 Activity 的 Android 应用（例如使用 Camera）都配置此事件处理。

参数类型
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

Interfaces​

AppInfo​

属性类型描述版本
namestring应用名称1.0.0
idstring应用标识符。iOS 上是 Bundle Identifier，Android 上是 Application ID1.0.0
buildstring构建版本号。iOS 上是 CFBundleVersion，Android 上是 versionCode1.0.0
versionstring应用版本。iOS 上是 CFBundleShortVersionString，Android 上是 versionName1.0.0

AppState​

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

AppLaunchUrl​

属性类型描述版本
urlstring用于打开应用的 URL1.0.0

PluginListenerHandle​

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

URLOpenListenerEvent​

属性类型描述版本
urlstring打开应用的 URL1.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对应的插件 ID，如 Camera1.0.0
methodNamestring对应的方法名，如 getPhoto1.0.0
dataany插件返回的数据，与正常调用插件方法的结果一致，如 CameraPhoto1.0.0
successboolean表示插件调用是否成功1.0.0
error{ message: string; }调用失败时的错误信息1.0.0

BackButtonListenerEvent​

属性类型描述版本
canGoBackboolean指示浏览器是否可以后退。当历史堆栈位于第一条记录时为 false1.0.0

Type Aliases​

StateChangeListener​


  (state: AppState): void

URLOpenListener​


  (event: URLOpenListenerEvent): void

RestoredListener​


  (event: RestoredListenerEvent): void

BackButtonListener​


  (event: BackButtonListenerEvent): void

Contents

编辑此页