הסבר קצר

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

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

פלטפורמת ה-API

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

התוצאה

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

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

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

התוצאה

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

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

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

@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