跳到主要内容
版本：v8

@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);
};

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

addListener('appStateChange', ...)​

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

监听应用或活动状态的更改。

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

参数类型
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 时，它会被触发。

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

**返回：** Promise<PluginListenerHandle>

自 1.0.0

addListener('appRestoredResult', ...)​

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

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

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

例如，这意味着相机 API（它启动一个新的活动来拍照）可能无法将数据返回到您的应用。

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

获得该结果后（如果有），您可以更新 UI 以恢复对用户的逻辑体验，例如导航或选择正确的选项卡。

我们建议每个使用依赖于外部活动（例如，相机）的插件的 Android 应用都拥有此事件并处理它。

参数类型
eventName'appRestoredResult'
listenerFuncRestoredListener

**返回：** Promise<PluginListenerHandle>

自 1.0.0

addListener('backButton', ...)​

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

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

参数类型
eventName'backButton'
listenerFuncBackButtonListener

**返回：** Promise<PluginListenerHandle>

自 1.0.0

removeAllListeners()​

removeAllListeners() => Promise<void>

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

自 1.0.0

接口​

AppInfo​

属性类型描述自
namestring应用的名称。1.0.0
idstring应用的标识符。在 iOS 上，它是包标识符。在 Android 上，它是应用 ID1.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

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。例如，getPhoto1.0.0
dataany从插件传递的结果数据。这将是您通常调用插件方法时所期望的结果。例如，CameraPhoto1.0.0
successboolean指示插件调用是否成功的布尔值。1.0.0
error{ message: string; }如果插件调用未成功，它将包含错误消息。1.0.0

BackButtonListenerEvent​

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

类型别名​

StateChangeListener​

(状态: AppState): void

URLOpenListener​

(事件: URLOpenListenerEvent): void

RestoredListener​

(事件: RestoredListenerEvent): void

BackButtonListener​

(事件: BackButtonListenerEvent): void

内容

编辑此页面