自 2025 年 3 月 27 日起，我們建議您使用 android-latest-release 而非 aosp-main 建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。
設定 AppCard 主機
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
使用 AppCardHost 與顯示應用程式資訊卡的應用程式進行通訊。
權限
任何使用 AppCardHost 的應用程式都必須具備下列權限：
android.permission.INTERACT_ACROSS_USERS_FULLandroid.permission.QUERY_ALL_PACKAGES- (僅適用於 API 級別 34 以上)
android.car.permission.BIND_APP_CARD_PROVIDER
初始化
如要初始化主機，請提供：
- 背景資訊
updateRate 以毫秒為單位的應用程式資訊卡更新率。fastUpdateRate 標記為 EnforceFastUpdateRate 的元件更新率 (以毫秒為單位)responseExecutor 您要接收 AppCard 應用程式回應的執行緒。
設計
AppCardHost 可透過以下兩種方式進行互動：
OR
AppCardListener
AppCardListener 元件會將自身註冊為 AppCardHost，以便接收來自 AppCardHost 和 AppCard 應用程式的通訊更新。以下是 AppCardListener 的介面函式詳細說明。
fun onAppCardReceived(AppCardContainer)
當應用程式收到 AppCard 時，這個函式就會觸發。它會以 AppCardContainer 的形式傳送，提供 AppCard 和 appIdentifier，用於識別傳送 AppCard 的應用程式
fun onComponentReceived(AppCardComponentContainer)
當應用程式收到 AppCard 元件時，這個函式就會觸發。它會以 AppCardComponentContainer 的形式傳送，該函式會提供 AppCard 元件、Identifier (用於識別傳送 AppCard 的應用程式)，以及字串 ID (用於指向元件相關聯的 AppCard)。
fun onProviderRemoved(String, String?)
當 AppCard 供應器已遭移除或停用時，系統會觸發這個函式。使用這個方法清除與指定套件名稱和供應者授權相關的任何有效 AppCard。
如果權限為 {@code null}，則整個套件都已移除。
fun onProviderAdded(String, String?)
新增或啟用 AppCard 供應器時，系統會觸發這個函式。
用法示範。使用這個函式做為觸發事件，即可在 AppCard 挑選器中重新整理所有可用的 AppCard。如果權限為 {@code null}，則表示已新增整個套件。
fun onPackageCommunicationError(appIdentifier, Throwable)
當 AppCardHost 與 AppCard 供應器通訊時發生錯誤，就會觸發這個函式。
用法示範。使用這個方法，向使用者顯示他們所選的 AppCard 發生錯誤。
API
fun refreshCompatibleapp()
只要使用主機的活動恢復時，就應呼叫此方法，以便主機重新整理支援 AppCard 的應用程式清單。
fun destroy()
在使用主機的活動遭到銷毀時呼叫此方法，以便主機清理所有連線和內部成員。
fun registerListener(AppCardListener)
用於註冊 AppCardListener。
fun unregisterListener(AppCardListener)
用於取消註冊 AppCardListener。
fun getAllAppCards(AppCardContext)
呼叫這個方法，即可為已註冊的 AppCardListener 提供系統中提供的所有 AppCard，並使用特定 AppCardContext 向供應器提供有關如何建構 AppCard 的提示。
fun requestAppCard(AppCardContext, appIdentifier, String)
呼叫這個方法，即可為註冊的 AppCardListener 提供特定 AppCard，前提是您提供 AppCardContext，讓提供者瞭解如何建構 AppCard。
fun notifyAppCardRemoved(appIdentifier, String)
通知 AppCard 供應商其 AppCard 已失效。
fun notifyAppCardInteraction(appIdentifier, String, String, String)
通知 AppCard 供應商，指出 AppCard 已與使用者互動。唯一支援的互動是按下按鈕，以 AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK 表示。
建議您為 AppCard 建立按鈕，並使用 onClick 事件監聽器，以 appIdentifier、AppCard ID、元件 ID 和互動 ID 呼叫此函式。
fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)
針對特定 AppCard 傳送 AppCardContext 更新。舉例來說，當您從停車模式切換至行車模式時，請使用這個方法傳送 AppCardContext 更新，其中 isInteractable 會針對每個有效的 AppCard 設為 false。
常見問題
哪裡可以找到實作範例？
每個 AppCardContentProvider 可支援多少個 AppCard？
AppCardContentProvider 可支援無限數量的 AppCard。不過，請務必在 AppCard 數量、效能降低和良好使用者體驗之間取得平衡。
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間：2025-06-26 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-06-26 (世界標準時間)。"],[],[],null,["# Configure an AppCard host\n\nUse `AppCardHost` to communicate with apps that show AppCards.\n\nPermissions\n-----------\n\nAny app that uses an `AppCardHost` must have the following permissions:\n\n- `android.permission.INTERACT_ACROSS_USERS_FULL`\n- `android.permission.QUERY_ALL_PACKAGES`\n- (In API level 34 and higher **only** ) `android.car.permission.BIND_APP_CARD_PROVIDER`\n\nInitialize\n----------\n\nTo initialize the host, provide:\n\n- Context\n- `updateRate` AppCard update rate in milliseconds.\n- `fastUpdateRate` Update rate in milliseconds for components tagged with `EnforceFastUpdateRate`\n- `responseExecutor` A thread on which you want to receive responses from AppCard apps.\n\nDesign\n------\n\nAn `AppCardHost` can be interacted with in one of two ways:\n\n- Register as an [`AppCardListener`](#appcardlistener)\n\nOR,\n\n- Interact with the [`AppCardHost` APIs](#api)\n\n### AppCardListener\n\nThe `AppCardListener` component registers itself with an `AppCardHost`\nto receive communication updates from the `AppCardHost` and AppCard apps.\nThe interface functions of an `AppCardListener` are detailed here.\n\n\u003cbr /\u003e\n\n`fun onAppCardReceived(AppCardContainer)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard has been received from an app. It's sent as an `AppCardContainer` which provides an AppCard and an `appIdentifier` to identify the app that sent the AppCard\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onComponentReceived(AppCardComponentContainer)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard component is received from an app. It's sent as an `AppCardComponentContainer`, which provides an AppCards component, `Identifier` to identify the app that sent the AppCard, and a string ID to point to the AppCard to which the component is related.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onProviderRemoved(String, String?)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard provider has been removed or disabled. Use this method to clean up any active AppCard related to the given package name and provider authority.\u003cbr /\u003e\n\nIf authority is `{@code null}`, then an entire package was removed.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onProviderAdded(String, String?)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard provider has been added or enabled.\u003cbr /\u003e\n\n**Sample usage.** Use this function as a trigger to refresh all available\nAppCards in an AppCard picker. If authority is `{@code null}`, then an entire\npackage was added.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onPackageCommunicationError(appIdentifier, Throwable)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when the `AppCardHost` encounters an error when communicating with an AppCard provider.\n\n\u003cbr /\u003e\n\n**Sample usage.** Use this method to show to the user that an AppCard they have\nselected has encountered an error.\n\n\u003cbr /\u003e\n\n### APIs\n\n\u003cbr /\u003e\n\n`fun refreshCompatibleapp()`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis method should be called whenever the activity that is using the host is resumed so that the host can refresh its list of apps that support AppCards.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun destroy()`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCall this method when an activity that is using a host is destroyed so that the host can clean up all connections and internal members.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun registerListener(AppCardListener)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nUsed to register an `AppCardListener`.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun unregisterListener(AppCardListener)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nUsed to unregister an `AppCardListener`.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun getAllAppCards(AppCardContext)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCall this method to supply a registered `AppCardListener` with all the AppCards provided in the system with a given `AppCardContext` that provides hints to the providers on how to structure their AppCard.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun requestAppCard(AppCardContext, appIdentifier, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCall this method to supply a registered `AppCardListener` with a specific AppCard, given an `AppCardContext` that gives hints to the providers on how to structure their AppCard.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun notifyAppCardRemoved(appIdentifier, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nNotify an AppCard provider that its AppCard is no longer active.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun notifyAppCardInteraction(appIdentifier, String, String, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nNotify an AppCard provider that its AppCard has been interacted with. The only supported interaction is a button click, which is signified by a `AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK`.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nWe recommend creating a button for an AppCard with an `onClick` listener that calls this function with `appIdentifier`, AppCard ID, component ID, and interaction ID.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nSend an `AppCardContext` update for a specific AppCard. For example, when shifting from Park mode to Drive mode, use this method to send an `AppCardContext` update in which `isInteractable` is set to `false` for each active AppCard.\n\n\u003cbr /\u003e\n\nFAQ\n---\n\n1. Where can I find sample implementations?\n\n - [Sample host](https://android.googlesource.com/platform/packages/apps/Car/libs/+/refs/tags/ub-automotive-master-20250418/car-app-card-host-lib/sample-host/). Shows all available AppCards in the system, along with\n testing capabilities.\n\n - DriverUI and [Pano manager](https://cs.android.com/android/platform/superproject/+/android-latest-release:packages/services/Car/car_product/distant_display/apps/CarDistantDisplayPanoManager/;l=1?q=CarDistantDisplayPanoManager&sq=&ss=android%2Fplatform%2Fsuperproject%2Fmain). Pano manager acts as the picker while\n DriverUI acts as the presenter.\n\n2. How many AppCards can each `AppCardContentProvider` support?\n\n An `AppCardContentProvider` can support an infinite number of AppCards.\n However, be sure to balance the number of AppCards with degraded performance\n versus a positive user experience."]]
