הסבר קצר

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

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

איור 1. הסבר קצר רגיל (1) והסבר קצר עם עיצוב עשיר (2).

משטח API

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

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

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

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

@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 שמגדירה את התוכן של תיאור הכלים באמצעות רכיב ה-PlainTooltip שאפשר להוסיף לו רכיבים.
  • Text(plainTooltipText) הטקסט מוצג בתיבת הטיפ.
  • tooltipState קובעת את מצב הכלי לטיפים.
• ‫IconButton יוצר לחצן שאפשר ללחוץ עליו עם סמל.
  • Icon(...) מציג סמל של לב בתוך הלחצן.
  • כשמשתמש מקיים אינטראקציה עם IconButton, מוצג תיאור הכלי TooltipBox עם הטקסט 'הוספה למועדפים'. בהתאם למכשיר, המשתמשים יכולים להפעיל את תיאור הכלים בדרכים הבאות:
  • העברת העכבר מעל הסמל
  • לחיצה ארוכה על הסמל במכשיר נייד

התוצאה

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

איור 2. הסבר קצר פשוט שמופיע כשמשתמש מעביר את העכבר מעל סמל הלב או לוחץ עליו לחיצה ארוכה.

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

משתמשים בתיבת מידע עשירה כדי לספק הקשר נוסף לגבי רכיב בממשק המשתמש. בדוגמה הזו נוצר תיאור כלי מרובה שורות עם עיצוב עשיר וכותרת שמעוגנת ל-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 מטפל ב-event listeners של אינטראקציות עם המשתמשים ומעדכן את TooltipState בהתאם. כש-TooltipState מציין שצריך להציג את ההסבר הקצר, פונקציית הלמדה של ההסבר הקצר מופעלת, ו-TooltipBox מציג את RichTooltip. התג TooltipBox משמש כעוגן וכקונטיינר גם לתוכן וגם לתיבת הטיפים.
  • במקרה הזה, התוכן הוא רכיב IconButton, שמספק את התנהגות הפעולה שאפשר להקיש עליה. כשלוחצים לחיצה ארוכה (במכשירי מגע) או מעבירים את העכבר מעל (כמו עם מצביע העכבר) בכל מקום בתוכן של TooltipBox, מוצג הסבר קצר עם מידע נוסף.
• רכיב ה-Composable‏ RichTooltip מגדיר את התוכן של תיאור הכלי, כולל הכותרת וגוף הטקסט. ‫TooltipDefaults.rememberRichTooltipPositionProvider() מספק מידע על המיקום של תיאורי הכלים המתקדמים.

התוצאה

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

איור 3. הסבר קצר ועשיר עם כותרת וסמל מידע.

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

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

@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 משנה את גודל החץ של תיאור הכלים.

התוצאה

הדוגמה הזו יוצרת את הפלט הבא:

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

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

• ‫Material Design: Tooltips