הסבר קצר

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

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

ממשק 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, ב-TooltipBox מוצגת ההודעה 'הוספה למועדפים'. בהתאם למכשיר, המשתמשים יכולים להציג את ההסבר בדרכים הבאות:
  • העברת הסמן מעל הסמל
  • לחיצה ארוכה על הסמל במכשיר נייד

התוצאה

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

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

שימוש בהסבר קצר עשיר כדי לספק הקשר נוסף לגבי רכיב בממשק המשתמש. בדוגמה הזו נוצרת תווית עזר עשירה עם כמה שורות וכותרת שמקובעת ל-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 מציין שצריך להציג את ההסבר הקצר, הפונקציה הלוגרית של ההסבר הקצר מופעלת ו-TooltipBox מציג את 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: תיאורים קצרים