הוספת שלב מודרך

פיתוח טוב יותר באמצעות Compose

אפשר ליצור ממשקי משתמש יפים עם מינימום קוד באמצעות Jetpack Compose ל-Android TV OS.

יצירת מוזיקה לטלוויזיה →

יכול להיות שהאפליקציה שלכם כוללת משימות רב-שלביות למשתמשים. לדוגמה, יכול להיות שהאפליקציה שלכם תצטרך להנחות את המשתמשים בתהליך של רכישת תוכן נוסף, הגדרת הגדרה מורכבת או אישור החלטה. בכל המשימות האלה צריך להנחות את המשתמשים בשלב אחד או יותר או לעזור להם לקבל החלטות.

הספרייה androidx.leanback שהוצאה משימוש מספקת מחלקות להטמעה של משימות משתמש מרובות שלבים. בדף הזה מוסבר איך להשתמש במחלקה GuidedStepSupportFragment כדי להנחות משתמש בסדרת החלטות להשלמת משימה באמצעות GuidedStepSupportFragment.

הוספת פרטים לשלב

הסמל GuidedStepSupportFragment מייצג שלב יחיד בסדרה של שלבים. מבחינה ויזואלית, הוא מספק תצוגת הדרכה עם רשימה של פעולות או החלטות אפשריות לשלב.

איור 1. דוגמה למדריך אינטראקטיבי.

לכל שלב במשימה מרובת השלבים, כדאי להרחיב את GuidedStepSupportFragment ולספק מידע על ההקשר של השלב ועל הפעולות שהמשתמש יכול לבצע. מחליף את onCreateGuidance() ומחזיר GuidanceStylist.Guidance חדש שמכיל פרטי הקשר, כמו שם השלב, התיאור והסמל, כפי שמוצג בדוגמה הבאה:

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

מוסיפים את מחלקת המשנה GuidedStepSupportFragment לפעילות הרצויה על ידי קריאה ל-GuidedStepSupportFragment.add() בשיטה onCreate() של הפעילות.

אם הפעילות מכילה רק אובייקטים GuidedStepSupportFragment, צריך להשתמש ב-GuidedStepSupportFragment.addAsRoot() במקום ב-add() כדי להוסיף את האובייקט הראשון GuidedStepSupportFragment. השימוש ב-addAsRoot() עוזר לוודא שאם המשתמש לוחץ על הכפתור "הקודם" בשלט טלוויזיה בזמן הצפייה ב-GuidedStepSupportFragment הראשון, גם GuidedStepSupportFragment וגם Activity האב ייסגרו.

הערה: צריך להוסיף אובייקטים מסוג GuidedStepSupportFragment באופן פרוגרמטי, ולא בקובצי ה-XML של הפריסה.

יצירה וטיפול בפעולות משתמש

כדי להוסיף פעולות משתמש, צריך לבטל את ההגדרה של onCreateActions(). בשינוי ברירת המחדל, מוסיפים GuidedAction חדש לכל פעולה לביצוע ומזינים את מחרוזת הפעולה, התיאור והמזהה. אפשר להשתמש ב-GuidedAction.Builder כדי להוסיף פעולות חדשות.

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

הפעולות לא מוגבלות לבחירות של שורה אחת. אלה סוגים נוספים של פעולות שאפשר ליצור:

• מוסיפים פעולה של תווית מידע כדי לספק מידע נוסף על הבחירות של המשתמשים על ידי הגדרת infoOnly(true). אם המדיניות infoOnly מוגדרת כ-True, המשתמשים לא יכולים לבחור את הפעולה.
• מוסיפים פעולה של טקסט שניתן לעריכה על ידי הגדרת הערך editable(true). כשהערך של editable הוא true, המשתמש יכול להזין טקסט בפעולה שנבחרה באמצעות השלט או מקלדת מחוברת. מחליפים את onGuidedActionEditedAndProceed() כדי לקבל את הטקסט ששונה שהמשתמש הזין. אפשר גם לבטל את onGuidedActionEditCanceled() כדי לדעת מתי המשתמש מבטל את הקלט.
• כדי להוסיף קבוצה של פעולות שמתנהגות כמו לחצני בחירה שאפשר לסמן, משתמשים בתג checkSetId() עם ערך מזהה משותף כדי לקבץ פעולות לקבוצה. כל הפעולות באותה רשימה עם אותו מזהה של קבוצת בדיקות נחשבות כמקושרות. כשהמשתמש בוחר אחת מהפעולות בקבוצה, הפעולה הזו מסומנת וכל שאר הפעולות מבוטלות.
• כדי להוסיף פעולה של בחירת תאריך, משתמשים ב-GuidedDatePickerAction.Builder במקום ב-GuidedAction.Builder ב-onCreateActions(). מחליפים את הערך onGuidedActionEditedAndProceed() כדי לקבל את ערך התאריך ששונה שהמשתמש הזין.
• להוסיף פעולה שמשתמשת בפעולות משנה כדי לאפשר למשתמש לבחור מתוך רשימה מורחבת של אפשרויות. תיאור של פעולות משנה מופיע בקטע הוספת פעולות משנה.
• מוסיפים כפתור פעולה שמופיע משמאל לרשימת הפעולות וקל לגשת אליו. פעולות באמצעות לחצנים מתוארות בקטע הוספת פעולות באמצעות לחצנים.

אפשר גם להוסיף אינדיקטור ויזואלי לכך שבחירת פעולה מובילה לשלב חדש, על ידי הגדרת hasNext(true).

לרשימה של כל המאפיינים שאפשר להגדיר, אפשר לעיין במאמר GuidedAction.

כדי להגיב לפעולות, מחליפים את onGuidedActionClicked() ומעבדים את GuidedAction. זיהוי הפעולה שנבחרה על ידי בדיקת GuidedAction.getId().

הוספת פעולות משנה

יכול להיות שחלק מהפעולות ידרשו מכם לתת למשתמש קבוצה נוספת של אפשרויות. ‫GuidedAction יכול לציין רשימה של פעולות משנה שמוצגות כתפריט של פעולות צאצא.

איור 2. פעולות משנה של מדריך אינטראקטיבי.

רשימת פעולות המשנה יכולה להכיל פעולות רגילות או פעולות של לחצני בחירה, אבל לא פעולות של בחירת תאריך או של טקסט שניתן לעריכה. בנוסף, לפעולת משנה לא יכול להיות סט משלה של פעולות משנה, כי המערכת לא תומכת ביותר מרמה אחת של פעולות משנה.

כדי להוסיף פעולות משנה, קודם צריך ליצור רשימה של אובייקטים של GuidedAction שפועלים כפעולות משנה, כמו בדוגמה הבאה:

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(), יוצרים GuidedAction ברמה העליונה שמציג את רשימת פעולות המשנה כשבוחרים אותו:

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

לבסוף, מגיבים לבחירות של פעולות משנה על ידי החלפת הערך של 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;
}

הוספת פעולות בכפתור

אם השלב המודרך כולל רשימה ארוכה של פעולות, יכול להיות שהמשתמשים יצטרכו לגלול ברשימה כדי לגשת לפעולות הנפוצות ביותר. אפשר להשתמש בפעולות של לחצנים כדי להפריד בין פעולות נפוצות לבין רשימת הפעולות. פעולות הכפתורים מופיעות לצד רשימת הפעולות, וקל לנווט אליהן.

איור 3. פעולות באמצעות לחצנים במדריך אינטראקטיבי.

פעולות של כפתורים נוצרות ומטופלות בדיוק כמו פעולות רגילות, אבל יוצרים פעולות של כפתורים ב-onCreateButtonActions() במקום ב-onCreateActions(). תגובה לפעולות של לחצנים בonGuidedActionClicked().

משתמשים בפעולות של לחצנים לפעולות פשוטות, כמו פעולות ניווט בין שלבים. אל תשתמשו בפעולה של בחירת תאריך או בפעולות אחרות שניתנות לעריכה כפעולות של לחצנים. בנוסף, לפעולות של לחצנים לא יכולות להיות פעולות משנה.

קיבוץ של מדריכים אינטראקטיביים לרצף מודרך

‫GuidedStepSupportFragment מייצג שלב אחד. כדי ליצור רצף מסודר של שלבים, מקבצים כמה אובייקטים של GuidedStepSupportFragment באמצעות GuidedStepSupportFragment.add() כדי להוסיף את השלב הבא ברצף למחסנית של הקטע.

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

אם המשתמש לוחץ על הכפתור "הקודם" בשלט טלוויזיה, המכשיר מציג את GuidedStepSupportFragment הקודם במצבור המקטעים. אם תספקו GuidedAction משלכם שחוזר לשלב הקודם, תוכלו להטמיע את התנהגות החזרה באמצעות קריאה ל-getFragmentManager().popBackStack(). אם אתם צריכים להחזיר את המשתמש לשלב מוקדם יותר ברצף, אתם יכולים להשתמש ב-popBackStackToGuidedStepSupportFragment() כדי לחזור ל-GuidedStepSupportFragment ספציפי במצבור המקטעים.

כשהמשתמש מסיים את השלב האחרון ברצף, צריך להשתמש ב-finishGuidedStepSupportFragments() כדי להסיר את כל המופעים של GuidedStepSupportFragment מהמחסנית הנוכחית ולחזור לפעילות האב המקורית. אם מוסיפים את GuidedStepSupportFragment הראשון באמצעות addAsRoot(), קריאה ל-finishGuidedStepSupportFragments() סוגרת גם את פעילות ההורה.

התאמה אישית של הצגת השלבים

בשיעור GuidedStepSupportFragment אפשר להשתמש בערכות נושא מותאמות אישית ששולטות בהיבטים של המצגת, כמו עיצוב הטקסט של הכותרת או אנימציות של מעברים בין שלבים. ערכות נושא מותאמות אישית צריכות להיות נגזרות מ-Theme_Leanback_GuidedStep, ויכולות לספק ערכים חלופיים למאפיינים שמוגדרים ב-GuidanceStylist וב-GuidedActionsStylist.

כדי להחיל עיצוב מותאם אישית על GuidedStepSupportFragment, מבצעים אחת מהפעולות הבאות:

• כדי להחיל את העיצוב על פעילות האב, צריך להגדיר את המאפיין android:theme לאלמנט activity במניפסט של Android. הגדרת המאפיין הזה מחילה את העיצוב על כל תצוגות הצאצא, והיא הדרך הכי פשוטה להחיל עיצוב בהתאמה אישית אם הפעילות ברמת ההורה מכילה רק אובייקטים מסוג GuidedStepSupportFragment.
• אם הפעילות כבר משתמשת בערכת נושא מותאמת אישית ואתם לא רוצים להחיל סגנונות של GuidedStepSupportFragment על תצוגות אחרות בפעילות, צריך להוסיף את המאפיין LeanbackGuidedStepTheme_guidedStepTheme לערכת הנושא המותאמת אישית הקיימת של הפעילות. המאפיין הזה מצביע על העיצוב המותאם אישית שרק אובייקטים מסוימים בפעילות משתמשים בו.GuidedStepSupportFragment
• אם אתם משתמשים באובייקטים של GuidedStepSupportFragment בפעילויות שונות שמהוות חלק ממשימה כללית רב-שלבית, ואתם רוצים להשתמש בערכת נושא ויזואלית עקבית בכל השלבים, אתם יכולים לבטל את ההגדרה של GuidedStepSupportFragment ולהחזיר את ערכת הנושא המותאמת אישית שלכם.GuidedStepSupportFragment.onProvideTheme()

מידע נוסף על הוספת סגנונות ועיצובים זמין במאמר סגנונות ועיצובים.

המחלקות GuidedStepSupportFragment משתמשות במחלקות סגנון מיוחדות כדי לגשת למאפייני ערכת הנושא ולהחיל אותם. המחלקות GuidanceStylist משתמשות בפרטי העיצוב כדי לשלוט בתצוגה של תצוגת ההדרכה בצד ימין, והמחלקות GuidedActionsStylist משתמשות בפרטי העיצוב כדי לשלוט בתצוגה של תצוגת הפעולות בצד שמאל.

כדי להתאים אישית את הסגנון החזותי של השלבים מעבר למה שניתן בהתאמה אישית של העיצוב, צריך ליצור מחלקת משנה של GuidanceStylist או של GuidedActionsStylist ולהחזיר את מחלקת המשנה ב-GuidedStepSupportFragment.onCreateGuidanceStylist() או ב-GuidedStepSupportFragment.onCreateActionsStylist(). פרטים על מה שאפשר להתאים אישית במחלקות המשנה האלה מופיעים במאמרי העזרה בנושא GuidanceStylist ו-GuidedActionsStylist.