Açıklamalı adım ekle

Uygulamanızda kullanıcılar için çok adımlı görevler bulunabilir. Örneğin, uygulamanızın ek içerik satın alma, karmaşık bir yapılandırma ayarı oluşturma veya yalnızca bir kararı onaylama konusunda kullanıcılara yol göstermesi gerekebilir. Tüm bu görevler, kullanıcılara bir veya daha fazla sıralı adımın uygulanması ya da karar verilmesi gerekir.

Leanback androidx kitaplığı, çok adımlı kullanıcı görevlerini uygulayacak sınıflar sunar. Bu sayfada, kullanıcıları bir görevi tamamlamaya yönelik bir dizi kararda yönlendirmek için GuidedStepSupportFragment sınıfının nasıl kullanılacağı açıklanmaktadır. GuidedStepSupportFragment, çok adımlı görevlerin TV cihazlarında anlaşılmasını ve gezinmesini kolaylaştırmak için TV kullanıcı arayüzü en iyi uygulamalarını kullanır.

Bir adımla ilgili ayrıntıları sağlama

GuidedStepSupportFragment, bir dizi adımdaki tek bir adımı temsil eder. Görsel olarak bu adımla ilgili olası eylemlerin veya kararların bir listesini içeren bir yol gösterici görünüm sağlar.

Şekil 1. Örnek açıklamalı adım.

Çok adımlı görevinizdeki her adım için GuidedStepSupportFragment kapsamını genişletin ve kullanıcının ilgili adım ve gerçekleştirebileceği işlemler hakkında bağlam bilgisi sağlayın. onCreateGuidance() değerini geçersiz kılın ve aşağıdaki örnekte gösterildiği gibi bağlam bilgilerini (ör. adım başlığı, açıklaması ve simgesi) içeren yeni bir GuidanceStylist.Guidance döndürün:

Kotlin

override fun onCreateGuidance(savedInstanceState: Bundle?): GuidanceStylist.Guidance {
    return GuidanceStylist.Guidance(
            getString(R.string.guidedstep_first_title),
            getString(R.string.guidedstep_first_description),
            getString(R.string.guidedstep_first_breadcrumb),
            activity.getDrawable(R.drawable.guidedstep_main_icon_1)
    )
}

Java

@Override
public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
    String title = getString(R.string.guidedstep_first_title);
    String breadcrumb = getString(R.string.guidedstep_first_breadcrumb);
    String description = getString(R.string.guidedstep_first_description);
    Drawable icon = getActivity().getDrawable(R.drawable.guidedstep_main_icon_1);
    return new GuidanceStylist.Guidance(title, description, breadcrumb, icon);
}

Etkinliğinizin onCreate() yönteminden GuidedStepSupportFragment.add() yöntemini çağırarak GuidedStepSupportFragment alt sınıfınızı istediğiniz etkinliğe ekleyin.

Etkinliğiniz yalnızca GuidedStepSupportFragment nesne içeriyorsa ilk GuidedStepSupportFragment öğesini eklemek için add() yerine GuidedStepSupportFragment.addAsRoot() öğesini kullanın. addAsRoot() kullanmak, kullanıcı ilk GuidedStepSupportFragment öğesini görüntülerken TV'nin uzaktan kumandasındaki Geri düğmesine basarsa hem GuidedStepSupportFragment hem de ebeveyn etkinliğinin kapanmasını sağlar.

Not: GuidedStepSupportFragment nesnelerini programatik olarak ekleyin, düzen XML dosyalarınıza eklemeyin.

Kullanıcı işlemleri oluşturma ve işleme

onCreateActions() değerini geçersiz kılarak kullanıcı işlemleri ekleyin. Geçersiz kılmanızda, her işlem öğesi için yeni bir GuidedAction ekleyip işlem dizesini, açıklamayı ve kimliği sağlayın. Yeni işlemler eklemek için GuidedAction.Builder öğesini kullanın.

Kotlin

override fun onCreateActions(actions: MutableList<GuidedAction>, savedInstanceState: Bundle?) {
    super.onCreateActions(actions, savedInstanceState)

    // Add "Continue" user action for this step
    actions.add(GuidedAction.Builder()
            .id(CONTINUE)
            .title(getString(R.string.guidedstep_continue))
            .description(getString(R.string.guidedstep_letsdoit))
            .hasNext(true)
            .build())
    ...

Java

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
    // Add "Continue" user action for this step
    actions.add(new GuidedAction.Builder()
           .id(CONTINUE)
           .title(getString(R.string.guidedstep_continue))
           .description(getString(R.string.guidedstep_letsdoit))
           .hasNext(true)
           .build());
...

İşlemler tek satırlı seçimlerle sınırlı değildir. İşte oluşturabileceğiniz başka eylem türleri:

• infoOnly(true) ayarlayarak kullanıcı seçenekleri hakkında ek bilgi sağlamak için bir bilgi etiketi işlemi ekleyin. infoOnly doğru olduğunda kullanıcılar işlemi seçemez.
• editable(true) ayarlayarak düzenlenebilir bir metin işlemi ekleyin. editable doğru olduğunda, kullanıcı uzaktan kumandayı veya bağlı bir klavyeyi kullanarak seçili bir işleme metin girebilir. Kullanıcının girdiği değiştirilmiş metni almak için onGuidedActionEditedAndProceed() değerini geçersiz kılın. Ayrıca, kullanıcının girişi ne zaman iptal ettiğini öğrenmek için onGuidedActionEditCanceled() değerini geçersiz kılabilirsiniz.
• İşlemleri bir grup halinde gruplandırmak için ortak bir kimlik değerine sahip checkSetId() kullanarak işaretlenebilir radyo düğmeleri gibi davranan bir işlem grubu ekleyin. Aynı kontrol grubu kimliğine sahip olan ve aynı listedeki tüm işlemler bağlı olarak kabul edilir. Kullanıcı bu gruptaki işlemlerden birini seçtiğinde, bu işlem işaretlenir ve diğer tüm işlemlerin işareti kaldırılır.
• onCreateActions() öğesinde GuidedAction.Builder yerine GuidedDatePickerAction.Builder kullanarak bir tarih seçici işlemi ekleyin. Kullanıcının girdiği değiştirilme tarihi değerini almak için onGuidedActionEditedAndProceed() değerini geçersiz kılın.
• Kullanıcının genişletilmiş bir seçenek listesinden seçim yapmasına izin vermek için alt işlemler kullanan bir işlem ekleyin. Alt işlemler Alt işlem ekleme bölümünde açıklanmaktadır.
• İşlemler listesinin sağ tarafında görünen ve kolayca erişilebilen bir düğme işlemi ekleyin. Düğme işlemleri, Düğme işlemleri ekle bölümünde açıklanmaktadır.

Ayrıca, hasNext(true) ayarlayarak bir işlem seçtiğinizde yeni bir adıma yol açtığını belirten bir görsel gösterge ekleyebilirsiniz.

Ayarlayabileceğiniz tüm farklı özellikler için GuidedAction politikasına bakın.

İşlemlere yanıt vermek için onGuidedActionClicked() değerini geçersiz kılın ve iletilen GuidedAction işlemini işleyin. GuidedAction.getId() öğesini inceleyerek seçili işlemi belirleyin.

Alt işlem ekleme

Bazı işlemler, kullanıcıya ek seçenekler vermenizi gerektirebilir. GuidedAction, alt işlemlerin menüsü olarak görüntülenen bir alt işlem listesi belirtebilir.

2. Şekil. Açıklamalı adım alt işlemleri.

Alt işlem listesi normal işlemleri veya radyo düğmesi işlemlerini içerebilir, ancak tarih seçici veya düzenlenebilir metin işlemlerini içeremez. Ayrıca, bir alt işlemin kendi alt işlem grubu olamaz. Bunun nedeni, sistemin birden fazla alt işlem düzeyini desteklemediği.

Alt işlem eklemek için önce aşağıdaki örnekte gösterildiği gibi, alt işlem olarak işlev gören GuidedAction nesnelerinin bir listesini oluşturup doldurun:

Kotlin

subActions.add(GuidedAction.Builder()
        .id(SUBACTION1)
        .title(getString(R.string.guidedstep_subaction1_title))
        .description(getString(R.string.guidedstep_subaction1_desc))
        .build())
...

Java

List<GuidedAction> subActions = new ArrayList<GuidedAction>();
subActions.add(new GuidedAction.Builder()
       .id(SUBACTION1)
       .title(getString(R.string.guidedstep_subaction1_title))
       .description(getString(R.string.guidedstep_subaction1_desc))
       .build());
...

onCreateActions() ürününde, seçildiğinde alt eylemlerin listesini görüntüleyen bir üst düzey GuidedAction oluşturun:

Kotlin

    ...
    actions.add(GuidedAction.Builder()
            .id(SUBACTIONS)
            .title(getString(R.string.guidedstep_subactions_title))
            .description(getString(R.string.guidedstep_subactions_desc))
            .subActions(subActions)
            .build())
    ...

Java

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
...
    actions.add(new GuidedAction.Builder()
           .id(SUBACTIONS)
           .title(getString(R.string.guidedstep_subactions_title))
           .description(getString(R.string.guidedstep_subactions_desc))
           .subActions(subActions)
           .build());
...
}

Son olarak, onSubGuidedActionClicked() değerini geçersiz kılarak alt işlem seçimlerini yanıtlayın:

Kotlin

override fun onSubGuidedActionClicked(action: GuidedAction): Boolean {
    // Check for which action was clicked and handle as needed
    when(action.id) {
        SUBACTION1 -> {
            // Subaction 1 selected
        }
    }
    // Return true to collapse the subactions menu or
    // false to keep the menu expanded
    return true
}

Java

@Override
public boolean onSubGuidedActionClicked(GuidedAction action) {
   // Check for which action was clicked and handle as needed
   if (action.getId() == SUBACTION1) {
       // Subaction 1 selected
   }
   // Return true to collapse the subactions menu or
   // false to keep the menu expanded
   return true;
}

Düğme işlemleri ekle

Rehberli adımınızda geniş bir işlem listesi varsa kullanıcıların en sık kullanılan işlemlere erişmek için listeyi kaydırması gerekebilir. Yaygın olarak kullanılan işlemleri işlem listesinden ayırmak için düğme işlemlerini kullanın. Düğme işlemleri işlem listesinin yanında görünür ve gezinmesi kolaydır.

3. Şekil. Açıklamalı adım düğmesi işlemleri.

Düğme işlemleri normal işlemler gibi oluşturulur ve işlenir, ancak düğme işlemleri onCreateActions() yerine onCreateButtonActions() içinde oluşturulur. onGuidedActionClicked() içindeki düğme işlemlerine yanıt verin.

Adımlar arasındaki gezinme işlemleri gibi basit işlemler için düğme işlemlerini kullanın. Tarih seçici işlemini veya diğer düzenlenebilir işlemleri düğme işlemleri olarak kullanmayın. Ayrıca, düğme işlemlerinin alt işlemleri olamaz.

Açıklamalı adımları rehberli bir adım halinde gruplandırın

GuidedStepSupportFragment, tek bir adımı temsil eder. Sıralı bir adım dizisi oluşturmak için dizideki bir sonraki adımı parça yığınına eklemek üzere GuidedStepSupportFragment.add() kullanarak birden fazla GuidedStepSupportFragment nesnesini birlikte gruplandırın.

Kotlin

override fun onGuidedActionClicked(action: GuidedAction) {
    val fm = fragmentManager
    when(action.id) {
        CONTINUE -> GuidedStepSupportFragment.add(fm, SecondStepFragment())
    }
}

Java

@Override
public void onGuidedActionClicked(GuidedAction action) {
    FragmentManager fm = getFragmentManager();
    if (action.getId() == CONTINUE) {
       GuidedStepSupportFragment.add(fm, new SecondStepFragment());
    }
...

Kullanıcı TV uzaktan kumandasındaki Geri düğmesine basarsa cihaz, parça yığınında önceki GuidedStepSupportFragment değerini gösterir. Önceki adıma geri dönen kendi GuidedAction sağlarsanız getFragmentManager().popBackStack() yöntemini çağırarak Geri davranışını uygulayabilirsiniz. Kullanıcıyı dizide daha önceki bir adıma döndürmeniz gerekiyorsa parça yığınındaki belirli bir GuidedStepSupportFragment öğesine dönmek için popBackStackToGuidedStepSupportFragment() öğesini kullanın.

Kullanıcı sıranın son adımını bitirdiğinde mevcut yığındaki tüm GuidedStepSupportFragment örneği kaldırmak ve orijinal üst etkinliğe dönmek için finishGuidedStepSupportFragments() tuşunu kullanın. İlk GuidedStepSupportFragment, addAsRoot() kullanılarak eklenirse finishGuidedStepSupportFragments() çağrısı da üst etkinliği kapatır.

Adım sunumunu özelleştirin

GuidedStepSupportFragment sınıfı, başlık metni biçimlendirmesi veya adım geçişi animasyonları gibi sunum özelliklerini kontrol eden özel temaları kullanabilir. Özel temalar Theme_Leanback_GuidedStep öğesini devralmalıdır ve GuidanceStylist ile GuidedActionsStylist içinde tanımlanan özellikler için geçersiz kılma değerleri sağlayabilir.

GuidedStepSupportFragment cihazınıza özel bir tema uygulamak için aşağıdakilerden birini yapın:

• Android manifest'indeki etkinlik öğesine android:theme özelliğini ayarlayarak temayı üst etkinliğe uygulayın. Bu özelliği ayarlamak, temayı tüm alt görünümlere uygular ve üst etkinlik yalnızca GuidedStepSupportFragment nesne içeriyorsa özel bir tema uygulamanın en basit yoludur.
• Etkinliğiniz zaten özel bir tema kullanıyorsa ve etkinlikteki diğer görünümlere GuidedStepSupportFragment stilleri uygulamak istemiyorsanız mevcut özel etkinlik temanıza LeanbackGuidedStepTheme_guidedStepTheme özelliğini ekleyin. Bu özellik, yalnızca etkinliğinizdeki GuidedStepSupportFragment nesnelerinin kullandığı özel temaya işaret eder.
• Genel olarak aynı çok adımlı görevin parçası olan farklı etkinliklerde GuidedStepSupportFragment nesneleri kullanıyorsanız ve tüm adımlarda tutarlı bir görsel tema kullanmak istiyorsanız GuidedStepSupportFragment.onProvideTheme() öğesini geçersiz kılın ve özel temanızı döndürün.

Stil ve tema ekleme hakkında daha fazla bilgi için bkz. Stiller ve Temalar.

GuidedStepSupportFragment sınıfı, tema özelliklerine erişmek ve uygulamak için özel stilist sınıflarını kullanır. GuidanceStylist sınıfı soldaki rehberlik görünümünün sunumunu kontrol etmek için tema bilgilerini kullanırken GuidedActionsStylist sınıfı doğru işlemler görünümünün sunumunu kontrol etmek için tema bilgilerini kullanır.

Adımlarınızın görsel stilini, tema özelleştirmenin sağladığı olanakların ötesinde özelleştirmek için GuidanceStylist veya GuidedActionsStylist alt sınıfını oluşturun ve GuidedStepSupportFragment.onCreateGuidanceStylist() ya da GuidedStepSupportFragment.onCreateActionsStylist() alt sınıfınızı döndürün. Bu alt sınıflarda neleri özelleştirebileceğinizle ilgili ayrıntılar için GuidanceStylist ve GuidedActionsStylist belgelerine göz atın.