اعمال مرور سفارشی را اجرا کنید

مشابه نحوه استفاده از کنش‌های پخش سفارشی برای پشتیبانی از قابلیت‌های منحصربه‌فرد در نمای بازپخش، می‌توانید از کنش‌های مرور سفارشی برای پشتیبانی از قابلیت‌های منحصربه‌فرد در نماهای مرور استفاده کنید. برای مثال، می‌توانید از عملکردهای مرور سفارشی استفاده کنید تا کاربران بتوانند لیست‌های پخش را دانلود کنند یا یک مورد را به صف اضافه کنند.

هنگامی که اقدامات سفارشی بیشتری نسبت به نمایش داده شده توسط سازنده تجهیزات اصلی (OEM) وجود داشته باشد، یک منوی سرریز به کاربر نمایش داده می شود. هر اقدام مرور سفارشی با یک تعریف می شود:

  • شناسه اقدام: شناسه رشته منحصر به فرد
  • برچسب اقدام: متن نمایش داده شده به کاربر
  • Action icon Resource identifier (URI): وکتور قابل ترسیم که می تواند رنگ آمیزی شود

سرریز عملکرد مرور سفارشی

شکل 1. سرریز عمل مرور سفارشی.

شما فهرستی از اقدامات مرور سفارشی را در سطح جهانی به عنوان بخشی از BrowseRoot خود تعریف می کنید. سپس زیر مجموعه ای از این اقدامات را به MediaItem فردی پیوست کنید.

وقتی کاربر با یک عملکرد مرور سفارشی تعامل می‌کند، برنامه شما در onCustomAction یک تماس پاسخ دریافت می‌کند. سپس این اکشن را انجام می‌دهید و در صورت لزوم فهرست اقدامات MediaItem را به‌روزرسانی می‌کنید. این برای اقدامات حالتی مانند Favorite و Download مفید است. برای کنش‌هایی که نیازی به به‌روزرسانی ندارند، مانند Play Radio، لازم نیست فهرست کنش‌ها را به‌روزرسانی کنید.

نوار ابزار اقدام مرور سفارشی

شکل 2. نوار ابزار اقدام مرور سفارشی.

همچنین می‌توانید اقدامات مرور سفارشی را به ریشه گره مرور پیوست کنید. این اقدامات در یک نوار ابزار ثانویه در زیر نوار ابزار اصلی نمایش داده می شوند.

برای افزودن عملکردهای مرور سفارشی به برنامه خود:

  1. دو روش را در اجرای MediaBrowserServiceCompat خود لغو کنید:

  2. محدودیت های عمل را در زمان اجرا تجزیه کنید:

    در onGetRoot ، با استفاده از کلید BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT در rootHints Bundle ، حداکثر تعداد اعمال مجاز را برای هر MediaItem دریافت کنید. محدودیت 0 نشان می دهد که این ویژگی توسط سیستم پشتیبانی نمی شود.

  3. فهرست جهانی اقدامات مرور سفارشی را بسازید. برای هر عمل، یک شی Bundle با این کلیدها ایجاد کنید:

    • شناسه اقدام EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID
    • برچسب اقدام EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL
    • نماد اقدام URI EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI

  4. تمام اشیاء Action Bundle را به یک لیست اضافه کنید.

  5. لیست جهانی را به BrowseRoot خود اضافه کنید. در BrowseRoot Bundle با استفاده از کلید BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST ، فهرستی از اقدامات را به‌عنوان ArrayList Parcelable اضافه کنید.

  6. اعمالی را به اشیاء MediaItem خود اضافه کنید. می‌توانید با استفاده از کلید DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST ، کنش‌ها را با گنجاندن فهرست شناسه‌های کنش در موارد اضافی MediaDescriptionCompat به اشیاء جداگانه MediaItem اضافه کنید. این لیست باید زیرمجموعه ای از فهرست جهانی اقداماتی باشد که در BrowseRoot تعریف کرده اید.

  7. مدیریت اقدامات و بازگشت پیشرفت یا نتایج:

    • در onCustomAction ، عملکرد را بر اساس شناسه اقدام و هر داده دیگری که نیاز دارید مدیریت کنید. با استفاده از کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID می‌توانید شناسه MediaItem را که این عمل را آغاز کرده است، از موارد اضافی دریافت کنید.

    • با قرار دادن کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM در بسته پیشرفت یا نتیجه، می‌توانید فهرست اقدامات یک MediaItem را به‌روزرسانی کنید.

وضعیت عملکرد را به روز کنید

برای لغو این روش ها در 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)
}

یک اقدام مرور سفارشی بسازید

هر عمل باید در یک 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>")

اعمال مرور سفارشی را به Parcelable ArrayList اضافه کنید

تمام اشیاء 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 اضافه کنید

شناسه‌های Browse Actions در 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);

بر روی نتیجه 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. نتیجه را بررسی کنید:

    • خطا: call result.sendError(resultBundle)
    • به روز رسانی پیشرفت: call result.sendProgressUpdate(resultBundle)
    • پایان: فراخوانی result.sendResult(resultBundle)

وضعیت عملکرد را به روز کنید

با استفاده از روش result.sendProgressUpdate(resultBundle) با کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM ، می توانید MediaItem به روز کنید تا وضعیت جدید عملکرد را منعکس کند. این به شما امکان می‌دهد در زمان واقعی به کاربر در مورد پیشرفت و نتیجه عملکرد او بازخورد ارائه دهید.

نمونه اقدام دانلود

این مثال توضیح می دهد که چگونه می توانید از این ویژگی برای اجرای یک اقدام دانلود با سه حالت استفاده کنید:

  • دانلود حالت اولیه اکشن است. وقتی کاربر این عمل را انتخاب کرد، می‌توانید آن را با Downloading تعویض کنید و sendProgressUpdate را برای به‌روزرسانی رابط کاربری (UI) فراخوانی کنید.

  • وضعیت دانلود نشان می دهد که دانلود در حال انجام است. می توانید از این حالت برای نشان دادن نوار پیشرفت یا نشانگر دیگری به کاربر استفاده کنید.

  • حالت دانلود شده نشان می دهد که دانلود کامل شده است. وقتی بارگیری تمام شد، می‌توانید Downloading را با Downloaded تعویض کنید و sendResult با کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM فراخوانی کنید تا نشان دهید که مورد باید به‌روزرسانی شود. علاوه بر این، می توانید از کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE برای نمایش پیام موفقیت آمیز به کاربر استفاده کنید.

این رویکرد به شما امکان می دهد بازخورد واضحی در مورد فرآیند دانلود و وضعیت فعلی آن به کاربر ارائه دهید. می توانید جزئیات بیشتری را با نمادها اضافه کنید تا وضعیت های دانلود 25٪، 50٪ و 75٪ را نشان دهید.

نمونه اقدام مورد علاقه

مثال دیگر یک عمل مورد علاقه با دو حالت است:

  • موارد دلخواه برای مواردی که در لیست علاقه مندی های کاربر نیستند نمایش داده می شود. وقتی کاربر این عملکرد را انتخاب کرد، آن را با Favorited عوض کنید و sendResult با کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM برای به روز رسانی رابط کاربری فراخوانی کنید.

  • موارد دلخواه برای موارد موجود در لیست علاقه مندی های کاربر نمایش داده می شود. وقتی کاربر این عملکرد را انتخاب کرد، آن را با Favorite تعویض کنید و sendResult با کلید EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM برای به روز رسانی رابط کاربری فراخوانی کنید.

این رویکرد راهی واضح و ثابت را برای کاربران فراهم می کند تا آیتم های مورد علاقه خود را مدیریت کنند. این مثال‌ها انعطاف‌پذیری عملکردهای مرور سفارشی و نحوه استفاده از آن‌ها را برای پیاده‌سازی انواع عملکردها با بازخورد بلادرنگ برای یک تجربه کاربری پیشرفته در برنامه رسانه خودرو نشان می‌دهند.

نمونه جامع پیاده سازی این قابلیت را می توانید در پروژه TestMediaApp مشاهده کنید.

قبلی
نمایش نتایج جستجوی قابل مرور