ใช้การดำเนินการเรียกดูที่กำหนดเอง

เช่นเดียวกับวิธีใช้การดำเนินการเล่นที่กำหนดเองเพื่อรองรับความสามารถเฉพาะตัวในมุมมองการเล่น คุณสามารถใช้การดำเนินการเรียกดูที่กำหนดเองเพื่อรองรับความสามารถเฉพาะตัวในมุมมองการเรียกดูได้ เช่น คุณสามารถใช้การเรียกดูที่กำหนดเอง เพื่อให้ผู้ใช้ดาวน์โหลดเพลย์ลิสต์หรือเพิ่มรายการลงในคิวได้

เมื่อมีการดำเนินการที่กำหนดเองมากกว่าที่ผู้ผลิตอุปกรณ์ดั้งเดิม (OEM) แสดง ระบบจะแสดงเมนูแบบเลื่อนลงต่อผู้ใช้ การดำเนินการเรียกดูที่กำหนดเองแต่ละรายการจะกำหนดด้วยข้อมูลต่อไปนี้

• รหัสการดำเนินการ: ตัวระบุสตริงที่ไม่ซ้ำกัน
• ป้ายกำกับการดำเนินการ: ข้อความที่แสดงต่อผู้ใช้
• Uniform Resource Identifier (URI) ของไอคอนการดำเนินการ: Vector Drawable ที่ สามารถปรับสีได้

รูปที่ 1 เมนูแบบเลื่อนลงของการดำเนินการเรียกดูที่กำหนดเอง

คุณกำหนดรายการการดำเนินการเรียกดูที่กำหนดเองทั่วโลกเป็นส่วนหนึ่งของ BrowseRoot จากนั้นแนบชุดย่อยของการดำเนินการเหล่านี้กับMediaItem

เมื่อผู้ใช้โต้ตอบกับการเรียกดูที่กำหนดเอง แอปของคุณจะได้รับการเรียกกลับ ใน onCustomAction จากนั้นคุณจะจัดการการดำเนินการและอัปเดตรายการการดำเนินการสำหรับ MediaItem หากจำเป็น ซึ่งจะเป็นประโยชน์สำหรับการดำเนินการแบบเก็บสถานะ เช่น รายการโปรดและการดาวน์โหลด สำหรับการดำเนินการที่ไม่จำเป็นต้องอัปเดต เช่น Play Radio คุณไม่จำเป็นต้องอัปเดตรายการการดำเนินการ

รูปที่ 2 แถบเครื่องมือการดำเนินการเรียกดูที่กำหนดเอง

นอกจากนี้ คุณยังแนบการดำเนินการเรียกดูที่กำหนดเองกับรูทของโหนดการเรียกดูได้ด้วย การดำเนินการเหล่านี้ จะแสดงในแถบเครื่องมือรองใต้แถบเครื่องมือหลัก

วิธีเพิ่มการดำเนินการเรียกดูที่กำหนดเองลงในแอป

1. ลบล้าง 2 วิธีต่อไปนี้ในการติดตั้งใช้งาน MediaBrowserServiceCompat

   • onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)
   • onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)

2. แยกวิเคราะห์ขีดจํากัดการดำเนินการที่รันไทม์

   ใน onGetRoot ให้รับจำนวนการดำเนินการสูงสุดที่อนุญาตสำหรับแต่ละ MediaItemโดยใช้คีย์ BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT ใน rootHints Bundle ขีดจำกัด 0 แสดงว่าระบบไม่รองรับฟีเจอร์นี้

3. สร้างรายการการกระทำในการเรียกดูที่กำหนดเองส่วนกลาง สำหรับการดำเนินการแต่ละอย่าง ให้สร้างออบเจ็กต์ Bundle ที่มีคีย์ต่อไปนี้

   • รหัสการดำเนินการ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID
   • ป้ายกำกับการดำเนินการ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL
   • URI ของไอคอนการดำเนินการ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI

4. เพิ่มออบเจ็กต์การดำเนินการทั้งหมด Bundle ลงในรายการ

5. เพิ่มรายการส่วนกลางลงใน BrowseRoot ใน BrowseRoot extras Bundle ให้เพิ่มรายการการดำเนินการเป็น Parcelable ArrayList โดยใช้คีย์ BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST

6. เพิ่มการดำเนินการไปยังMediaItemออบเจ็กต์ คุณเพิ่มการดำเนินการไปยังออบเจ็กต์ MediaItemแต่ละรายการได้โดยใส่รายการรหัสการดำเนินการใน MediaDescriptionCompatส่วนเพิ่มเติมโดยใช้คีย์ DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST รายการนี้ต้อง เป็นชุดย่อยของรายการการดำเนินการส่วนกลางที่คุณกำหนดไว้ใน BrowseRoot

7. จัดการการดำเนินการและแสดงความคืบหน้าหรือผลลัพธ์

   • ใน onCustomAction ให้จัดการการดำเนินการตามรหัสการดำเนินการและข้อมูลอื่นๆ ที่คุณต้องการ คุณรับรหัสของ MediaItem ที่ทริกเกอร์การดำเนินการจากส่วนเสริมได้โดยใช้คีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID

   • คุณอัปเดตรายการการดำเนินการสำหรับ MediaItem ได้โดยใส่คีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM ในชุดผลลัพธ์หรือชุดความคืบหน้า

อัปเดตสถานะการดำเนินการ

หากต้องการลบล้างวิธีการเหล่านี้ใน MediaBrowserServiceCompat ให้ทำดังนี้

public void onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)

และ

public void onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)

ขีดจำกัดการแยกวิเคราะห์การกระทำ

ตรวจสอบว่าระบบรองรับการดำเนินการเรียกดูที่กำหนดเองกี่รายการ

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid, Bundle rootHints) {
    rootHints.getInt(
            MediaConstants.BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT, 0)
}

หมายเหตุ: ขีดจํากัดการดําเนินการที่ 0 หรือน้อยกว่าแสดงว่าระบบไม่รองรับฟีเจอร์นี้

สร้างการเรียกดูที่กำหนดเอง

โดยแต่ละการกระทำจะต้องรวมอยู่ใน Bundle แยกกัน

• รหัสการดำเนินการ:

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                  "<ACTION_ID>")
  

• ป้ายกำกับการดำเนินการ:

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                  "<ACTION_LABEL>")
  

• URI ของไอคอนการดำเนินการ

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                  "<ACTION_ICON_URI>")
  

เพิ่มการกระทำในการเรียกดูที่กำหนดเองลงใน ArrayList ของ Parcelable

เพิ่มออบเจ็กต์การกระทำในการเรียกดูที่กำหนดเองทั้งหมด Bundle ลงใน ArrayList

private ArrayList<Bundle> createCustomActionsList(
                                        CustomBrowseAction browseActions) {
    ArrayList<Bundle> browseActionsBundle = new ArrayList<>();
    for (CustomBrowseAction browseAction : browseActions) {
        Bundle action = new Bundle();
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                browseAction.mId);
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                getString(browseAction.mLabelResId));
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                browseAction.mIcon);
        browseActionsBundle.add(action);
    }
    return browseActionsBundle;
}

เพิ่มรายการการดำเนินการเรียกดูที่กำหนดเองไปยังรูทการเรียกดู

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid,
                             Bundle rootHints) {
    Bundle browserRootExtras = new Bundle();
    browserRootExtras.putParcelableArrayList(
            BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST,
            createCustomActionsList()));
    mRoot = new BrowserRoot(ROOT_ID, browserRootExtras);
    return mRoot;
}

เพิ่มการดำเนินการไปยัง MediaItem

รหัสการเรียกดูใน MediaItem ต้องเป็นชุดย่อยของรายการการเรียกดูส่วนกลางที่ระบุใน onGetRoot ระบบจะไม่สนใจการดำเนินการที่ไม่อยู่ในรายการส่วนกลาง

MediaDescriptionCompat buildDescription (long id, String title, String subtitle,
                String description, Uri iconUri, Uri mediaUri,
                ArrayList<String> browseActionIds) {

    MediaDescriptionCompat.Builder bob = new MediaDescriptionCompat.Builder();
    bob.setMediaId(id);
    bob.setTitle(title);
    bob.setSubtitle(subtitle);
    bob.setDescription(description);
    bob.setIconUri(iconUri);
    bob.setMediaUri(mediaUri);

    Bundle extras = new Bundle();
    extras.putStringArrayList(
          DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST,
          browseActionIds);

    bob.setExtras(extras);
    return bob.build();
}
MediaItem mediaItem = new MediaItem(buildDescription(...), flags);

หมายเหตุ: ใส่เฉพาะรหัสการดำเนินการ String ใน MediaItem ระบบจะแมปรหัสจาก รายการส่วนกลางที่ส่งไปยัง BrowseRoot

สร้างผลลัพธ์ CustomAction

วิธีสร้างผลลัพธ์

1. แยกวิเคราะห์ mediaId จาก Bundle extras

   @Override
   public void onCustomAction(
               @NonNull String action, Bundle extras, @NonNull Result<Bundle> result){
       String mediaId = extras.getString(MediaConstans.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID);
               }
   

2. สำหรับผลลัพธ์แบบอะซิงโครนัส ให้แยกผลลัพธ์ result.detach

3. สร้างแพ็กเกจผลลัพธ์

   1. แสดงข้อความแก่ผู้ใช้

      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE,
                    mContext.getString(stringRes))
      

   2. อัปเดตรายการ (ใช้เพื่ออัปเดตการดำเนินการในรายการ)

      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, mediaId);
      

   3. เปิดมุมมองการเล่นโดยทำดังนี้

      //Shows user the PBV without changing the playback state
      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_SHOW_PLAYING_ITEM, null);
      

   4. อัปเดตโหนดการเรียกดูโดยทำดังนี้

      //Change current browse node to mediaId
      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_BROWSE_NODE, mediaId);
      

4. ตรวจสอบผลลัพธ์

   • ข้อผิดพลาด: โทร result.sendError(resultBundle)
   • อัปเดตความคืบหน้า: โทรหา result.sendProgressUpdate(resultBundle)
   • เสร็จสิ้น: โทร result.sendResult(resultBundle)

อัปเดตสถานะการดำเนินการ

การใช้เมธอด result.sendProgressUpdate(resultBundle) กับคีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM จะช่วยให้คุณอัปเดต MediaItem เพื่อแสดงสถานะใหม่ของการดำเนินการได้ ซึ่งช่วยให้คุณแสดงความคิดเห็นแบบเรียลไทม์แก่ผู้ใช้เกี่ยวกับความคืบหน้าและผลลัพธ์ของการดำเนินการได้

ตัวอย่างการดำเนินการดาวน์โหลด

ตัวอย่างนี้อธิบายวิธีใช้ฟีเจอร์นี้เพื่อใช้การดำเนินการดาวน์โหลดที่มี 3 สถานะ ดังนี้

• ดาวน์โหลดคือสถานะเริ่มต้นของการดำเนินการ เมื่อผู้ใช้เลือก การดำเนินการนี้ คุณสามารถสลับกับการดาวน์โหลดและเรียก sendProgressUpdate เพื่ออัปเดตอินเทอร์เฟซผู้ใช้ (UI)

• สถานะกำลังดาวน์โหลดแสดงว่าระบบกำลังดาวน์โหลด คุณสามารถ ใช้สถานะนี้เพื่อแสดงแถบความคืบหน้าหรือตัวบ่งชี้อื่นๆ แก่ผู้ใช้

• สถานะดาวน์โหลดแล้วแสดงว่าการดาวน์โหลดเสร็จสมบูรณ์ เมื่อ ดาวน์โหลดเสร็จแล้ว คุณสามารถสลับสถานะจากกำลังดาวน์โหลดเป็นดาวน์โหลดแล้ว และเรียกใช้ sendResultด้วยคีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM เพื่อระบุว่าควรรีเฟรชรายการ นอกจากนี้ คุณยังใช้คีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE เพื่อแสดงข้อความว่าดำเนินการสำเร็จแล้วต่อผู้ใช้ได้ด้วย

แนวทางนี้ช่วยให้คุณแสดงความคิดเห็นที่ชัดเจนแก่ผู้ใช้เกี่ยวกับกระบวนการดาวน์โหลด และสถานะปัจจุบัน คุณเพิ่มรายละเอียดได้ด้วยไอคอนเพื่อแสดงสถานะการดาวน์โหลด 25%, 50% และ 75%

ตัวอย่างการดำเนินการที่ชื่นชอบ

อีกตัวอย่างหนึ่งคือการดำเนินการที่ชื่นชอบซึ่งมี 2 สถานะ

• รายการโปรดจะแสดงสำหรับรายการที่ไม่ได้อยู่ในรายการโปรดของผู้ใช้ เมื่อผู้ใช้เลือกการดำเนินการนี้ ให้สลับกับการดำเนินการรายการโปรดและเรียกใช้ sendResult ด้วยคีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM เพื่ออัปเดต UI

• รายการโปรดจะแสดงสำหรับรายการในรายการโปรดของผู้ใช้ เมื่อผู้ใช้เลือกการดำเนินการนี้ ให้สลับกับการดำเนินการรายการโปรดและเรียกใช้ sendResult ด้วยคีย์ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM เพื่ออัปเดต UI

แนวทางนี้ช่วยให้ผู้ใช้จัดการรายการโปรดได้อย่างชัดเจนและสอดคล้องกัน ตัวอย่างเหล่านี้แสดงให้เห็นถึงความยืดหยุ่นของการดำเนินการเรียกดูที่กำหนดเอง และวิธีใช้เพื่อติดตั้งฟังก์ชันการทำงานที่หลากหลายพร้อม ความคิดเห็นแบบเรียลไทม์เพื่อประสบการณ์การใช้งานที่ดียิ่งขึ้นในแอปสื่อของรถยนต์

คุณดูตัวอย่างการใช้งานฟีเจอร์นี้อย่างละเอียดได้ในโปรเจ็กต์ TestMediaApp