Menambahkan langkah terpandu

Aplikasi Anda mungkin memiliki tugas multi-langkah untuk pengguna. Misalnya, aplikasi Anda mungkin perlu memandu pengguna menyelesaikan pembelian konten tambahan, menyiapkan setelan konfigurasi yang rumit, atau sekadar mengonfirmasi keputusan. Untuk semua tugas ini, pengguna perlu dipandu dalam menyelesaikan satu atau beberapa keputusan atau langkah yang memiliki urutan tertentu.

Library leanback androidx menyediakan class untuk mengimplementasikan tugas pengguna multi-langkah. Pelajaran ini membahas cara menggunakan class GuidedStepFragment untuk memandu pengguna menyelesaikan serangkaian keputusan dalam menyelesaikan tugas. GuidedStepFragment menggunakan praktik terbaik UI TV untuk memudahkan Anda memahami dan menavigasi tugas multi-langkah di perangkat TV.

Memberikan detail untuk sebuah langkah

GuidedStepFragment mewakili satu langkah dalam serangkaian langkah. Secara visual, objek ini memberikan tampilan panduan di sebelah kiri yang disertai dengan informasi langkah. Di sebelah kanan, GuidedStepFragment menyediakan tampilan yang berisi daftar tindakan atau keputusan yang mungkin untuk langkah tersebut.

Gambar 1. Contoh langkah terpandu.

Untuk setiap langkah dalam tugas multi-langkah, sediakan GuidedStepFragment dan berikan informasi konteks tentang langkah itu serta tindakan yang dapat dilakukan pengguna. Ganti onCreateGuidance() dan tampilkan GuidanceStylist.Guidance baru yang berisi informasi konteks, seperti judul langkah, deskripsi, dan ikon.

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

Tambahkan subclass GuidedStepFragment ke aktivitas yang diinginkan dengan memanggil GuidedStepFragment.add() dalam metode onCreate() aktivitas Anda. Jika aktivitas Anda hanya memuat objek GuidedStepFragment, gunakan GuidedStepFragment.addAsRoot(), bukan add(), untuk menambahkan GuidedStepFragment pertama. Dengan addAsRoot(), pastikan bahwa jika pengguna menekan tombol Kembali pada remote TV sewaktu melihat GuidedStepFragment pertama, baik GuidedStepFragment maupun aktivitas induk akan menutup.

Catatan: Tambahkan objek GuidedStepFragment secara terprogram dan tidak dalam tata letak file XML Anda.

Membuat dan menangani tindakan pengguna

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

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

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

  • Tambahkan tindakan label informasi dengan menetapkan infoOnly(true). Jika Anda menetapkan infoOnly ke true, pengguna tidak dapat memilih tindakan tersebut. Untuk memberikan informasi tambahan tentang pilihan pengguna, gunakan tindakan label.
  • Tambahkan tindakan teks yang dapat diedit dengan menetapkan editable(true). Jika editable bernilai true, saat tindakan tersebut dipilih, pengguna dapat memasukkan teks menggunakan remote atau keyboard yang tersambung. Ganti onGuidedActionEdited() atau onGuidedActionEditedAndProceed() untuk mendapatkan teks yang sudah dimodifikasi yang dimasukkan pengguna.
  • Tambahkan satu set tindakan yang berperilaku sebagai 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 yang sama dianggap tertaut. Saat pengguna memilih salah satu tindakan dalam set tersebut, tindakan akan dicentang, sementara semua tindakan lainnya menjadi tidak dicentang.
  • Tambahkan tindakan pemilih tanggal menggunakan GuidedDatePickerAction.Builder, bukan GuidedAction.Builder, dalam onCreateActions(). Ganti onGuidedActionEdited() atau onGuidedActionEditedAndProceed() untuk mendapatkan nilai tanggal yang sudah dimodifikasi yang dimasukkan pengguna.
  • Tambahkan tindakan yang menggunakan subtindakan agar pengguna dapat memilih dari daftar pilihan yang diperluas. Subtindakan dijelaskan dalam Menambahkan subtindakan.
  • Tambahkan tindakan tombol yang muncul di sebelah kanan daftar tindakan dan yang mudah diakses. Tindakan tombol dijelaskan dalam Menambahkan tindakan tombol.

Anda juga dapat menambahkan indikator visual—untuk menunjukkan bahwa memilih tindakan itu akan membawa ke langkah baru—dengan menetapkan hasNext(true). Untuk semua atribut lain yang dapat Anda tetapkan, lihat GuidedAction.

Untuk merespons tindakan, ganti onGuidedActionClicked() dan proses GuidedAction yang diteruskan. Identifikasi tindakan yang dipilih dengan memeriksa GuidedAction.getId().

Menambahkan subtindakan

Beberapa tindakan mungkin mengharuskan Anda memberikan sekumpulan pilihan tambahan kepada pengguna. GuidedAction dapat menentukan daftar subtindakan yang ditampilkan sebagai menu drop-down dari tindakan turunan.

Gambar 2. Subtindakan langkah terpandu.

Daftar subtindakan dapat berisi tindakan reguler atau tindakan tombol pilihan, tetapi tidak dapat berisi tindakan pemilih tanggal atau teks yang dapat diedit. Selain itu, sebuah subtindakan tidak dapat memiliki sekumpulan subtindakan, karena sistem tidak mendukung lebih dari satu tingkat subtindakan. Rangkaian tindakan dengan banyak tingkatan akan menciptakan pengalaman pengguna yang buruk.

Untuk menambahkan subtindakan, pertama-tama buat dan isi daftar GuidedActions yang akan berfungsi sebagai subtindakan:

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

Dalam onCreateActions(), buat GuidedAction tingkat teratas yang akan menampilkan daftar subtindakan saat dipilih:

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

Terakhir, respons pilihan subtindakan dengan mengganti onSubGuidedActionClicked():

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 drop-down list, or
        // false to keep the drop-down list 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 drop-down list, or
       // false to keep the drop-down list expanded.
       return true;
    }
    

Menambahkan tindakan tombol

Jika langkah terpandu Anda memiliki daftar panjang tindakan, pengguna mungkin harus men-scroll daftar untuk mengakses tindakan yang paling umum digunakan. Gunakan tindakan tombol untuk memisahkan tindakan yang umum digunakan dari daftar tindakan. Tindakan tombol muncul di sebelah kanan daftar tindakan dan mudah diakses.

Gambar 3. Tindakan tombol langkah terpandu.

Tindakan tombol dibuat dan ditangani seperti halnya tindakan biasa, tetapi pembuatannya dilakukan di onCreateButtonActions(), bukan di onCreateActions(). Respons 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

GuidedStepFragment mewakili satu langkah, tetapi Anda mungkin memiliki beberapa langkah dalam sebuah urutan rangkaian. Kelompokkan beberapa objek GuidedStepFragment menggunakan GuidedStepFragment.add() untuk menambahkan langkah selanjutnya dalam urutan ke tumpukan fragmen.

Kotlin

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

Java

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

Jika pengguna menekan tombol Kembali pada remote TV, perangkat akan menampilkan GuidedStepFragment sebelumnya pada tumpukan fragmen. Jika ingin memberikan GuidedAction Anda sendiri yang mengembalikan pengguna ke langkah sebelumnya, Anda dapat menerapkan perilaku Kembali dengan memanggil getFragmentManager().popBackStack(). Jika ingin mengembalikan pengguna ke langkah yang lebih awal lagi dalam urutan ini, gunakan popBackStackToGuidedStepFragment() untuk kembali ke GuidedStepFragment tertentu dalam tumpukan fragmen.

Setelah pengguna menyelesaikan langkah terakhir dalam urutan, gunakan finishGuidedStepFragments() untuk menghapus semua GuidedStepFragments dari tumpukan saat ini dan kembali ke aktivitas induk awal. Jika GuidedStepFragment pertama ditambahkan menggunakan addAsRoot(), memanggil finishGuidedStepFragments() juga akan menutup aktivitas induk.

Menyesuaikan presentasi langkah

Class GuidedStepFragment dapat menggunakan tema kustom yang mengontrol berbagai aspek presentasi seperti pemformatan teks judul atau animasi transisi langkah. Tema kustom harus diwarisi dari Theme_Leanback_GuidedStep, dan dapat memberikan nilai pengganti untuk atribut yang ditentukan dalam GuidanceStylist dan GuidedActionsStylist.

Untuk menerapkan tema kustom ke GuidedStepFragment Anda, lakukan salah satu langkah berikut:

  • Terapkan tema ke aktivitas induk dengan menetapkan atribut android:theme ke elemen aktivitas dalam manifes Android. Menetapkan atribut ini akan menerapkan tema ke semua tampilan turunan dan merupakan cara termudah untuk menerapkan tema kustom jika aktivitas induknya hanya berisi objek GuidedStepFragment.
  • Jika aktivitas Anda sudah menggunakan tema kustom dan Anda tidak ingin menerapkan gaya GuidedStepFragment ke tampilan lain dalam aktivitas itu, tambahkan atribut LeanbackGuidedStepTheme_guidedStepTheme ke tema aktivitas kustom yang ada. Atribut ini mengarah ke tema kustom yang hanya digunakan oleh objek GuidedStepFragment dalam aktivitas Anda.
  • Jika Anda menggunakan objek GuidedStepFragment dalam aktivitas lain yang merupakan bagian dari keseluruhan tugas multi-langkah yang sama, dan ingin menggunakan tema visual yang konsisten di semua langkah, ganti GuidedStepFragment.onProvideTheme() dan tampilkan tema kustom Anda.

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

Class GuidedStepFragment menggunakan class stylist khusus untuk mengakses dan menerapkan atribut tema. Class GuidanceStylist menggunakan informasi tema untuk mengontrol presentasi tampilan panduan di sebelah kiri, sedangkan class GuidedActionsStylist menggunakan informasi tema untuk mengontrol presentasi tampilan tindakan di sebelah kanan.

Untuk menyesuaikan gaya visual langkah-langkah Anda di luar apa yang dapat disediakan melalui penyesuaian tema, tambahkan subclass GuidanceStylist atau GuidedActionsStylist, dan kembalikan subclass Anda dalam GuidedStepFragment.onCreateGuidanceStylist() atau GuidedStepFragment.onCreateActionsStylist(). Untuk penjelasan tentang apa yang dapat Anda sesuaikan dalam subclass ini, baca dokumentasi mengenai GuidanceStylist dan GuidedActionsStylist.