اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
ضبط مضيف بطاقة التطبيق
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
استخدِم AppCardHost للتواصل مع التطبيقات التي تعرض بطاقات التطبيقات.
الأذونات
يجب أن يكون لدى أي تطبيق يستخدم AppCardHost الأذونات التالية:
android.permission.INTERACT_ACROSS_USERS_FULLandroid.permission.QUERY_ALL_PACKAGES- (في المستوى 34 من واجهة برمجة التطبيقات والإصدارات الأحدث فقط)
android.car.permission.BIND_APP_CARD_PROVIDER
تهيئة
لإعداد المضيف، يجب تقديم ما يلي:
- السياق
updateRate معدّل تعديل بطاقة التطبيق بالمللي ثانيةfastUpdateRate معدّل التعديل بالمللي ثانية للمكوّنات التي تم وضع علامة عليها باستخدام
EnforceFastUpdateRateresponseExecutor سلسلة محادثات تريد تلقّي ردود عليها من
تطبيقات AppCard
التصميم
يمكن التفاعل مع AppCardHost بطريقتَين:
أو
AppCardListener
يسجِّل مكوّن AppCardListener نفسه باستخدام AppCardHost
لتلقّي آخر المعلومات المتعلّقة بالتواصل من تطبيقَي AppCardHost وAppCard.
يمكنك الاطّلاع هنا على تفاصيل وظائف واجهة AppCardListener.
fun onAppCardReceived(AppCardContainer)
يتم تنشيط هذه الدالة عند تلقّي بطاقة تطبيق من أحد
التطبيقات. ويتم إرسالها كرسالة AppCardContainer تقدّم بطاقة تطبيق وappIdentifier
لتحديد التطبيق الذي أرسل بطاقة التطبيق.
fun onComponentReceived(AppCardComponentContainer)
يتم تنشيط هذه الدالة عند تلقّي مكوّن بطاقة تطبيق من
تطبيق. ويتم إرساله كعنصر AppCardComponentContainer، الذي يقدّم
مكوّن بطاقة تطبيق، Identifier لتحديد التطبيق الذي أرسل
بطاقة التطبيق، ورقم تعريف سلسلة للإشارة إلى بطاقة التطبيق التي
يرتبط بها المكوّن.
fun onProviderRemoved(String, String?)
يتم تنشيط هذه الدالة عند إزالة مقدّم بطاقة التطبيق أو
إيقافه. استخدِم هذه الطريقة لإزالة أي بطاقة تطبيق نشطة مرتبطة باسم الحزمة المُعطى وسلطة الموفِّر.
إذا كانت السلطة هي {@code null}، يعني ذلك أنّه تمت إزالة حزمة كاملة.
fun onProviderAdded(String, String?)
يتم تنشيط هذه الدالة عند إضافة مقدّم خدمة بطاقة التطبيق أو
تفعيله.
أمثلة على الاستخدام: استخدِم هذه الدالة كمشغِّل لإعادة تحميل كل ملفّات AppCard المتاحة في أداة اختيار ملفّات AppCard. إذا كانت السلطة هي {@code null}، يعني ذلك أنّه تمت إضافة
حزمة كاملة.
fun onPackageCommunicationError(appIdentifier, Throwable)
يتم تنشيط هذه الوظيفة عندما يواجه AppCardHost خطأ عند
التواصل مع موفِّر بطاقة التطبيق.
أمثلة على الاستخدام: استخدِم هذه الطريقة لإعلام المستخدم بأنّه حدث خطأ في بطاقة التطبيق التي اختارها.
واجهات برمجة التطبيقات
fun refreshCompatibleapp()
يجب استدعاء هذه الطريقة عند استئناف النشاط الذي يستخدم المضيف
كي يتمكّن المضيف من إعادة تحميل قائمة التطبيقات المتوافقة مع بطاقات التطبيقات.
fun destroy()
استخدِم هذه الطريقة عند إتلاف نشاط يستخدم مضيفًا
لكي يتمكّن المضيف من تنظيف جميع عمليات الربط والأعضاء الداخليين.
fun registerListener(AppCardListener)
يُستخدَم لتسجيل AppCardListener.
fun unregisterListener(AppCardListener)
يُستخدَم لإلغاء تسجيل AppCardListener.
fun getAllAppCards(AppCardContext)
استخدِم هذه الطريقة لتزويد AppCardListener مسجَّل بجميع
بطاقات التطبيقات المقدَّمة في النظام باستخدام AppCardContext معيّن
يقدّم إرشادات لموفّري التطبيقات حول كيفية تنظيم بطاقة التطبيق.
fun requestAppCard(AppCardContext, appIdentifier, String)
استخدِم هذه الطريقة لتزويد AppCardListener مسجَّل بأحد
بطاقات التطبيقات المحدّدة، وذلك من خلال AppCardContext يقدّم للموفّرين اقتراحات بشأن كيفية تنظيم بطاقة التطبيق الخاصة بهم.
fun notifyAppCardRemoved(appIdentifier, String)
إعلام مقدّم خدمة AppCard بأنّ بطاقة AppCard لم تعُد نشطة
fun notifyAppCardInteraction(appIdentifier, String, String, String)
إرسال إشعار إلى موفّر بطاقة AppCard بأنّه تم التفاعل مع بطاقة AppCard
التفاعل الوحيد المسموح به هو النقر على زر، ويُشار إليه بالرمز
AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK.
ننصح بإنشاء زر لـ "بطاقة تطبيق" باستخدام مستمع onClick
يُطلِب هذه الدالة باستخدام appIdentifier ورقم تعريف "بطاقة التطبيق" ورقم تعريف العنصر
ورقم تعريف التفاعل.
fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)
أرسِل تحديثًا AppCardContext لـ "بطاقة تطبيق" معيّنة. على سبيل المثال، عند
التبديل من وضع الركن إلى وضع القيادة، استخدِم هذه الطريقة لإرسال AppCardContext تحديث يتم فيه ضبط isInteractable على false لكل
بطاقة تطبيق نشطة.
الأسئلة الشائعة
أين يمكنني العثور على نماذج عمليات التنفيذ؟
كم عدد بطاقات التطبيقات التي يمكن لكل AppCardContentProvider استخدامها؟
يمكن أن يتضمّن AppCardContentProvider عددًا غير محدود من بطاقات التطبيقات.
ومع ذلك، احرص على موازنة عدد بطاقات التطبيقات ذات الأداء المتدني
مع تجربة المستخدم الإيجابية.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ 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."]]
