לחצני סמלים

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

יש שני סוגים של לחצני סמלים:

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

ממשק API

כדי להטמיע לחצני סמלים רגילים, משתמשים ברכיב ה-Composable‏ IconButton. כדי ליצור סגנונות חזותיים שונים, כמו מלא, מלא עם גוון או עם קו מתאר, משתמשים ב-FilledIconButton, ב-FilledTonalIconButton וב-OutlinedIconButton, בהתאמה.

הפרמטרים העיקריים של IconButton כוללים:

• onClick: פונקציית lambda שפועלת כשהמשתמש מקייש על לחצן הסמל.
• enabled: ערך בוליאני שקובע את מצב ההפעלה של הלחצן. כשהערך הוא false, הלחצן לא מגיב לקלט של המשתמש.
• content: התוכן שאפשר ליצור בתוך הלחצן, בדרך כלל Icon.

דוגמה בסיסית: כפתור של סמל החלפת מצב

בדוגמה הזו מוסבר איך מטמיעים לחצן של סמל החלפת מצב. המראה של לחצן עם סמל החלפת מצב משתנה בהתאם לכך שהוא נבחר או לא נבחר.

@Preview
@Composable
fun ToggleIconButtonExample() {
    // isToggled initial value should be read from a view model or persistent storage.
    var isToggled by rememberSaveable { mutableStateOf(false) }

    IconButton(
        onClick = { isToggled = !isToggled }
    ) {
        Icon(
            painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite),
            contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button."
        )
    }
}
IconButton.kt

נקודות עיקריות לגבי הקוד

• הרכיב הקומפוזיציבי ToggleIconButtonExample מגדיר IconButton שניתן להפעיל או להשבית.
  • mutableStateOf(false) יוצר אובייקט MutableState שמכיל ערך בוליאני, בהתחלה false. כך, isToggled הוא מאגר המצב, כלומר Compose יוצר מחדש את ממשק המשתמש בכל פעם שהערך שלו משתנה.
  • rememberSaveable מוודא שהמצב isToggled נשמר גם אחרי שינויים בהגדרות, כמו סיבוב המסך.
• פונקציית הלמה onClick של IconButton מגדירה את התנהגות הלחצן כשלוחצים עליו, ומעבירה את המצב בין true ל-false.
• הפרמטר painter של ה-composable Icon טוען painterResource שונה באופן מותנה על סמך המצב של isToggled. כך אפשר לשנות את המראה החזותי של הסמל.
  • אם הערך של isToggled הוא true, המערכת תטען את הלב המלא שאפשר לצייר.
  • אם הערך של isToggled הוא false, המערכת תטען את הלב עם קו המתאר.
• גם השדה contentDescription של ה-Icon מתעדכן על סמך המצב של isToggled כדי לספק מידע נגישות מתאים.

התוצאה

בתמונה הבאה מוצג לחצן סמל המתג מהקטע הקודם במצב שבו הוא לא מסומן:

דוגמה מתקדמת: פעולות חוזרות על לחיצה

בקטע הזה מוסבר איך ליצור לחצני סמלים שמפעילים פעולה באופן רציף בזמן שהמשתמש לוחץ עליהם ומחזיק אותם, במקום להפעיל פעולה רק פעם אחת לכל קליק.

@Composable
fun MomentaryIconButton(
    unselectedImage: Int,
    selectedImage: Int,
    contentDescription: String,
    modifier: Modifier = Modifier,
    stepDelay: Long = 100L, // Minimum value is 1L milliseconds.
    onClick: () -> Unit
) {
    val interactionSource = remember { MutableInteractionSource() }
    val isPressed by interactionSource.collectIsPressedAsState()
    val pressedListener by rememberUpdatedState(onClick)

    LaunchedEffect(isPressed) {
        while (isPressed) {
            delay(stepDelay.coerceIn(1L, Long.MAX_VALUE))
            pressedListener()
        }
    }

    IconButton(
        modifier = modifier,
        onClick = onClick,
        interactionSource = interactionSource
    ) {
        Icon(
            painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage),
            contentDescription = contentDescription,
        )
    }
}
IconButton.kt

נקודות עיקריות לגבי הקוד

• MomentaryIconButton מקבלת את הערך unselectedImage: Int, מזהה המשאב הניתן לציור של הסמל כשהלחצן לא לוחצים עליו, ואת הערך selectedImage: Int, מזהה המשאב הניתן לציור של הסמל כשהלחצן לוחצים עליו.
• הוא משתמש ב-interactionSource כדי לעקוב באופן ספציפי אחרי אינטראקציות של 'לחיצה' מהמשתמש.
• הערך של isPressed הוא true כשהלחצן לוחצים עליו באופן פעיל, ו-false במקרים אחרים. כשהערך של isPressed הוא true, ה-LaunchedEffect נכנס ללולאה.
  • בתוך הלולאה הזו, המערכת משתמשת ב-delay (עם stepDelay) כדי ליצור הפסקות בין פעולות ההפעלה. coerceIn מוודא שהעיכוב הוא לפחות 1ms כדי למנוע לולאות אינסופיות.
  • הפונקציה pressedListener מופעלת אחרי כל עיכוב בתוך הלולאה. הפעולה תתבצע שוב.
• הפונקציה pressedListener משתמשת ב-rememberUpdatedState כדי לוודא שהפונקציה onClick (הפעולה לביצוע) תמיד תהיה העדכנית ביותר מההרכב האחרון.
• התמונה שמוצגת ב-Icon משתנה בהתאם למצב של הכפתור.
  • אם הערך של isPressed הוא True, הערך של selectedImage מוצג.
  • אחרת, יוצג unselectedImage.

בשלב הבא, נשתמש ב-MomentaryIconButton בדוגמה. קטע הקוד הבא מדגים שני לחצני סמלים ששולטים בספירה:

@Preview()
@Composable
fun MomentaryIconButtonExample() {
    var pressedCount by remember { mutableIntStateOf(0) }

    Row(
        modifier = Modifier.fillMaxWidth(),
        verticalAlignment = Alignment.CenterVertically
    ) {
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_rewind,
            selectedImage = R.drawable.fast_rewind_filled,
            stepDelay = 100L,
            onClick = { pressedCount -= 1 },
            contentDescription = "Decrease count button"
        )
        Spacer(modifier = Modifier)
        Text("advanced by $pressedCount frames")
        Spacer(modifier = Modifier)
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_forward,
            selectedImage = R.drawable.fast_forward_filled,
            contentDescription = "Increase count button",
            stepDelay = 100L,
            onClick = { pressedCount += 1 }
        )
    }
}
IconButton.kt

נקודות עיקריות לגבי הקוד

• ה-composable של MomentaryIconButtonExample מציג Row שמכיל שתי מכונות MomentaryIconButton ו-composable של Text כדי ליצור ממשק משתמש להגדלה ולצמצום של מונה.
• הוא שומר על משתנה מצב שאפשר לשנות (mutable) בשם pressedCount באמצעות remember ו-mutableIntStateOf, שמאופסים בזמן האימפריסאליזציה. כשהערך של pressedCount משתנה, כל הרכיבים הניתנים לקיבוץ שמתבצעת עליהם תצפית (כמו הרכיב הניתן לקיבוץ Text) עוברים יצירת מחדש כדי לשקף את הערך החדש.
• ה-MomentaryIconButton הראשון מקטין את pressedCount כשלוחצים עליו או לוחצים לחיצה ארוכה עליו.
• הערך השני של MomentaryIconButton מגדיל את הערך של pressedCount כשמקישים עליו או לוחצים לחיצה ארוכה.
• בשני הלחצנים stepDelay מוגדר ל-100 אלפיות השנייה, כלומר הפעולה onClick חוזרת על עצמה כל 100 אלפיות השנייה בזמן הלחיצה על הלחצן.

התוצאה

בסרטון הבא מוצג ממשק המשתמש עם לחצני הסמלים והמספר:

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

• Material 3 – לחצנים עם סמלים