Przyciski ikon

Przyciski ikon wyświetlają działania, które użytkownicy mogą wykonać. Przyciski ikon muszą używać ikony o jasnym znaczeniu i zwykle reprezentują typowe lub często używane działania.

Istnieją 2 rodzaje przycisków ikon:

  • Domyślne: te przyciski mogą otwierać inne elementy, takie jak menu lub wyszukiwanie.
  • Przełącznik: te przyciski mogą reprezentować działania binarne, które można włączać i wyłączać, takie jak „ulubione” lub „zakładka”.
5 przycisków z różnymi ikonami, takimi jak ustawienia i inne. Niektóre są wypełnione, co oznacza, że są zaznaczone, a niektóre są obrysowane.
Rysunek 1. Przyciski ikon; niektóre są wypełnione (co oznacza wybór), a inne są obrysowane.

Interfejs API

Użyj funkcji kompozycyjnej IconButton, aby zaimplementować standardowe przyciski ikon, oraz IconToggleButton, aby utworzyć przycisk, który przełącza się między stanem zaznaczonym i niezaznaczonym. Aby utworzyć różne style wizualne, takie jak wypełniony, wypełniony tonalnie lub konturowy, użyj FilledIconButton, FilledTonalIconButton i OutlinedIconButton lub ich odpowiedników z przełącznikiem FilledIconToggleButton, FilledTonalIconToggleButton i OutlinedIconToggleButton.

Najważniejsze parametry IconButton to:

  • onClick: funkcja lambda, która jest wykonywana, gdy użytkownik kliknie przycisk ikony.
  • enabled: wartość logiczna, która określa stan włączenia przycisku. Gdy false, przycisk nie reaguje na dane wejściowe użytkownika.
  • content: zawartość kompozycyjna wewnątrz przycisku, zwykle Icon.

Najważniejsze parametry IconToggleButton to:

  • checked: wartość logiczna, która określa stan zaznaczenia przycisku.
  • onCheckedChange: funkcja lambda, która jest wykonywana, gdy użytkownik kliknie przycisk, i która podaje nowy stan zaznaczenia.
  • enabled: wartość logiczna, która określa stan włączenia przycisku. Gdy false, przycisk nie reaguje na dane wejściowe użytkownika.

Podstawowy przykład: przycisk ikony przełącznika

Przyciski ikon przełączania umożliwiają zaznaczenie lub odznaczenie pojedynczego wyboru, np. dodanie lub usunięcie czegoś z ulubionych. Do tego celu służy IconToggleButton i jego warianty.

Poniższy przykład pokazuje, jak zaimplementować przycisk ikony przełącznika, który zmienia wygląd w zależności od tego, czy jest zaznaczony, czy nie, przez zarządzanie stanem za pomocą IconButton:

@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."
        )
    }
}

Najważniejsze informacje o kodzie

  • Element kompozycyjny ToggleIconButtonExample definiuje przełączany element IconButton.
    • mutableStateOf(false) tworzy obiekt MutableState, który zawiera wartość logiczną, początkowo false. Dzięki temu isToggled jest zmienną stanu, co oznacza, że Compose ponownie komponuje interfejs, gdy zmienia się jej wartość.
    • rememberSaveable dba o to, aby stan isToggled był zachowywany podczas zmian konfiguracji, takich jak obrót ekranu.
  • Funkcja lambda onClick elementu IconButton określa zachowanie przycisku po kliknięciu, przełączając stan między true a false.
  • Parametr painter funkcji kompozycyjnej Icon warunkowo wczytuje inny element painterResource na podstawie stanu isToggled. Zmienia to wygląd ikony.
    • Jeśli isToggled to true, wczytuje wypełnione serce.
    • Jeśli isToggled to false, wczytuje element rysowalny z konturem serca.
  • contentDescription elementu Icon również aktualizuje się na podstawie stanu isToggled, aby dostarczać odpowiednie informacje o ułatwieniach dostępu.

Wynik

Poniższy obraz przedstawia przycisk przełącznika z poprzedniego fragmentu kodu w stanie wybranym:

Rysunek 2. Przycisk przełącznika „Ulubione” w stanie wybranym.

Przykład zaawansowany: powtarzane działania po naciśnięciu

W tej sekcji pokazujemy, jak tworzyć przyciski ikon, które stale wywołują działanie, gdy użytkownik je naciśnie i przytrzyma, a nie tylko raz po kliknięciu.

@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,
        )
    }
}

Najważniejsze informacje o kodzie

  • MomentaryIconButton przyjmuje unselectedImage: Int, czyli identyfikator zasobu obiektu rysowalnego dla ikony, gdy przycisk nie jest naciśnięty, oraz selectedImage: Int, czyli identyfikator zasobu obiektu rysowalnego dla ikony, gdy przycisk jest naciśnięty.
  • Używa interactionSource do śledzenia interakcji „naciśnięcia” przez użytkownika.
  • isPressed ma wartość true, gdy przycisk jest aktywnie naciskany, a w przeciwnym razie ma wartość false. Gdy isPressed ma wartość true, LaunchedEffect wchodzi w pętlę.
    • W tej pętli używa delay (z stepDelay) do tworzenia przerw między działaniami wyzwalającymi. coerceIn zapewnia, że opóźnienie wynosi co najmniej 1 ms, aby zapobiec nieskończonym pętlom.
    • Funkcja pressedListener jest wywoływana po każdym opóźnieniu w pętli. Spowoduje to powtórzenie działania.
  • pressedListener używa rememberUpdatedState, aby mieć pewność, że lambda onClick (działanie do wykonania) jest zawsze aktualna i pochodzi z najnowszej kompozycji.
  • Obraz wyświetlany przez Icon zmienia się w zależności od tego, czy przycisk jest aktualnie naciśnięty.
    • Jeśli isPressed ma wartość Prawda, wyświetla się selectedImage.
    • W przeciwnym razie wyświetli się unselectedImage.

Następnie użyj tego MomentaryIconButton w przykładzie. Ten fragment kodu pokazuje 2 przyciski ikon sterujące licznikiem:

@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 }
        )
    }
}

Najważniejsze informacje o kodzie

  • Funkcja kompozycyjna MomentaryIconButtonExample wyświetla element Row zawierający 2 instancje MomentaryIconButton i funkcję kompozycyjną Text, aby utworzyć interfejs do zwiększania i zmniejszania licznika.
  • Utrzymuje zmienną stanu zmiennego pressedCount za pomocą remember i mutableIntStateOf, zainicjowaną na 0. Gdy wartość pressedCount się zmienia, wszystkie elementy kompozycyjne, które ją obserwują (np. element kompozycyjny Text), są ponownie komponowane, aby odzwierciedlić nową wartość.
  • Pierwszy element MomentaryIconButton zmniejsza wartość pressedCount po kliknięciu lub przytrzymaniu.
  • Drugi przycisk MomentaryIconButton zwiększa pressedCount po kliknięciu lub przytrzymaniu.
  • Oba przyciski mają stepDelay o wartości 100 milisekund, co oznacza, że działanie onClick powtarza się co 100 ms, gdy przycisk jest przytrzymywany.

Wynik

Poniższy film przedstawia interfejs z przyciskami ikon i licznikiem:

Rysunek 3. Interfejs licznika z 2 przyciskami ikon (plus i minus), które zwiększają i zmniejszają wartość licznika.

Aktualizacja M3 Expressive

W aktualizacji M3 Expressive przyciski ikon obsługują dodatkowe opcje rozmiaru, narożników i szerokości oraz mogą zmieniać kształt po naciśnięciu lub wybraniu. Gdy przyciski z ikonami są umieszczone w standardowych grupach przycisków, po naciśnięciu wchodzą też w interakcję z sąsiednimi przyciskami.

Animowany kształt

Przyciski ikon mogą zmieniać kształt po naciśnięciu, a przyciski ikon przełączania mogą zmieniać kształt w zależności od stanu zaznaczenia. Aby włączyć animację kształtu, przekaż IconButtonDefaults.shapes() lub IconButtonDefaults.toggleableShapes() do parametru shapes funkcji IconButton lub IconToggleButton.

Przyciski ikon

Stany przycisku ikony
Rysunek 4. Animacja kształtu przycisku ikony w okrągłych i kwadratowych kształtach.

Poniższy fragment kodu pokazuje, jak wdrożyć przycisk z ikoną, który po naciśnięciu animuje swój kształt:

@Composable
fun IconButtonWithAnimatedShapeSample() {
    IconButton(
        onClick = { /* doSomething() */ },
        shapes = IconButtonDefaults.shapes(),
    ) {
        Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
    }
}

Przyciski przełączania ikon

Stany przycisku ikony przełączania
Rysunek 5. Animacja kształtu przycisku ikony przełącznika w stanie niewybranym i wybranym.

Poniższy fragment kodu pokazuje, jak wdrożyć przycisk ikony przełącznika, który animuje swój kształt na podstawie stanu zaznaczenia:

@Composable
fun IconToggleButtonWithAnimatedShapeSample() {
    var checked by remember { mutableStateOf(false) }
    IconToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        shapes = IconButtonDefaults.toggleableShapes(),
    ) {
        if (checked) {
            Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
        } else {
            Icon(painter = rememberVectorPainter(AppIcons.Lock), contentDescription = "Localized description")
        }
    }
}

Warianty rozmiaru, szerokości i kształtu

Przyciski ikon są dostępne w kształtach okrągłych i kwadratowych, w 5 rozmiarach i 3 szerokościach.

Przykłady rozmiarów, kształtów i szerokości przycisków ikon.
Rysunek 6. Funkcje ekspresyjne obejmują 5 rozmiarów, 2 kształty i 3 szerokości.

Więcej informacji o aktualizacjach Material 3 Expressive dotyczących przycisków ikon znajdziesz w wytycznych dotyczących przycisków ikon w Material Design 3.

Dostępnych jest 5 rozmiarów przycisków ikon: bardzo mały, mały, średni, duży i bardzo duży. Każdy rozmiar obsługuje 3 opcje szerokości: jednolitą (domyślną), wąską i szeroką.

5 wierszy i 3 kolumny przycisków z ikoną serca. Każdy wiersz jest większy od poprzedniego, a 3 kolumny mają różne szerokości: jednolitą, wąską i szeroką.
Rysunek 7. Przyciski ikon pokazujące 5 rozmiarów i 3 opcje szerokości: jednolitą, wąską i szeroką.

Przyciski ikon są dostępne w wariantach z zaokrąglonymi lub kwadratowymi rogami, a przyciski ikon przełączania zmieniają kształt po naciśnięciu lub wybraniu.

Dwa rzędy po 5 przycisków z ikoną serca, których rozmiar rośnie od lewej do prawej. Górny rząd ma zaokrąglone rogi, a dolny – kwadratowe.
Rysunek 8. Przyciski ikon są dostępne w wersjach z zaokrąglonymi lub kwadratowymi rogami.

Wskazówki dotyczące wyboru wariantów narożników znajdziesz w wytycznych dotyczących przycisków ikon w Material Design 3.

Dodatkowe materiały