واجهة برمجة تطبيقات "مجموعة الأدوات"

استخدام واجهة برمجة تطبيقات مجموعة الأدوات (واجهة برمجة تطبيقات Android) لعرض تطبيقات التنقل، بما في ذلك خرائط Google، على شاشة عرض ثانوية في السيارة، مثل خلف على عجلة القيادة في لوحة العدادات. تصف هذه الصفحة كيفية إنشاء للتحكم في العرض الثانوي ودمج الخدمة مع CarService حتى تتمكن تطبيقات التنقّل من عرض واجهة المستخدم.

المصطلحات

تم استخدام المصطلحات التالية في هذه الصفحة.

المتطلّبات الأساسية

قبل المتابعة، تأكد من توفر العناصر التالية:

• بيئة تطوير Android: لإعداد نظام التشغيل Android، بيئة التطوير، راجع متطلبات الإصدار:
• نزِّل رمز المصدر لنظام التشغيل Android. احصل على أحدث إصدار من رمز مصدر Android من فرع إصدار pi-car (أو لاحقًا) على https://android.googlesource.com.
• الوحدة الرئيسية (HU): يشير هذا المصطلح إلى جهاز Android قادر على تشغيل إصدار Android 9 (أو إصدار أحدث) يجب أن يكون لهذا الجهاز شاشة خاصة به وأن يكون قادرًا على أو إبراز الإصدارات الجديدة من Android.
• مجموعة الأدوات هي واحدة مما يلي:
  • شاشة ثانوية مادية متصلة بمصدر الطاقة (HU) إذا كانت الأجهزة والنواة التي تتيح إدارة شاشات متعددة.
  • وحدة مستقلة: وأي وحدة حسابية متصلة HU عبر اتصال شبكة، قادر على استقبال الفيديو المضمّن وعرضه على عرضها الخاص.
  • محاكاة الشاشة: أثناء التطوير، يمكنك استخدام إحدى هذه البيئات في وضع المحاكاة:
    • محاكاة شاشات ثانوية لتمكين محاكاة جهاز عرض ثانوي على أي توزيع لنظام التشغيل Android من خلال AOSP، انتقِل إلى خيارات المطوّرين. في تطبيق النظام الإعدادات ثم انقر على محاكاة الإعدادات الثانوية. أجهزة العرض: يعادل هذا الإعداد توصيل جهاز ثانوي مادي إلا أنه يتم تراكب هذه الشاشة فوق الجزء الأساسي العرض.
    • مجموعة الأدوات التي تمت محاكاتها: يتضمّن محاكي Android مع AAOS خيارًا لعرض مجموعة أدوات ClusterRenderingService:

بنية الدمج

مكوّنات الدمج

يتألف أي دمج لواجهة برمجة تطبيقات مجموعة الأدوات من هذه المكوّنات الثلاثة:

• CarService
• تطبيقات التنقّل
• خدمة مجموعة أدوات المصنّع الأصلي للجهاز

خدمة السيارة

يتوسط "CarService" بين تطبيقات التنقّل والسيارة، ما يضمن يكون أحد تطبيقات التنقل نشطًا في أي وقت، ولا يتم تسجيل سوى التطبيقات التي يمكن للإذن "android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL" إرسال البيانات. إلى السيارة.

يدمج "CarService" جميع الخدمات الخاصة بالسيارة ويتيح الوصول إلى هذه الخدمات من خلال سلسلة من المديرين. وللتفاعل مع الخدمات، التطبيقات التي تعمل في السيارة يمكنها الوصول إلى هؤلاء المدراء.

لتطبيق مجموعة الأدوات، على المصنّعين الأصليين أو المصنّعين الأصليين للسيارات إنشاء قائمة تنفيذ MachineClusterRendererService وتحديث ClusterRenderingService:

عند عرض مجموعة أدوات، وأثناء عملية التمهيد يقرأ CarService المفتاح InstrumentClusterRendererService ClusterRenderingService لتحديد مكان تنفيذ InstrumentClusterService. في AOSP، هذا الإدخال يشير إلى خدمة عرض نموذج تطبيق المجموعة لواجهة برمجة تطبيقات حالة التنقل:

<string name="instrumentClusterRendererService">
android.car.cluster/.ClusterRenderingService
</string>

يتم إعداد الخدمة المشار إليها في هذا الإدخال وربطها CarService عند طلب تطبيقات التنقّل، مثل "خرائط Google"، CarInstrumentClusterManager، يوفر CarService للمدير تعدّل حالة مجموعة الأدوات من الحد InstrumentClusterRenderingService. (في هذه الحالة، تشير bound إلى أجهزة Android الخدمات.)

خدمة مجموعة الأدوات

على المصنّعين الأصليين للأجهزة إنشاء حزمة Android (APK) تحتوي على فئة فرعية من ClusterRenderingService:

تخدم هذه الفئة غرضين:

• توفّر واجهة Android وجهاز عرض "مجموعة الأدوات" (الغرض من هذه الصفحة).
• تلقّي تحديثات حالة التنقّل وعرضها، مثل الاتّجاهات المفصّلة إرشادات التنقل.

للغرض الأول، تم تنفيذ InstrumentClusterRendererService لدى المصنّع الأصلي للجهاز تهيئة الشاشة الثانوية المستخدمة لعرض المعلومات على الشاشات في مقصورة السيارة لتوصيل هذه المعلومات إلى CarService من خلال الاتصال InstrumentClusterRendererService.setClusterActivityOptions() و InstrumentClusterRendererService.setClusterActivityState() طرق.

بالنسبة للدالة الثانية، يجب أن توفر خدمة "مجموعة الأدوات" تنفيذ ClusterRenderingService تتلقّى أحداث تحديث حالة التنقّل، والتي يتم ترميزها على أنّها eventType وبيانات الحدث المشفّرة في حزمة.

تسلسل عملية الدمج

يوضِّح الرسم البياني التالي تنفيذ حالة التنقّل. يعرض التحديثات:

في هذا الرسم التوضيحي، تشير الألوان إلى ما يلي:

• أصفر CarService وCarNavigationStatusManager الذي يقدمه نظام Android الأساسي. لمزيد من المعلومات، يُرجى مراجعة سيارة CAR_NAVIGATION_SERVICE
• أزرق سماوي تم تنفيذ InstrumentClusterRendererService المصنّع الأصلي للجهاز.
• أرجواني تطبيق "التنقل" الذي تنفّذه Google والجهات الخارجية المطورين.
• أخضر CarAppFocusManager. لمزيد من المعلومات، يُرجى مراجعة استخدام واجهة برمجة التطبيقات CarAppFocusManager أدناه و CarAppFocusManager.

ويتبع تدفق معلومات حالة التنقل هذا التسلسل:

1. يؤدي CarService إلى إعداد InstrumentClusterRenderingService.
2. أثناء الإعداد، يتم تحديث "InstrumentClusterRenderingService". CarService مع:
   1. خصائص عرض مجموعة الأدوات، مثل الحدود غير الغامضة (اطّلِع على مزيد من التفاصيل حول عدم إخفاء الحدود لاحقًا).
   2. خيارات النشاط اللازمة لبدء الأنشطة داخل عرض "مجموعة الأدوات" لمزيد من المعلومات، يُرجى مراجعة ActivityOptions
3. أحد تطبيقات التنقّل (مثل "خرائط Google" لأجهزة Android Automotive أو أي تطبيق خرائط لديه الأذونات المطلوبة):
   1. يحصل على CarAppFocusManager باستخدام فئة السيارة من lib.
   2. قبل بدء الحصول على اتّجاهات مفصّلة، تتبقى CarAppFocusManager.requestFocus() للوصول إلى الهدف. CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION على أنّه appType .
4. ينقل CarAppFocusManager هذا الطلب إلى CarService. في حال منح الإذن، يفحص "CarService" حزمة تطبيق التنقّل ويحدّد موقع تم تمييز النشاط بالفئة android.car.cluster.NAVIGATION.
5. وفي حال العثور عليه، سيستخدم تطبيق التنقّل ActivityOptions التي تم الإبلاغ عنها من قِبل InstrumentClusterRenderingService لتشغيل النشاط ويتضمن تعرض مجموعة الأدوات الخصائص كعناصر إضافية في الغرض.

دمج واجهة برمجة التطبيقات

يجب أن تستوفي عملية تنفيذ InstrumentClusterRenderingService الشروط التالية:

• يمكن تحديدها كخدمة مفردة عن طريق إضافة القيمة التالية إلى ملف AndroidManifest.xml. يعد ذلك ضروريًا للتأكد من أن نسخة واحدة من يتم تشغيل خدمة "مجموعة الأدوات" حتى أثناء الإعداد وتبديل المستخدمين:
  android:singleUser="true"
• الحصول على إذن النظام BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE هذا النمط تضمن عدم تضمين سوى خدمة عرض مجموعة الأدوات صورة نظام Android مرتبطة في أي وقت بـ CarService:

  <uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>
  

تنفيذ instrumentClusterRenderingService

لإنشاء الخدمة:

1. اكتب صفًا يمتد من ClusterRenderingService ثم أضِف إدخالاً مقابلاً إلى ملف AndroidManifest.xml. هذا الصف تتحكم في عرض "مجموعة الأدوات" ويمكنها (اختياريًا) عرض حالة التنقل بيانات واجهة برمجة التطبيقات.
2. خلال "onCreate()"، يمكنك استخدام هذه الخدمة لإعداد الاتصال مع أجهزة العرض. تشمل الخيارات ما يلي:
   • عليك تحديد الشاشة الثانوية المراد استخدامها في مجموعة الأدوات.
   • أنشئ شاشة عرض افتراضية لكي يعرض تطبيق "مجموعة الأدوات" وينقل الصورة المعروضة على وحدة خارجية (باستخدام تنسيق بث فيديو مثل H.264).
3. عندما تكون الشاشة المشار إليها أعلاه جاهزة، يجب على هذه الخدمة الاتصال InstrumentClusterRenderingService#setClusterActivityLaunchOptions() للتعريف قيمة ActivityOptions الدقيقة التي يجب استخدامها لعرض نشاط على مجموعة الآلات. استخدام هذه المعلمات:
   • category. ClusterRenderingService.
   • ActivityOptions. مثيل ActivityOptions الذي يمكن المستخدم لإطلاق نشاط في مجموعة الأدوات. على سبيل المثال، من العينة تنفيذ مجموعة الأدوات على AOSP:

     getService().setClusterActivityLaunchOptions(
       CATEGORY_NAVIGATION,
       ActivityOptions.makeBasic()
           .setLaunchDisplayId(displayId));

4. عندما تكون "مجموعة الأدوات" جاهزة لعرض الأنشطة، يجب استدعاء هذه الخدمة InstrumentClusterRenderingService#setClusterActivityState() استخدام هذه المَعلمات:
   • category ClusterRenderingService.
   • تم إنشاء حزمة واحدة (state) باستخدام ClusterRenderingService. تأكَّد من تقديم هذه البيانات:
     • visible: تحدد مجموعة الأدوات على أنها مرئية وجاهزة عرض المحتوى.
     • unobscuredBounds مستطيل يحدد المساحة داخل عرض مجموعة الأدوات التي يمكن من خلالها عرض المحتوى بأمان على سبيل المثال، المناطق مغطاة بالأقراص والمقاييس.
5. إلغاء طريقة Service#dump() والإبلاغ عن معلومات الحالة المفيدة لتصحيح الأخطاء (راجِع dumpsys للحصول على مزيد من المعلومات).

نموذج تنفيذ instrumentClusterRenderingService

يوضّح المثال التالي InstrumentClusterRenderingService التنفيذ، الذي ينشئ VirtualDisplay لعرض الأداة تجميع المحتوى على شاشة فعلية عن بُعد

بدلاً من ذلك، يمكن لهذا الرمز أن يجتاز displayId للترميز الثانوي الفعلي. شاشة متصلة بوحدة HU، إذا كانت معروفة بتوفرها.

/**
* Sample {@link InstrumentClusterRenderingService} implementation
*/
public class SampleClusterServiceImpl extends InstrumentClusterRenderingService {
   // Used to retrieve or create displays
   private final DisplayManager mDisplayManager;
   // Unique identifier for the display to be used for instrument
   // cluster
   private final String mUniqueId = UUID.randomUUID().toString();
   // Format of the instrument cluster display
   private static final int DISPLAY_WIDTH = 1280;
   private static final int DISPLAY_HEIGHT = 720;
   private static final int DISPLAY_DPI = 320;
   // Area not covered by instruments
   private static final int DISPLAY_UNOBSCURED_LEFT = 40;
   private static final int DISPLAY_UNOBSCURED_TOP = 0;
   private static final int DISPLAY_UNOBSCURED_RIGHT = 1200;
   private static final int DISPLAY_UNOBSCURED_BOTTOM = 680;
   @Override
   public void onCreate() {
      super.onCreate();
      // Create a virtual display to render instrument cluster activities on
      mDisplayManager = getSystemService(DisplayManager.class);
      VirtualDisplay display = mDisplayManager.createVirtualDisplay(
          mUniqueId, DISPLAY_WIDTH, DISPLAY_HEIGHT, DISPLAY_DPI, null,
          0 /* flags */, null, null);
      // Do any additional initialization (e.g.: start a video stream
      // based on this virtual display to present activities on a remote
      // display).
      onDisplayReady(display.getDisplay());
}
private void onDisplayReady(Display display) {
    // Report activity options that should be used to launch activities on
    // the instrument cluster.
    String category = CarInstrumentClusterManager.CATEGORY_NAVIGATION;
    ActionOptions options = ActivityOptions.makeBasic()
        .setLaunchDisplayId(display.getDisplayId());
    setClusterActivityOptions(category, options);
    // Report instrument cluster state.
    Rect unobscuredBounds = new Rect(DISPLAY_UNOBSCURED_LEFT,
        DISPLAY_UNOBSCURED_TOP, DISPLAY_UNOBSCURED_RIGHT,
        DISPLAY_UNOBSCURED_BOTTOM);
    boolean visible = true;
    ClusterActivityState state = ClusterActivityState.create(visible,
       unobscuredBounds);
    setClusterActivityState(category, options);
  }
}

استخدام واجهة برمجة التطبيقات CarAppFocusManager

توفّر واجهة برمجة التطبيقات CarAppFocusManager طريقة تُسمى getAppTypeOwner()، تتيح خدمة التجميع العنقودي التي كتبها المصنّعون الأصليون للأجهزة لمعرفة تطبيق التنقل الذي يركز على التنقل في أي وقت الوقت. يمكن للمصنّعين الأصليين للأجهزة استخدام طريقة CarAppFocusManager#addFocusListener() الحالية ثم استخدام getAppTypeOwner() لمعرفة التطبيق محل التركيز. باستخدام هذه المعلومات، يمكن للمصنّعين الأصليين للأجهزة تنفيذ ما يلي:

• تبديل النشاط المعروض في المجموعة إلى نشاط المجموعة الذي يوفره تطبيق التنقل الضغط المستمر على التركيز.
• يمكن رصد ما إذا كان تطبيق التنقّل الذي يتم التركيز عليه يحتوي على نشاط مجموعة أم لا. إذا تم التركيز على لا يحتوي تطبيق التنقل على نشاط مجموعة (أو إذا تم إيقاف هذا النشاط)، يمكن للمصنّعين الأصليين ترسل هذه الإشارة إلى DIM للسيارة بحيث يتم تخطي واجهة التنقل في المجموعة تمامًا.

استخدِم CarAppFocusManager لضبط التركيز الحالي للتطبيق والاستماع إليه، مثلاً التنقل النشط أو طلب صوتي. وعادةً ما يتم تنشيط مثيل واحد فقط من هذا التطبيق تشغيل (أو التركيز) في النظام.

استخدام طريقة CarAppFocusManager#addFocusListener(..) للاستماع إلى تركيز التطبيق التغييرات:

import android.car.CarAppFocusManager;

...

Car car = Car.createCar(this);
mAppFocusManager = (CarAppFocusManager)car.getCarManager(Car.APP_FOCUS_SERVICE);
mAppFocusManager.addFocusListener(this, CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION);

...

public void onAppFocusChanged(int appType, boolean active) {
    // Use the CarAppFocusManager#getAppTypeOwner(appType) method call
    // to retrieve a list of active package names
}

استخدام الطريقة CarAppFocusManager#getAppTypeOwner(..) لاسترداد الحزمة اسم المالك الحالي لنوع تطبيق معيّن محلّ التركيز. قد تعرض هذه الطريقة أكثر من اسم حزمة واحد إذا كان المالك الحالي يستخدم ميزة android:sharedUserId.

import android.car.CarAppFocusManager;

...

Car car = Car.createCar(this);
mAppFocusManager = (CarAppFocusManager)car.getCarManager(Car.APP_FOCUS_SERVICE);
List<String> focusOwnerPackageNames = mAppFocusManager.getAppTypeOwner(
              CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION);

if (focusOwnerPackageNames == null || focusOwnerPackageNames.isEmpty()) {
        // No Navigation app has focus
        // OEM may choose to show their default cluster view
} else {
       // focusOwnerPackageNames
       // Use the PackageManager to retrieve the cluster activity for the package(s)
       // returned in focusOwnerPackageNames
}

...

الملحق: استخدام نموذج التطبيق

يوفّر AOSP نموذج تطبيق ينفِّذ واجهة برمجة تطبيقات حالة التنقّل.

لتشغيل هذا التطبيق النموذجي:

1. يمكنك إنشاء Android Auto وتحديثه على وحدة معالجة مركزية (HU) متوافقة. يمكنك استخدام إرشادات بشأن إنشاء إصدار Android ووميض خاصة بجهازك للحصول على التعليمات، يُرجى الاطّلاع على استخدام اللوحات المرجعية:
2. توصيل شاشة ثانوية مادية بوحدة HU (إذا كانت متوافقة) أو تفعيل الشاشة الافتراضية HU الثانوي:
   1. اختَر وضع مطور البرامج في تطبيق "الإعدادات".
   2. انتقِل إلى الإعدادات > النظام > متقدم > خيارات المطوّرين > محاكاة الشاشات الثانوية
3. إعادة تشغيل HU
4. لتشغيل تطبيق KitchenSink:
   1. افتح الدرج.
   2. انتقِل إلى Inst. المجموعة.
   3. انقر على بدء البيانات الوصفية.

يطلب KitchenSink عنصر التركيز على التنقُّل، والذي يوجِّه تعليمات إلى DirectRenderingCluster خدمة عرض واجهة مستخدم نموذجية على مجموعة الأدوات.