跳至主要內容
版本：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 方法被呼叫時，會觸發此事件，但僅在恢復事件先觸發後才會觸發。在 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（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 上是應用程式 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

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​

(state: AppState): void

URLOpenListener​

(event: URLOpenListenerEvent): void

RestoredListener​

(event: RestoredListenerEvent): void

BackButtonListener​

(event: BackButtonListenerEvent): void

目錄

編輯此頁面