Açıklamalı adım ekle

Compose ile daha iyi uygulamalar geliştirin

Android TV OS için Jetpack Compose'u kullanarak en az kodla güzel kullanıcı arayüzleri oluşturun.

TV için Compose →

Uygulamanızda kullanıcılar için çok adımlı görevler olabilir. Örneğin, uygulamanızın kullanıcıları ek içerik satın alma, karmaşık bir yapılandırma ayarını belirleme veya bir kararı onaylama konusunda yönlendirmesi gerekebilir. Bu görevlerin tümünde, kullanıcılara sıralı bir veya daha fazla adım ya da karar konusunda yol göstermek gerekir.

Desteği sonlandırılan androidx.leanback kitaplığı, çok adımlı kullanıcı görevlerini uygulamak için sınıflar sağlar. Bu sayfada, GuidedStepSupportFragment sınıfının, GuidedStepSupportFragment kullanılarak bir görevi tamamlamak için bir dizi karar verme sürecinde kullanıcıya nasıl rehberlik edeceği açıklanmaktadır.

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

GuidedStepSupportFragment, bir dizi adımdaki tek bir adımı temsil eder. Görsel olarak, adım için olası işlemlerin veya kararların listesini içeren bir rehberlik görünümü sunar.

Şekil 1. Açıklamalı adım örneği.

Çok adımlı görevinizdeki her adım için GuidedStepSupportFragment ifadesini genişletin ve adım ile kullanıcının gerçekleştirebileceği işlemler hakkında bağlam bilgileri verin. onCreateGuidance() öğesini geçersiz kılın onCreateGuidance() ve aşağıdaki örnekte gösterildiği gibi bağlam bilgilerini (ör. adım başlığı, açıklama ve simge) içeren yeni bir GuidanceStylist.Guidance döndürün:

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

@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 GuidedStepSupportFragment alt sınıfını, etkinliğinizin onCreate() yönteminde GuidedStepSupportFragment.add() çağırarak istediğiniz etkinliğe ekleyin.

Etkinliğiniz yalnızca GuidedStepSupportFragment nesneler içeriyorsa ilk GuidedStepSupportFragment öğesini eklemek için add() yerine GuidedStepSupportFragment.addAsRoot() kullanın. addAsRoot() kullanılması, kullanıcı GuidedStepSupportFragment öğesini görüntülerken TV uzaktan kumandasında Geri düğmesine bastığında hem GuidedStepSupportFragment öğesinin hem de üst etkinliğin kapanmasını sağlar.

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

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

onCreateActions() geçersiz kılarak kullanıcı işlemleri ekleyin. Geçersiz kılma işleminde, her işlem öğesi için yeni bir GuidedAction ekleyin ve işlem dizesini, açıklamasını ve kimliğini belirtin. Yeni işlemler eklemek için GuidedAction.Builder simgesini kullanın.

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())
    ...

@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ık seçimlerle sınırlı değildir. Oluşturabileceğiniz diğer işlem türleri şunlardır:

• infoOnly(true) ayarını yaparak kullanıcı tercihleri hakkında ek bilgiler sağlamak için bilgi etiketi işlemi ekleyin. infoOnly doğru olduğunda kullanıcılar işlemi seçemez.
• editable(true) ayarını yaparak düzenlenebilir 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. Kullanıcının girişi ne zaman iptal ettiğini öğrenmek için onGuidedActionEditCanceled() değerini de geçersiz kılabilirsiniz.
• İşlemleri bir grupta toplamak için ortak bir kimlik değeriyle birlikte checkSetId() kullanarak işaretlenebilir radyo düğmeleri gibi davranan bir dizi işlem ekleyin. Aynı listede bulunan ve aynı kontrol kümesi kimliğine sahip 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() içinde GuidedAction.Builder yerine GuidedDatePickerAction.Builder kullanarak tarih seçici işlemi ekleyin. Kullanıcının girdiği değiştirilmiş tarih 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 olanak tanımak için alt işlemler kullanan bir işlem ekleyin. Alt işlemler, Alt işlem ekleme bölümünde açıklanmıştır.
• İşlem listesinin sağında görünen ve kolayca erişilebilen bir düğme işlemi ekleyin. Düğme işlemleri Düğme işlemleri ekleme bölümünde açıklanmıştır.

hasNext(true) ayarını yaparak bir işlemin seçilmesinin yeni bir adıma yol açtığını gösteren görsel bir gösterge de ekleyebilirsiniz.

Ayarlayabileceğiniz tüm farklı özellikler için GuidedAction bölümüne bakın.

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

Alt işlemler ekleme

Bazı işlemler için kullanıcıya ek seçenekler sunmanız gerekebilir. Bir GuidedAction, alt işlemler menüsü olarak gösterilen bir alt işlem listesi belirtebilir.

Şekil 2. 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 ya da düzenlenebilir metin işlemlerini içermez. Ayrıca, sistem birden fazla alt işlem düzeyini desteklemediğinden bir alt işlem kendi alt işlem grubuna sahip olamaz.

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

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

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() içinde, seçildiğinde alt işlemlerin listesini gösteren bir üst düzey GuidedAction oluşturun:

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

@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, alt işlem seçimlerini geçersiz kılarak yanıtlayın onSubGuidedActionClicked():

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
}

@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 ekleme

Rehberli adımınızda uzun bir işlem listesi varsa kullanıcıların en çok tercih edilen işlemlere erişmek için listede kaydırma yapması gerekebilir. En çok tercih edilen 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 kolayca erişilebilir.

Şekil 3. 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şlemlerini onCreateActions() yerine onCreateButtonActions() içinde oluşturursunuz. onGuidedActionClicked() dilinde düğme işlemlerine yanıt verin.

Adımlar arasında gezinme 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şlemi olarak kullanmayın. Ayrıca, düğme işlemlerinin alt işlemleri olamaz.

Açıklamalı adımları açıklamalı bir sıraya gruplandırma

GuidedStepSupportFragment tek bir adımı temsil eder. Adımlardan oluşan sıralı bir dizi oluşturmak için birden fazla GuidedStepSupportFragment nesneyi GuidedStepSupportFragment.add() kullanarak gruplandırın. Böylece, dizideki bir sonraki adımı parça yığınına ekleyebilirsiniz.

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

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

Kullanıcı TV kumandasındaki Geri düğmesine basarsa cihaz, parça yığınındaki önceki parçayı GuidedStepSupportFragment gösterir. Önceki adıma dönen kendi GuidedAction öğenizi sağlarsanız getFragmentManager().popBackStack() öğesini çağırarak Geri davranışını uygulayabilirsiniz. Kullanıcıyı dizide daha da önceki bir adıma döndürmeniz gerekirse popBackStackToGuidedStepSupportFragment() kullanarak parça yığınındaki belirli bir GuidedStepSupportFragment'a dönün.

Kullanıcı dizideki son adımı tamamladığında, geçerli yığındaki tüm finishGuidedStepSupportFragments() örneklerini kaldırmak ve orijinal üst etkinliğe dönmek için GuidedStepSupportFragment kullanın. İlk GuidedStepSupportFragment, addAsRoot() kullanılarak eklenirse finishGuidedStepSupportFragments() çağrısı da üst etkinliği kapatır.

Adım sunumunu özelleştirme

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 öğesinden devralınmalıdır ve GuidanceStylist ile GuidedActionsStylist içinde tanımlanan özellikler için geçersiz kılma değerleri sağlayabilir.

GuidedStepSupportFragment için özel tema uygulamak istiyorsanız aşağıdakilerden birini yapın:

• Android manifest dosyasındaki etkinlik öğesinde 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 nesneleri içeriyorsa özel bir temayı uygulamanın en basit yoludur.
• Etkinliğinizde zaten özel bir tema kullanılıyorsa ve GuidedStepSupportFragment stillerini etkinliğin diğer görünümlerine uygulamak istemiyorsanız mevcut özel etkinlik temanıza LeanbackGuidedStepTheme_guidedStepTheme özelliğini ekleyin. Bu özellik, yalnızca etkinliğinizdeki GuidedStepSupportFragment nesnelerinin kullandığı özel temayı gösterir.
• Aynı çok adımlı görevin parçası olan farklı etkinliklerde GuidedStepSupportFragment nesnelerini 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 Stiller ve Temalar başlıklı makaleyi inceleyin.

GuidedStepSupportFragment sınıfı, tema özelliklerine erişmek ve bunları uygulamak için özel stilist sınıflar kullanır. GuidanceStylist sınıfı, sol rehber görünümünün sunumunu kontrol etmek için tema bilgilerini kullanır. GuidedActionsStylist sınıfı ise sağdaki 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ştirme özelliklerinin ötesinde özelleştirmek için GuidanceStylist veya GuidedActionsStylist alt sınıfını oluşturun ve alt sınıfınızı GuidedStepSupportFragment.onCreateGuidanceStylist() veya GuidedStepSupportFragment.onCreateActionsStylist() içinde döndürün. Bu alt sınıflarda özelleştirebileceğiniz öğeler hakkında ayrıntılı bilgi için GuidanceStylist ve GuidedActionsStylist ile ilgili dokümanları inceleyin.