Menambahkan langkah yang dipandu

Membangun aplikasi dengan lebih baik menggunakan Compose

Membuat UI yang menarik dengan kode minimal menggunakan Jetpack Compose untuk Android TV OS.

Compose untuk TV →

Aplikasi Anda mungkin memiliki tugas multi-langkah untuk pengguna. Misalnya, aplikasi Anda mungkin perlu memandu pengguna dengan membeli konten tambahan, menyiapkan pengaturan konfigurasi yang kompleks, atau sekadar mengkonfirmasi sebuah keputusan. Semua tugas ini mengharuskan pengguna memandu pengguna melalui satu atau beberapa langkah atau keputusan.

Library androidx.Lean menyediakan class untuk mengimplementasikan tugas pengguna multi-langkah. Halaman ini membahas cara menggunakan Class GuidedStepSupportFragment untuk memandu pengguna melalui serangkaian keputusan dalam menyelesaikan tugas. GuidedStepSupportFragment menggunakan praktik terbaik UI TV untuk membuat tugas multi-langkah mudah dipahami dan dilakukan di perangkat TV.

Memberikan detail untuk sebuah langkah

GuidedStepSupportFragment mewakili satu langkah dalam deret langkah. Secara visual, model ini memberikan tampilan panduan dengan daftar tindakan atau keputusan yang mungkin untuk langkah tersebut.

Gambar 1. Contoh langkah terpandu.

Untuk setiap langkah dalam tugas multi-langkah, perluas GuidedStepSupportFragment dan berikan informasi konteks tentang langkah dan tindakan yang dapat dilakukan pengguna. Ganti onCreateGuidance() dan mengembalikan GuidanceStylist.Guidance yang berisi konteks informasi tambahan, seperti judul, deskripsi, dan ikon langkah, seperti yang ditunjukkan pada contoh berikut:

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

Tambahkan subclass GuidedStepSupportFragment ke yang Anda inginkan aktivitas dengan memanggil GuidedStepSupportFragment.add() dalam metode onCreate() aktivitas Anda.

Jika aktivitas Anda hanya berisi GuidedStepSupportFragment objek, gunakan GuidedStepSupportFragment.addAsRoot() bukan add(), untuk menambahkan GuidedStepSupportFragment pertama. Menggunakan addAsRoot() membantu memastikan bahwa jika pengguna menekan tombol Kembali pada remote TV saat melihat GuidedStepSupportFragment pertama, baik GuidedStepSupportFragment dan aktivitas induk ditutup.

Catatan: Tambahkan objek GuidedStepSupportFragment secara terprogram, bukan dalam file XML tata letak Anda.

Membuat dan menangani tindakan pengguna

Tambahkan tindakan pengguna dengan mengganti onCreateActions(). Dalam penggantian, tambahkan GuidedAction baru untuk masing-masing item tindakan dan berikan string tindakan, deskripsi, dan ID. Gunakan GuidedAction.Builder untuk menambahkan tindakan baru.

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

Tindakan tidak terbatas pada pilihan baris tunggal. Berikut adalah jenis tindakan yang dapat Anda buat:

• Tambahkan tindakan label informasi untuk memberikan informasi tambahan tentang pilihan pengguna dengan menetapkan infoOnly(true). Jika infoOnly bernilai benar (true), pengguna tidak dapat memilih tindakan.
• Menambahkan tindakan teks yang dapat diedit dengan setelan editable(true). Jika editable bernilai benar (true), pengguna dapat memasukkan teks dalam tindakan yang dipilih menggunakan jarak jauh atau {i>keyboard<i} yang terhubung. Ganti onGuidedActionEditedAndProceed() untuk mendapatkan teks yang diubah yang dimasukkan pengguna. Anda juga dapat mengganti onGuidedActionEditCanceled() untuk mengetahui kapan pengguna membatalkan input.
• Menambahkan serangkaian tindakan yang berperilaku seperti tombol pilihan yang dapat dicentang menggunakan checkSetId() dengan nilai ID umum untuk mengelompokkan tindakan ke dalam sebuah set. Semua tindakan dalam daftar yang sama dengan ID check-set dianggap tertaut. Saat pengguna memilih salah satu tindakan dalam set tersebut, tindakan menjadi dicentang dan semua tindakan lainnya menjadi tidak dicentang.
• Tambahkan tindakan pemilih tanggal menggunakan GuidedDatePickerAction.Builder bukannya GuidedAction.Builder dalam onCreateActions(). Ganti onGuidedActionEditedAndProceed() untuk mendapatkan nilai tanggal yang diubah yang dimasukkan pengguna.
• Tambahkan tindakan yang menggunakan subtindakan agar pengguna dapat memilih dari daftar pilihan. Subtindakan dijelaskan di bagian Menambahkan subtindakan.
• Menambahkan tindakan tombol yang muncul di sebelah kanan daftar tindakan dan mudah dapat diakses. Tindakan tombol dijelaskan dalam tombol Tambahkan tindakan.

Anda juga dapat menambahkan indikator visual yang memilih tindakan mengarah ke langkah baru dengan menetapkan hasNext(true).

Untuk berbagai atribut yang dapat Anda tetapkan, lihat GuidedAction.

Untuk merespons tindakan, ganti onGuidedActionClicked() dan memproses pesan yang diteruskan GuidedAction. Identifikasi tindakan yang dipilih berdasarkan sedang memeriksa GuidedAction.getId().

Menambahkan subtindakan

Beberapa tindakan mungkin mengharuskan Anda memberi pengguna serangkaian pilihan tambahan. J GuidedAction dapat menentukan daftar yang ditampilkan sebagai menu tindakan turunan.

Gambar 2. Subtindakan langkah terpandu.

Daftar subtindakan dapat berisi tindakan reguler atau tindakan tombol pilihan, tetapi bukan pemilih tanggal atau tindakan teks yang dapat diedit. Selain itu, subtindakan tidak boleh memiliki sekumpulan subtindakan, karena sistem tidak mendukung lebih dari satu tingkat subtindakan.

Untuk menambahkan subtindakan, pertama-tama buat dan isi daftar Objek GuidedAction yang berfungsi sebagai subtindakan, seperti yang ditunjukkan dalam contoh berikut:

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

Di onCreateActions(), buat instance level teratas GuidedAction yang menampilkan daftar subtindakan saat dipilih:

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

Terakhir, tanggapi pilihan subtindakan dengan mengganti 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;
}

Menambahkan tindakan tombol

Jika langkah terpandu Anda memiliki banyak daftar tindakan, pengguna mungkin harus men-scroll daftar untuk mengakses tindakan yang paling umum digunakan. Menggunakan tindakan tombol untuk memisahkan tindakan yang umum digunakan dari daftar tindakan. Tindakan tombol muncul di samping daftar tindakan dan mudah untuk dinavigasi.

Gambar 3. Tindakan tombol langkah terpandu.

Tindakan tombol dibuat dan ditangani seperti halnya tindakan biasa, tetapi Anda membuatnya tindakan tombol di onCreateButtonActions() bukan onCreateActions(). Merespons tindakan tombol di onGuidedActionClicked().

Gunakan tindakan tombol untuk tindakan sederhana, seperti tindakan navigasi antar-langkah. Jangan gunakan tindakan pemilih tanggal atau tindakan yang dapat diedit lainnya sebagai tindakan tombol. Selain itu, tindakan tombol tidak dapat memiliki subtindakan.

Mengelompokkan langkah terpandu ke dalam urutan

GuidedStepSupportFragment mewakili satu langkah. Untuk membuat urutan langkah yang berurutan, kelompokkan beberapa GuidedStepSupportFragment objek bersama-sama menggunakan GuidedStepSupportFragment.add() untuk ditambahkan langkah berikutnya dalam urutan ke tumpukan fragmen.

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

Jika pengguna menekan tombol Back pada remote TV, perangkat akan menampilkan GuidedStepSupportFragment di tumpukan fragmen. Jika Anda menyediakan GuidedAction Anda sendiri yang kembali ke langkah sebelumnya, Anda dapat mengimplementasikan perilaku Kembali dengan memanggil getFragmentManager().popBackStack(). Jika Anda perlu mengembalikan pengguna ke langkah yang lebih awal lagi dalam urutan tersebut, gunakan popBackStackToGuidedStepSupportFragment() untuk kembali ke GuidedStepSupportFragment spesifik dalam tumpukan fragmen.

Saat pengguna menyelesaikan langkah terakhir dalam urutan, gunakan finishGuidedStepSupportFragments() untuk menghapus semua GuidedStepSupportFragment instance dari tumpukan saat ini dan kembali ke aktivitas induk asli. Jika GuidedStepSupportFragment pertama ditambahkan menggunakan addAsRoot(), memanggil finishGuidedStepSupportFragments() juga menutup aktivitas induk.

Menyesuaikan presentasi langkah

Class GuidedStepSupportFragment dapat menggunakan tema yang mengontrol aspek presentasi seperti pemformatan teks judul atau transisi langkah animasi. Tema kustom harus mewarisi dari Theme_Leanback_GuidedStep dan dapat memberikan mengganti nilai untuk atribut yang ditentukan dalam GuidanceStylist dan GuidedActionsStylist.

Untuk menerapkan tema kustom ke GuidedStepSupportFragment, lakukan salah satu hal berikut:

• Terapkan tema ke aktivitas induk dengan menyetel atribut android:theme ke elemen aktivitas dalam manifes Android. Menyetel atribut ini akan menerapkan tema ke semua turunan dan merupakan cara paling mudah untuk menerapkan tema khusus jika aktivitas induk hanya berisi Objek GuidedStepSupportFragment.
• Jika aktivitas Anda sudah menggunakan tema kustom dan Anda tidak ingin menerapkannya GuidedStepSupportFragment ke tampilan lain dalam aktivitas ini, tambahkan LeanbackGuidedStepTheme_guidedStepTheme ke tema aktivitas khusus yang ada. Atribut ini menunjuk ke tema kustom yang hanya objek GuidedStepSupportFragment di penggunaan aktivitas.
• Jika Anda menggunakan objek GuidedStepSupportFragment dengan aktivitas yang merupakan bagian dari tugas multi-langkah keseluruhan yang sama dan ingin menggunakan tema visual di semua langkah, timpa GuidedStepSupportFragment.onProvideTheme() dan tampilkan tema kustom Anda.

Untuk informasi selengkapnya tentang cara menambahkan gaya dan tema, lihat Gaya dan Tema.

Class GuidedStepSupportFragment menggunakan class stylist untuk mengakses dan menerapkan atribut tema. Class GuidanceStylist menggunakan informasi tema untuk mengontrol penyajian tampilan panduan sebelah kiri, sedangkan Class GuidedActionsStylist menggunakan informasi tema untuk mengontrol penyajian tampilan tindakan kanan.

Untuk menyesuaikan gaya visual langkah Anda di luar yang disediakan penyesuaian tema, buat subclass GuidanceStylist atau GuidedActionsStylist dan tampilkan subclass Anda di GuidedStepSupportFragment.onCreateGuidanceStylist() atau GuidedStepSupportFragment.onCreateActionsStylist(). Untuk detail tentang apa yang dapat Anda sesuaikan dalam subclass ini, lihat dokumentasi di GuidanceStylist dan GuidedActionsStylist.