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

כתיבה משופרת בעזרת תכונת הכתיבה

אפשר ליצור ממשקי משתמש יפים עם מינימום קוד באמצעות 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 וגם פעילות האב ייסגרו.

הערה: צריך להוסיף אובייקטים מסוג 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().

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

יכול להיות שחלק מהפעולות ידרשו מכם לתת למשתמשים עוד אפשרויות בחירה. ‫A 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 ספציפי במצבור של רכיבי ה-Fragment.

כשהמשתמש מסיים את השלב האחרון ברצף, משתמשים ב-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.