הסבר קצר

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

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

פלטפורמת ה-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 היא פונקציית למבדה שמגדירה את התוכן של תיאור הכלים באמצעות הקומפוזבל 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, מוצג הסבר קצר עם מידע נוסף.
• רכיב ה-Composable‏ 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)
                        }
                    }
                },
            ) {
                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: Tooltips