Thêm một bước có hướng dẫn

Tạo dựng ứng dụng hiệu quả hơn với Compose

Tạo giao diện người dùng đẹp mắt mà không cần nhiều mã nguồn bằng Jetpack Compose cho hệ điều hành Android TV.

Compose cho TV →

Ứng dụng của bạn có thể có các nhiệm vụ nhiều bước cho người dùng. Ví dụ: ứng dụng của bạn có thể cần hướng dẫn người dùng thông qua việc mua nội dung bổ sung, thiết lập một chế độ cài đặt cấu hình phức tạp, hoặc chỉ đơn giản là xác nhận quyết định. Tất cả các nhiệm vụ này yêu cầu người dùng phải đi bộ qua một hoặc nhiều nhiệm vụ được sắp xếp các bước hoặc quyết định.

Thư viện androidx.leanback cung cấp các lớp để triển khai các tác vụ nhiều bước của người dùng. Trang này thảo luận cách sử dụng GuidedStepSupportFragment lớp để hướng dẫn người dùng thực hiện một loạt quyết định để hoàn thành một nhiệm vụ. GuidedStepSupportFragment sử dụng các phương pháp hay nhất về giao diện người dùng trên TV để giúp bạn dễ dàng nắm bắt và thao tác đối với các tác vụ nhiều bước trên thiết bị TV.

Cung cấp thông tin chi tiết cho một bước

GuidedStepSupportFragment đại diện cho một bước duy nhất trong chuỗi bước. Về mặt trực quan, công cụ này cung cấp chế độ xem hướng dẫn kèm theo danh sách các hành động hoặc quyết định có thể xảy ra cho bước đó.

Hình 1. Một bước có hướng dẫn mẫu.

Đối với mỗi bước trong nhiệm vụ nhiều bước, hãy mở rộng GuidedStepSupportFragment và cung cấp thông tin bối cảnh về bước và hành động mà người dùng có thể thực hiện. Ghi đè onCreateGuidance() và trả lại một GuidanceStylist.Guidance có chứa ngữ cảnh thông tin (chẳng hạn như tiêu đề, nội dung mô tả và biểu tượng của bước) như trong ví dụ sau:

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

Thêm lớp con GuidedStepSupportFragment vào lớp con bạn muốn hoạt động bằng cách gọi GuidedStepSupportFragment.add() trong phương thức onCreate() của hoạt động.

Nếu hoạt động của bạn chỉ chứa GuidedStepSupportFragment đối tượng, hãy sử dụng GuidedStepSupportFragment.addAsRoot() thay vì add() để thêm GuidedStepSupportFragment đầu tiên. Sử dụng addAsRoot() giúp đảm bảo rằng nếu người dùng nhấn nút Quay lại trên điều khiển từ xa của TV khi xem GuidedStepSupportFragment đầu tiên, cả hai GuidedStepSupportFragment và hoạt động gốc đóng lại.

Lưu ý: Hãy thêm GuidedStepSupportFragment đối tượng theo phương thức lập trình, không có trong tệp XML bố cục của bạn.

Tạo và xử lý các thao tác của người dùng

Thêm hành động của người dùng bằng cách ghi đè onCreateActions(). Trong phần ghi đè, hãy thêm GuidedAction mới cho mỗi mục hành động và cung cấp chuỗi hành động, nội dung mô tả và mã hành động. Sử dụng GuidedAction.Builder để thêm thao tác mới.

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

Các thao tác không bị giới hạn ở việc chọn một dòng. Sau đây là các loại mà bạn có thể tạo:

• Thêm hành động đối với nhãn thông tin để cung cấp thêm thông tin về lựa chọn của người dùng bằng cách cài đặt infoOnly(true). Khi infoOnly là đúng, người dùng sẽ không thể chọn thao tác này.
• Cài đặt để thêm một thao tác có thể chỉnh sửa cho văn bản editable(true). Khi editable là đúng, người dùng có thể nhập văn bản vào thao tác đã chọn bằng điều khiển từ xa hoặc bàn phím đã kết nối. Ghi đè onGuidedActionEditedAndProceed() để lấy văn bản sửa đổi mà người dùng đã nhập. Bạn cũng có thể ghi đè onGuidedActionEditCanceled() để biết thời điểm người dùng huỷ dữ liệu nhập.
• Thêm một tập hợp các thao tác hoạt động như các nút chọn có thể đánh dấu bằng cách sử dụng checkSetId() có một giá trị mã nhận dạng chung để nhóm các hành động thành một tập hợp. Tất cả các hành động trong cùng một danh sách có cùng mã nhận dạng bộ kiểm tra đó được coi là đã liên kết. Khi người dùng chọn một trong các hành động trong tập hợp đó, hành động được đánh dấu và tất cả các hành động khác sẽ bị bỏ đánh dấu.
• Thêm một thao tác đối với bộ chọn ngày bằng cách sử dụng GuidedDatePickerAction.Builder thay vì GuidedAction.Builder trong onCreateActions(). Ghi đè onGuidedActionEditedAndProceed() để nhận giá trị ngày sửa đổi mà người dùng đã nhập.
• Thêm một thao tác sử dụng các hành động phụ để cho phép người dùng chọn từ một danh sách mở rộng lựa chọn. Thao tác phụ được mô tả trong phần Thêm tiểu mục.
• Thêm một nút hành động xuất hiện ở bên phải danh sách thao tác và dễ dàng thực hiện dễ sử dụng. Thao tác của nút được mô tả trong Nút thêm actions.

Bạn cũng có thể thêm chỉ báo trực quan cho biết việc chọn một hành động dẫn đến một bước mới bằng cách thiết lập hasNext(true).

Đối với tất cả các thuộc tính mà bạn có thể thiết lập, hãy xem GuidedAction.

Để phản hồi thao tác, hãy ghi đè onGuidedActionClicked() và xử lý thông tin nhập GuidedAction Xác định hành động đã chọn bằng kiểm tra GuidedAction.getId().

Thêm các hành động phụ

Một số thao tác có thể yêu cầu bạn cung cấp cho người dùng một nhóm lựa chọn bổ sung. Đáp GuidedAction có thể chỉ định danh sách các thao tác phụ hiển thị dưới dạng trình đơn gồm các thao tác con.

Hình 2. Các bước phụ theo bước có hướng dẫn.

Danh sách hành động phụ có thể chứa các hành động thông thường hoặc hành động bằng nút chọn, nhưng chứ không phải bộ chọn ngày hoặc hành động trên văn bản có thể chỉnh sửa. Ngoài ra, một hành động phụ không được có hành động phụ tập hợp các hành động phụ, bởi vì hệ thống không hỗ trợ nhiều hơn một cấp độ của các hành động phụ.

Để thêm các hành động phụ, trước tiên, hãy tạo và điền danh sách Các đối tượng GuidedAction đóng vai trò là hành động phụ, như trong ví dụ sau:

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

Trong onCreateActions(), hãy tạo cấp cao nhất GuidedAction hiển thị danh sách các nhóm phụ khi được chọn:

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

Cuối cùng, hãy phản hồi các lựa chọn hành động phụ bằng cách ghi đè 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;
}

Thêm các thao tác của nút

Nếu bước có hướng dẫn của bạn có nhiều hành động, thì người dùng có thể phải cuộn qua danh sách để truy cập vào các thao tác thường dùng nhất. Sử dụng các thao tác của nút để phân tách các hành động thường dùng trong danh sách hành động. Hành động của nút xuất hiện bên cạnh danh sách hành động và dễ dàng điều hướng đến.

Hình 3. Các thao tác trên nút bước có hướng dẫn.

Thao tác đối với nút được tạo và xử lý giống như các thao tác thông thường, nhưng bạn phải tạo hành động của nút trong onCreateButtonActions() thay vì onCreateActions(). Phản hồi các thao tác của nút trong onGuidedActionClicked().

Sử dụng thao tác trên nút cho các thao tác đơn giản, chẳng hạn như thao tác di chuyển giữa các bước. Không sử dụng hành động bộ chọn ngày hoặc các thao tác có thể chỉnh sửa khác làm thao tác trên nút. Ngoài ra, thao tác của nút không được có hành động phụ.

Nhóm các bước có hướng dẫn thành một trình tự có hướng dẫn

Một GuidedStepSupportFragment đại diện cho một bước duy nhất. Để tạo một trình tự các bước theo thứ tự, hãy nhóm nhiều bước GuidedStepSupportFragment đối tượng kết hợp với nhau bằng GuidedStepSupportFragment.add() để thêm bước tiếp theo trong trình tự vào ngăn xếp mảnh.

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

Nếu người dùng nhấn vào nút Quay lại trên điều khiển từ xa của TV, thiết bị sẽ hiển thị GuidedStepSupportFragment trên ngăn xếp mảnh. Nếu bạn cung cấp GuidedAction của riêng bạn quay lại bước trước, bạn có thể triển khai hành vi Quay lại bằng cách gọi getFragmentManager().popBackStack() Nếu bạn cần đưa người dùng quay lại một bước trước đó trong trình tự, hãy sử dụng popBackStackToGuidedStepSupportFragment() để quay lại một GuidedStepSupportFragment cụ thể trong ngăn xếp mảnh.

Khi người dùng hoàn thành bước cuối cùng trong trình tự, hãy sử dụng finishGuidedStepSupportFragments() để xoá tất cả GuidedStepSupportFragment thực thể khỏi ngăn xếp hiện tại và quay lại hoạt động gốc ban đầu. Nếu đã thêm GuidedStepSupportFragment đầu tiên sử dụng addAsRoot(), gọi finishGuidedStepSupportFragments() cũng đóng hoạt động gốc.

Tuỳ chỉnh cách trình bày theo bước

Lớp GuidedStepSupportFragment có thể sử dụng các tuỳ chỉnh giao diện kiểm soát các khía cạnh trong bản trình bày như định dạng văn bản tiêu đề hoặc chuyển đổi bước ảnh động. Giao diện tuỳ chỉnh phải kế thừa từ Theme_Leanback_GuidedStep và có thể cung cấp giá trị ghi đè cho các thuộc tính được xác định trong GuidanceStylist và GuidedActionsStylist.

Cách áp dụng giao diện tuỳ chỉnh cho GuidedStepSupportFragment: thực hiện một trong các thao tác sau:

• Áp dụng giao diện cho hoạt động gốc bằng cách đặt thuộc tính android:theme thành phần tử hoạt động trong tệp kê khai Android. Việc đặt thuộc tính này sẽ áp dụng giao diện cho tất cả thành phần con khung hiển thị và là cách đơn giản nhất để áp dụng một giao diện tuỳ chỉnh nếu hoạt động gốc chỉ chứa Đối tượng GuidedStepSupportFragment.
• Nếu hoạt động của bạn đã dùng một giao diện tuỳ chỉnh và bạn không muốn áp dụng GuidedStepSupportFragment kiểu sang các khung hiển thị khác trong hoạt động, thêm LeanbackGuidedStepTheme_guidedStepTheme vào giao diện tuỳ chỉnh hiện có cho hoạt động. Thuộc tính này trỏ đến giao diện tuỳ chỉnh chỉ các đối tượng GuidedStepSupportFragment trong dữ liệu hoạt động.
• Nếu bạn sử dụng các đối tượng GuidedStepSupportFragment trong nhiều là một phần của cùng một nhiệm vụ gồm nhiều bước tổng thể và muốn sử dụng một chủ đề hình ảnh trên tất cả các bước, ghi đè GuidedStepSupportFragment.onProvideTheme() rồi trả về giao diện tuỳ chỉnh của bạn.

Để biết thêm thông tin về cách thêm kiểu và giao diện, hãy xem Kiểu và giao diện.

Lớp GuidedStepSupportFragment sử dụng các đặc biệt các lớp tạo mẫu để truy cập và áp dụng các thuộc tính giao diện. Lớp GuidanceStylist sử dụng thông tin về giao diện để kiểm soát việc trình bày chế độ xem hướng dẫn bên trái, trong khi Lớp GuidedActionsStylist sử dụng thông tin về giao diện để kiểm soát việc trình bày khung hiển thị hành động phù hợp.

Để tuỳ chỉnh kiểu hình ảnh của các bước ngoài những tính năng tuỳ chỉnh giao diện cung cấp, hãy tạo lớp con GuidanceStylist hoặc GuidedActionsStylist rồi trả về lớp con trong GuidedStepSupportFragment.onCreateGuidanceStylist() hoặc GuidedStepSupportFragment.onCreateActionsStylist(). Để biết thông tin chi tiết về những nội dung bạn có thể tuỳ chỉnh trong các lớp con này, hãy xem tài liệu về GuidanceStylist và GuidedActionsStylist