تجربة الدرس التطبيقي حول AppCard

توضّح هذه الصفحة كيفية تنفيذ AppCard.

الخطوة 1: إضافة جميع عمليات الاستيراد

1. لإضافة عمليات الاستيراد:

   static_libs: [
        …
        "car-app-card",
   ],
   

الخطوة 2: إضافة SimpleAppCardContentProvider إلى ملف البيان

1. تأكَّد من استبدال android:authorities (بالخط الغامق) باسم الحزمة.

   <!-- App Card Content Provider that is required to communicate
        relevant App Cards with the system
        android.car.permission.BIND_APP_CARD_PROVIDER is an essential permission
        that will only allow the system to communicate with the
        AppCardContentProvider
        The content provider must also be exported and enabled -->
        <provider android:name=".SimpleAppCardContentProvider"
            android:authorities="com.example.appcard.sample" 
            android:permission="@string/host_permission"
            android:exported="true"
            android:enabled="true">
            <intent-filter>
               <!-- This intent filter will allow the system to find and
                    connect with the application's AppCardContentProvider -->
                <action android:name="com.android.car.appcard.APP_CARD_PROVIDER" />
               </intent-filter>
        </provider>
   

الخطوة 3: إضافة SimpleAppCardContentProvider إلى ملف البيان

1. لإضافة SimpleAppCardContentProvider إلى ملف البيان، اتّبِع الخطوات التالية:

   class SimpleAppCardContentProvider : AppCardContentProvider() {
     /** Must return same authority as defined in manifest */
     override val authority: String = AUTHORITY
   
     /** Setup [AppCardContentProvider] and its constituents */
     override fun onCreate(): Boolean {
       return super.onCreate()
     }
   
     /** Setup an [AppCard] that is being requested */
     override fun onAppCardAdded(id: String, ctx: AppCardContext): AppCard {
       return when (id) {
         APPCARD_ID -> //TODO: create app card
   
         else -> throw IllegalStateException("Unidentified app card ID: $id")
       }
     }
   
     /** List of supported [AppCard] IDs */
   ​   ​override val appCardIds: List<String> = listOf(APPCARD_ID).toMutableList()
   
     /** Clean up when an [AppCard] is removed */
     override fun onAppCardRemoved(id: String) {
       when (id) {
         APPCARD_ID -> //TODO: create app card
       }
     }
   
     /** Handle an [AppCardContext] change for a particular [AppCard] ID */
     override fun onAppCardContextChanged(
       id: String,
       appCardContext: AppCardContext
     ) {
        when (id) {
         APPCARD_ID -> //TODO: update AppCardContext
       }
     }
   
     companion object {
       private const val AUTHORITY = "com.example.appcard.sample"
       private const val APPCARD_ID = "sampleAppCard"
     }
   }
   

الخطوة 4: إنشاء AppCard

1. لإنشاء بطاقة AppCard، اتّبِع الخطوات التالية:

   override fun onAppCardAdded(id: String, ctx: AppCardContext): AppCard {
     return when (id) {
       APPCARD_ID -> createAppCard(ctx)
   
       else -> throw IllegalStateException("Unidentified app card ID: $id")
     }
   }
   
   private fun createAppCard(appCardContext: AppCardContext): ImageAppCard {
     return ImageAppCard.newBuilder(APPCARD_ID)
       .setPrimaryText("Hello")
       .setSecondaryText("World")
       .setHeader(
         Header.newBuilder("header")
           .setTitle("Code Lab")
           .build()
       )
       .addButton(
         Button.newBuilder(
           "button",
           Button.ButtonType.PRIMARY,
           object : OnClickListener {
             override fun onClick() {
               //no-op
             }
           }
         )
           .setText("Click me!")
           .build()
       )
      .build()
   }
   

مثلاً:

الشكل 1: أنشئ AppCard.

الخطوة 5: تفعيل أداة النقر على الأزرار

لتفعيل جهاز النقر، اتّبِع الخطوات التالية:

   private var clickCounter = 0

   private fun createAppCard(appCardContext: AppCardContext): ImageAppCard {
      ...
       .addButton(
        Button.newBuilder(
          "button",
           Button.ButtonType.PRIMARY,
           object : OnClickListener {
             override fun onClick() {
               clickCounter++
               sendAppCardUpdate(createAppCard(appCardContext))
             }
           }
         )
           .setText(
             if (clickCounter == 0) "Click me!" else "Clicked: $clickCounter"
           )
           .build()
         )
      ...
    }

    override fun onAppCardRemoved(id: String) {
      when (id) {
        APPCARD_ID -> clickCounter = 0
      }
    }

مثلاً:

الشكل 2: فعِّل أداة النقر على الأزرار.

الخطوة 6: تعديل صورة العنوان

1. لتعديل الصورة في العنوان:

     private fun createAppCard(appCardContext: AppCardContext): ImageAppCard {
       val headerImageSize = appCardContext.imageAppCardContext.getMaxImageSize(Header::class.java)
       val logo = resToBitmap(
        android.R.drawable.ic_menu_compass,
          headerImageSize.width,
          headerImageSize.height
       )
   
    ...
      .setHeader(
        Header.newBuilder("header")
          .setTitle("Code Lab")
          .setImage(
            Image.newBuilder("image")
              .setContentScale(Image.ContentScale.FILL_BOUNDS)
              .setColorFilter(Image.ColorFilter.TINT)
              .setImageData(logo)
              .build()
          )
          .build()
       )
     ...
     }
   
     private fun resToBitmap(res: Int, width: Int, height: Int): Bitmap {
       val drawable = context?.getDrawable(res)
   
       return drawableToBitmap(drawable!!, width, height)
     }
   
     private fun drawableToBitmap(d: Drawable, width: Int, height: Int): Bitmap {
       val bitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
   
       val canvas = Canvas(bitmap)
       val left = 0
       val top = 0
       d.setBounds(left, top, canvas.width, canvas.height)
       d.draw(canvas)
   
       return bitmap
    }
    ```
   
   For example:
   
   ![Change the image in the header](/docs/automotive/unbundled_apps/appcards/images/ceramic-06.png)
   
   **Figure 3.** Change the name to the header.
   

2. كرِّر هذه العملية لإضافة صورة إلى أي مكوّن يتيح ذلك.

الخطوة 7: إضافة المزيد من التفاعلات

1. لإنشاء شريط تقدّم يتضمّن عناصر تحكّم، اتّبِع الخطوات التالية:

    private var progressOn = false
   
    private var progressTimer: Timer? = null
   
    private var progressCounter = 0
   
    override fun onAppCardRemoved(id: String) {
      when (id) {
        APPCARD_ID -> {
          clickCounter = 0
          progressCounter = 0
          progressTimer?.cancel()
        }
      }
    }
   
    private fun createAppCard(appCardContext: AppCardContext): ImageAppCard {
      val buttonImageSize = appCardContext.imageAppCardContext.getMaxImageSize(Button::class.java)
      val progressPlayPauseImage = resToBitmap(
        if (progressOn) {
          android.R.drawable.ic_media_pause
        } else {
          android.R.drawable.ic_media_play
        },
        buttonImageSize.width,
        buttonImageSize.height
      )
      ...
        .setProgressBar(
          createProgressBar()
        )
        .addButton(
          Button.newBuilder(
            "progressButton",
            Button.ButtonType.NO_BACKGROUND,
            object : OnClickListener {
              override fun onClick() {
                progressOn = !progressOn
                if (progressOn) {
                  progressTimer = Timer()
                  progressTimer?.scheduleAtFixedRate(object : TimerTask() {
                    override fun run() {
                    progressCounter++
                    if (progressCounter > 60) progressCounter = 0
                    sendAppCardComponentUpdate(APPCARD_ID, createProgressBar())
                  }
                }, SECONDS_TO_MS, SECONDS_TO_MS)
              } else {
                progressTimer?.cancel()
                progressTimer = null
              }
              sendAppCardUpdate(createAppCard(appCardContext))
            }
          }
        )
          .setImage(
            Image.newBuilder("buttonImage")
              .setContentScale(Image.ContentScale.FILL_BOUNDS)
              .setColorFilter(Image.ColorFilter.TINT)
              .setImageData(progressPlayPauseImage)
              .build()
          )
          .build()
      )
    ...
    }
   
    private fun createProgressBar(): ProgressBar {
      return ProgressBar.newBuilder(PROGRESS_BAR_ID, 0, 60)
        .setProgress(progressCounter)
        .build()
    }
   
    companion object {
      ...
      private const val PROGRESS_BAR_ID = "progress"
      private const val SECONDS_TO_MS = 1000L
    }
   

أضفنا زر تشغيل أو إيقاف مؤقت إلى شريط التقدم يمكن تعديله كل ثانية. بسبب قيود الحجم، يمكنك الاطّلاع على setText على زر النقر الذي تمت إضافته لعرض عدد النقرات، .setText("$clickCounter")

الشكل 4. أضِف زرًا.

الشكل 5. زر معروض

الخطوة 8: بدء النشاط

1. إذا كان تطبيقك متوافقًا مع background-starts#exceptions، يمكنك تشغيل نشاط من onClickListener الزر.

   class SampleRoutingActivity : AppCompatActivity() {
     override fun onStart() {
       super.onStart()
       val intent = Intent(ACTION_LOCATION_SOURCE_SETTINGS).apply {
         setFlags(FLAG_ACTIVITY_CLEAR_TOP)
       }
       startActivity(intent)
       finish()
     }
   }
   

2. لبدء النشاط، أضِف زرًا في AppCard. إذا لم يكن هناك أي نشاط، أضِف نشاط توجيه إلى تطبيقك:

   override fun onStart() {
   super.onStart()
   val intent = Intent(ACTION_LOCATION_SOURCE_SETTINGS).apply {
     setFlags(FLAG_ACTIVITY_CLEAR_TOP)
   }
   startActivity(intent)
   finish()
    }
   }
   

   عند استدعاء الفئة، تتم إعادة توجيه المستخدم إلى إعدادات الموقع الجغرافي. يتم تطبيق setFlags(FLAG_ACTIVITY_CLEAR_TOP) لضمان عدم تمكّن المستخدم من الرجوع إلى النشاط الأصلي.

3. أضِف زرًا في AppCard لبدء النشاط:

    private fun createAppCard(appCardContext: AppCardContext): ImageAppCard {
      val locationImage = resToBitmap(
        android.R.drawable.ic_menu_call,
        buttonImageSize.width,
        buttonImageSize.height
      )
      ...
        .addButton(
          Button.newBuilder(
           "activityButton",
           Button.ButtonType.SECONDARY,
           object : OnClickListener {
             override fun onClick() {
               // no-op
             }
           }
          )
           .setImage(
             Image.newBuilder("locationButtonImage")
               .setContentScale(Image.ContentScale.FILL_BOUNDS)
               .setColorFilter(Image.ColorFilter.TINT)
               .setImageData(locationImage)
               .build()
           )
           .setIntent(
             RoutingActivityIntent
               .newBuilder("com.example.appcard.sample.SampleRoutingActivity")
               .build()
           )
           .build()
         )
       ...
   }
   

بسبب قيود المساحة، تمت إزالة زر النقر في مضيف AppCard. تظهر بطاقة AppCard على النحو التالي:

الشكل 6. AppCard بدون زر النقر