הסבר קצר

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

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

תרשים 1. הסבר קצר רגיל (1) והסבר קצר מתקדם (2).

פלטפורמת ה-API

אפשר להשתמש ב-TooltipBox composable כדי להטמיע תיאורי כלים באפליקציה. אתם שולטים במראה של 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 היא פונקציית למבדה שמגדירה את התוכן של תיאור הכלים באמצעות הקומפוזבל 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 מטפל במאזיני האירועים של אינטראקציות המשתמשים ומעדכן את TooltipState בהתאם. כש-TooltipState מציין שיש להציג את תיאור הכלי, פונקציית ה-lambda של תיאור הכלי מופעלת ו-TooltipBox מציג את RichTooltip. רכיב TooltipBox משמש כעוגן וכמאגר גם לתוכן וגם לתיאור הכלי.
  • במקרה הזה, התוכן הוא רכיב IconButton, שמספק את התנהגות הפעולה שניתן להקיש עליה. כשלוחצים לחיצה ארוכה (במכשירי מגע) או כשמעבירים את סמן העכבר מעל (כמו עם מצביע העכבר) בכל מקום בתוכן של TooltipBox, תופיע בועת מידע עם פרטים נוספים.
• רכיב ה-RichTooltip composable מגדיר את התוכן של תיאור הכלים, כולל הכותרת והטקסט בגוף. רכיב ה-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)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

מידע חשוב על הקוד

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

תוצאה

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

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

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

• ‫Material Design: Tooltips