הסבר קצר

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

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

פלטפורמת ה-API

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

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

תוצאה

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

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

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