הסבר קצר

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

אפשר להשתמש בתיאורי העזר כדי להוסיף הקשר לכפתור או לרכיב אחר בממשק המשתמש. יש שני סוגים של כלי עזר:

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

ממשק API

אפשר להשתמש ברכיב ה-composable TooltipBox כדי להטמיע תיאורי כלים באפליקציה. אתם שולטים במראה של TooltipBox באמצעות הפרמטרים הראשיים הבאים:

• positionProvider: מיקום הסבר הקצר ביחס לתוכן של עוגן הקישור. בדרך כלל משתמשים בספק מיקום שמוגדר כברירת מחדל מ-TooltipDefaults, או מספקים ספק משלכם אם צריך לוגיקה מותאמת אישית למיקום.
• tooltip: הרכיב הניתן לקישור שמכיל את התוכן של ההסבר הקצר. בדרך כלל משתמשים ב-composables‏ PlainTooltip או RichTooltip.
  • משתמשים ב-PlainTooltip כדי לתאר אלמנטים או פעולות של לחצני סמלים.
  • אפשר להשתמש ב-RichTooltip כדי לספק פרטים נוספים, כמו תיאור הערך של מאפיין. תיאורי העזרה המפורטים יכולים לכלול כותרת, קישור ולחצנים אופציונליים.
• state: מאגר המצב שמכיל את הלוגיקה של ממשק המשתמש ואת מצב הרכיב של הסמל השימושי הזה.
• content: התוכן שאפשר ליצור ממנו רכיבים, שאליו מוצמדת ההודעה.

הצגת הסבר קצר פשוט

אפשר להשתמש בהסבר קצר כדי לתאר בקצרה רכיב בממשק המשתמש. קטע הקוד הזה מציג תיאור כללי פשוט מעל לחצן סמל עם הכיתוב 'הוספה למועדפים':

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

נקודות עיקריות לגבי הקוד

• TooltipBox יוצרת תיאור כללי פשוט עם הטקסט 'הוספה למועדפים'.
  • TooltipDefaults.rememberPlainTooltipPositionProvider() מגדיר את מיקום ברירת המחדל של כלי העזר הפשוטים.
  • tooltip היא פונקציית lambda שמגדירה את התוכן של תיבת העזר באמצעות ה-composable‏ PlainTooltip.
  • Text(plainTooltipText) מציג את הטקסט בתוך ההסבר הקצר.
  • tooltipState קובע את מצב הסמל של ההנחיה.
• IconButton יוצר לחצן שניתן ללחוץ עליו עם סמל.
  • Icon(...) מוצג סמל לב בתוך הלחצן.
  • כשמשתמש יוצר אינטראקציה עם IconButton, מוצגת תיאורת העזרה עם הטקסט 'הוספה למועדפים'. בהתאם למכשיר, המשתמשים יכולים להפעיל את הסמל של ההסבר בדרכים הבאות:
  • מעבירים את הסמן מעל הסמל
  • לחיצה ארוכה על הסמל במכשיר נייד

התוצאה

בדוגמה הזו מוצגת תיבת עזר פשוטה מעל סמל:

הצגת הסבר קצר עשיר

שימוש בהסבר קצר עשיר כדי לספק הקשר נוסף לגבי רכיב בממשק המשתמש. בדוגמה הזו נוצרת תווית עזר עשירה עם כמה שורות וכותרת שמקובעת ל-Icon:

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

נקודות עיקריות לגבי הקוד

• TooltipBox מטפל במאזני האירועים של האינטראקציות של המשתמשים ומעדכן את TooltipState בהתאם. כשהערך של TooltipState מציין שצריך להציג את ההסבר הקצר, הפונקציה הלוגריתםית של ההסבר הקצר מופעלת וההסבר הקצר RichTooltip מוצג. ה-TooltipBox משמש כציר וכקונטיינר גם לתוכן וגם להסבר הקצר.
  • במקרה הזה, התוכן הוא רכיב IconButton שמספק את התנהגות הפעולה שניתן להקיש עליה. אם לוחצים לחיצה ארוכה (במכשירי מגע) או מעבירים את העכבר מעל (כמו עם סמן העכבר) לכל מקום בתוכן של TooltipBox, יוצג הסבר קצר עם מידע נוסף.
• הרכיב הניתן לקישור RichTooltip מגדיר את התוכן של תיבת העזר, כולל השם וטקסט הגוף. TooltipDefaults.rememberRichTooltipPositionProvider() מספק מידע על המיקום של כלי העזר העשירים.

התוצאה

בדוגמה הזו נוצרת תיבת עזר עשירה עם כותרת שמצורפת לסמל מידע:

התאמה אישית של הסבר קצר עשיר

קטע הקוד הזה מציג תיאור עזר עשיר עם כותרת, פעולות בהתאמה אישית וסימן חץ בהתאמה אישית שמופיע מעל לחצן עם סמל מצלמה:

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

נקודות עיקריות לגבי הקוד

• הסמל RichToolTip מציג תיאור קצר עם כותרת ופעולה לסגירה.
• כשמפעילים את ההסבר הקצר, בלחיצה ארוכה או בהעברת סמן העכבר מעל התוכן של ToolTipBox, הוא מוצג למשך שנייה בערך. כדי לסגור את ההסבר, מקישים במקום אחר במסך או לוחצים על לחצן הפעולה לסגירה.
• כשמבצעים את פעולת הסגירה, מופעל קורוטין כדי לקרוא ל-tooltipState.dismiss. כך מוודאים שהפעלת הפעולה לא נחסמת בזמן שההסבר הקצר מוצג.
• onClick = coroutineScope.launch { tooltipState.show() } } מפעיל פונקציית קורוטין כדי להציג את ההסבר באופן ידני באמצעות tooltipState.show.
• הפרמטר action מאפשר להוסיף רכיבים אינטראקטיביים להסבר קצר, כמו לחצן.
• הפרמטר caretSize משנה את גודל החץ של הסמל של ההנחיה.

התוצאה

הדוגמה הזו מניבה את התוצאה הבאה:

מקורות מידע נוספים

• Material Design: תיאורים קצרים