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

משפרים את הפיתוח באמצעות 'כתיבה'

בעזרת 'Jetpack פיתוח נייטיב' ל-Android TV תוכלו ליצור ממשקי משתמש יפהפיים עם כמה שפחות קוד.

כתיבת הודעה לטלוויזיה ←

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

ספריית 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().

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

כדי לבצע פעולות מסוימות, יכול להיות שתצטרכו לספק למשתמש עוד אפשרויות. א' 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 לערך רכיב פעילות במניפסט של Android. הגדרת המאפיין הזה תחיל את העיצוב על כל הצאצאים צפיות וזו הדרך הישירה ביותר להחיל עיצוב מותאם אישית אם הפעילות של ההורה מכילה רק GuidedStepSupportFragment אובייקטים.
• אם בפעילות שלכם כבר נעשה שימוש בעיצוב מותאם אישית ואינכם רוצים להחיל אותה GuidedStepSupportFragment סגנונות לתצוגות אחרות בפעילות, הוספה של LeanbackGuidedStepTheme_guidedStepTheme לעיצוב של הפעילות המותאמת אישית הקיימת. המאפיין הזה מפנה לעיצוב המותאם אישית רק GuidedStepSupportFragment האובייקטים פעילות.
• אם משתמשים ב-GuidedStepSupportFragment אובייקטים ב- פעילויות שהן חלק מאותה משימה כוללת מרובת שלבים ומעוניינות להשתמש עיצוב חזותי בכל השלבים, שינוי מברירת המחדל GuidedStepSupportFragment.onProvideTheme() והחזרת העיצוב המותאם אישית.

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

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

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