הסבר קצר

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

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

פלטפורמת ה-API

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

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

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

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

@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 שמגדירה את התוכן של הטיפ באמצעות ה-composable‏ 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 listener של האינטראקציות של המשתמשים ומעדכן את TooltipState בהתאם. כשהערך של TooltipState מציין שצריך להציג את ההסבר הקצר, פונקציית הלמבדה של ההסבר הקצר מופעלת, והפונקציה TooltipBox מציגה את RichTooltip. ה-TooltipBox משמש כעוגן וכמאגר לתוכן ולהסבר הקצר.
  • במקרה הזה, התוכן הוא רכיב IconButton, שמספק את התנהגות הפעולה שניתן ללחוץ עליה. כדי להציג את ההסבר הקצר עם מידע נוסף, לוחצים לחיצה ארוכה (במכשירי מגע) או מעבירים את העכבר (כמו עם סמן העכבר) מעל לכל מקום בתוכן של TooltipBox.
• הפונקציה הקומפוזבילית 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, הוא מוצג למשך כשנייה. כדי לסגור את ההסבר הקצר, אפשר ללחוץ במקום אחר במסך או על כפתור הפעולה לסגירה.
• כשהפעולה לסגירת ההתראה מתבצעת, המערכת מפעילה פונקציית coroutine כדי להפעיל את tooltipState.dismiss. כך אפשר לוודא שביצוע הפעולה לא נחסם בזמן שההסבר הקצר מוצג.
• ‫onClick = coroutineScope.launch { tooltipState.show() } } מפעיל פונקציית coroutine כדי להציג את ההסבר הקצר באופן ידני באמצעות tooltipState.show.
• הפרמטר action מאפשר להוסיף רכיבים אינטראקטיביים להסבר קצר, כמו כפתור.
• הפרמטר caretSize משנה את גודל החץ של ההסבר הקצר.

תוצאה

הדוגמה הזו מפיקה את התוצאה הבאה:

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

• ‫Material Design: הסברים קצרים