Özel göz atma işlemleri uygulama

Oynatma görünümünde benzersiz özellikleri desteklemek için özel oynatma işlemleri'ni kullandığınız gibi, göz atma görünümlerinde benzersiz özellikleri desteklemek için özel göz atma işlemleri kullanabilirsiniz. Örneğin, kullanıcıların oynatma listelerini indirmesini veya bir öğeyi sıraya eklemesini sağlamak için özel göz atma işlemleri kullanabilirsiniz.

Orijinal Ekipman Üreticisi (OEM) tarafından gösterilenden daha fazla özel işlem olduğunda kullanıcıya taşma menüsü gösterilir. Her özel göz atma işlemi aşağıdakilerle tanımlanır:

  • İşlem kimliği: Benzersiz dize tanımlayıcısı
  • İşlem etiketi: Kullanıcıya gösterilen metin
  • İşlem simgesi tekdüzen kaynak tanımlayıcısı (URI): Renklendirilebilen vektör çizilebilir öğesi

Özel göz atma işlemi taşması

Şekil 1. Özel göz atma işlemi taşması.

BrowseRoot kapsamında genel olarak özel göz atma işlemleri listesi tanımlarsınız. Ardından bu işlemlerin bir alt kümesini bireysel MediaItem'lere ekleyin.

Kullanıcı, özel bir göz atma işlemiyle etkileşimde bulunduğunda uygulamanız onCustomAction içinde bir geri çağırma alır. Ardından işlemi gerçekleştirir ve gerekirse MediaItem için işlem listesini güncellersiniz. Bu, Favori ve İndir gibi durum bilgisi olan işlemler için kullanışlıdır. Radyo Çal gibi güncelleme gerektirmeyen işlemler için işlem listesini güncellemeniz gerekmez.

Özel göz atma işlemi araç çubuğu

Şekil 2. Özel göz atma işlemi araç çubuğu.

Ayrıca bir göz atma düğümü köküne özel göz atma işlemleri de ekleyebilirsiniz. Bu işlemler, birincil araç çubuğunun altındaki ikincil araç çubuğunda gösterilir.

Uygulamanıza özel göz atma işlemleri eklemek için:

  1. MediaBrowserServiceCompat uygulamanızda iki yöntemi geçersiz kılın:

  2. Çalışma zamanında işlem sınırlarını ayrıştırın:

    onGetRoot içinde, rootHints Bundle bölümündeki BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT anahtarını kullanarak her MediaItem için izin verilen maksimum işlem sayısını elde edin. 0 sınırı, özelliğin sistem tarafından desteklenmediğini gösterir.

  3. Özel göz atma işlemlerinin genel listesini oluşturun. Her işlem için aşağıdaki anahtarlara sahip bir Bundle nesnesi oluşturun:

    • İşlem kimliği EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID
    • İşlem etiketi EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL
    • İşlem simgesi URI'si EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI

  4. Tüm işlem Bundle nesnelerini bir listeye ekleyin.

  5. Global listeyi BrowseRoot öğenize ekleyin. BrowseRoot extras Bundle bölümünde, BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST anahtarını kullanarak işlem listesini Parcelable ArrayList olarak ekleyin.

  6. MediaItem nesnelerinize işlem ekleyin. İşlem kimliklerinin listesini DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST anahtarını kullanarak MediaDescriptionCompat ekstralarına dahil ederek işlemleri tek tek MediaItem nesnelerine ekleyebilirsiniz. Bu liste, BrowseRoot içinde tanımladığınız genel işlem listesinin bir alt kümesi olmalıdır.

  7. İşlemleri gerçekleştirme ve ilerleme durumunu veya sonuçları döndürme:

    • onCustomAction içinde, işlemi işlem kimliğine ve ihtiyaç duyduğunuz diğer verilere göre gerçekleştirin. EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID anahtarını kullanarak ekstralardan işlemi tetikleyen MediaItem öğesinin kimliğini alabilirsiniz.

    • İlerleme veya sonuç paketine anahtarı EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM ekleyerek MediaItem için işlem listesini güncelleyebilirsiniz.

İşlem durumunu güncelleme

Bu yöntemleri MediaBrowserServiceCompat'da geçersiz kılmak için:

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

ve

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

Ayrıştırma işlemleri sınırı

Kaç özel göz atma işleminin desteklendiğini kontrol edin:

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

Özel göz atma işlemi oluşturma

Her işlem ayrı bir Bundle içine yerleştirilmelidir.

  • İşlem kimliği:

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

  • İşlem etiketi:

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

  • İşlem simgesi URI'si:

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

Parcelable ArrayList'e özel göz atma işlemleri ekleme

Tüm özel göz atma işlemi Bundle nesnelerini bir ArrayList içine ekleyin:

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;
}

Göz atma köküne özel göz atma işlemi listesi ekleme

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'a işlem ekleme

MediaItem içindeki göz atma işlemi kimlikleri, onGetRoot üzerinde verilen genel göz atma işlemi listesinin bir alt kümesi olmalıdır. Genel listede yer almayan işlemler yoksayılır.

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);

Build onCustomAction sonucu

Sonucu oluşturmak için:

  1. Bundle extras kaynağından mediaId öğesini ayrıştır

    @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. Eşzamansız sonuçlar için sonucu ayırın result.detach.

  3. Sonuç paketini oluşturun:

    1. Kullanıcıya bir mesaj gösterin:

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

    2. Öğeyi güncelleme (bir öğedeki işlemleri güncellemek için kullanılır):

      mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, mediaId);

    3. Oynatma görünümünü açın:

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

    4. Göz atma düğümünü güncelleyin:

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

  4. Sonucu kontrol edin:

    • Hata: result.sendError(resultBundle) çağrısı
    • İlerleme durumu güncellemesi: result.sendProgressUpdate(resultBundle) görüşmesi
    • Son: result.sendResult(resultBundle) numaralı telefonu arayın.

İşlem durumunu güncelleme

result.sendProgressUpdate(resultBundle) yöntemini EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM anahtarıyla kullanarak MediaItem değerini işlemin yeni durumunu yansıtacak şekilde güncelleyebilirsiniz. Bu sayede, kullanıcılara işlemlerinin ilerleme durumu ve sonucu hakkında anlık geri bildirim sağlayabilirsiniz.

Örnek indirme işlemi

Bu örnekte, bu özelliği kullanarak üç durumlu bir indirme işlemi nasıl uygulayabileceğiniz açıklanmaktadır:

  • İndirme, işlemin ilk durumudur. Kullanıcı bu işlemi seçtiğinde, işlemi İndirme ile değiştirebilir ve kullanıcı arayüzünü (UI) güncellemek için sendProgressUpdate işlevini çağırabilirsiniz.

  • İndiriliyor durumu, indirme işleminin devam ettiğini gösterir. Bu durumu, kullanıcıya bir ilerleme çubuğu veya başka bir gösterge göstermek için kullanabilirsiniz.

  • İndirildi durumu, indirme işleminin tamamlandığını gösterir. İndirme işlemi tamamlandığında, İndiriliyor'u İndirildi ile değiştirebilir ve öğenin yenilenmesi gerektiğini belirtmek için sendResult işlevini EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM anahtarıyla çağırabilirsiniz. Ayrıca, kullanıcıya başarı mesajı göstermek için EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE tuşunu kullanabilirsiniz.

Bu yaklaşım, indirme süreci ve mevcut durumu hakkında kullanıcıya net geri bildirim vermenizi sağlar. %25, %50 ve% 75 indirme durumlarını göstermek için simgelerle daha fazla ayrıntı ekleyebilirsiniz.

Örnek favori işlem

Bir başka örnek de iki durumu olan bir favori işlemidir:

  • Kullanıcının favoriler listesinde olmayan öğeler için Favori gösterilir. Kullanıcı bu işlemi seçtiğinde, işlemi Favorited ile değiştirin ve sendResult işlevini EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM anahtarıyla çağırarak kullanıcı arayüzünü güncelleyin.

  • Kullanıcının favoriler listesindeki öğeler için Favorilere eklendi gösterilir. Kullanıcı bu işlemi seçtiğinde Favori ile değiştirin ve kullanıcı arayüzünü güncellemek için sendResult işlevini EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM anahtarıyla çağırın.

Bu yaklaşım, kullanıcıların favori öğelerini yönetmesi için net ve tutarlı bir yol sunar. Bu örnekler, özel göz atma işlemlerinin esnekliğini ve arabanın Medya uygulamasında gelişmiş bir kullanıcı deneyimi için anlık geri bildirimle çeşitli işlevleri uygulamak üzere bu işlemlerden nasıl yararlanabileceğinizi gösterir.

Bu özelliğin kapsamlı bir örnek uygulamasını TestMediaApp projesinde görebilirsiniz.

Önceki
Göz atılabilir arama sonuçlarını görüntüleyin