Кнопки со значками

Кнопки со значками показывают действия, которые могут выполнить пользователи. Кнопки со значками должны использовать значок с понятным значением и обычно представляют собой общие или часто используемые действия.

Существует два типа кнопок со значками:

  • По умолчанию. Эти кнопки могут открывать другие элементы, например меню или поиск.
  • Переключатель. Эти кнопки могут представлять бинарные действия, которые можно включать или выключать, например "Избранное" или "Закладка".
Пять кнопок с разными значками, например "Настройки". Некоторые из них заполнены, что указывает на выбор, а некоторые выделены контуром.
Рисунок 1. Кнопки со значками. Некоторые из них заполнены (выбраны), а другие – нет.

API surface

Используйте composable-функцию IconButton, чтобы реализовать стандартные кнопки со значками, и IconToggleButton для кнопки, которая переключается между выбранным и невыбранным состояниями. Чтобы создать разные визуальные стили, например заполненный, заполненный тональный или контурный, используйте FilledIconButton, FilledTonalIconButton и OutlinedIconButton или их переключаемые аналоги FilledIconToggleButton, FilledTonalIconToggleButton и OutlinedIconToggleButton.

Основные параметры IconButton:

  • onClick – лямбда-функция, которая выполняется, когда пользователь нажимает кнопку со значком.
  • enabled – логическое значение, которое определяет, включена ли кнопка. Если false, кнопка не реагирует на действия пользователя.
  • content – компонуемый контент внутри кнопки, обычно Icon.

Основные параметры IconToggleButton:

  • checked: логическое значение, которое управляет выбранным состоянием кнопки.
  • onCheckedChange – лямбда-функция, которая выполняется, когда пользователь нажимает кнопку, и предоставляет новое состояние флажка.
  • enabled – логическое значение, которое определяет, включена ли кнопка. Если false, кнопка не реагирует на действия пользователя.

Простой пример: кнопка-переключатель со значком

Кнопки-переключатели позволяют выбрать или отменить выбор одного элемента, например добавить или удалить что-то из избранного. Для этого предназначена функция IconToggleButton и ее варианты.

В следующем примере показано, как реализовать кнопку-переключатель, которая меняет свой внешний вид в зависимости от того, выбрана она или нет, путем управления состоянием с помощью 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."
        )
    }
}

Основные сведения о коде

  • Composable-функция 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, чтобы предоставить соответствующую информацию о специальных возможностях.

Результат

На следующем изображении показана кнопка-переключатель из предыдущего фрагмента кода в выбранном состоянии:

Рисунок 2. Кнопка-переключатель "Избранное" в выбранном состоянии.

Пример для продвинутых пользователей: повторные действия при нажатии

В этом разделе показано, как создать кнопки со значками, которые непрерывно запускают действие, пока пользователь нажимает и удерживает их, а не просто запускают его один раз за клик.

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

Основные сведения о коде

  • MomentaryIconButton принимает unselectedImage: Int – идентификатор прорисовываемого ресурса для значка, когда кнопка не нажата, и selectedImage: Int – идентификатор прорисовываемого ресурса для значка, когда кнопка нажата.
  • Для отслеживания нажатий используется interactionSource.
  • isPressed – true, если кнопка нажата, и false в противном случае. Если isPressed – true, LaunchedEffect входит в цикл.
    • Внутри этого цикла используется delay (с stepDelay), чтобы создавать паузы между действиями. coerceIn гарантирует, что задержка составит не менее 1 мс, чтобы предотвратить бесконечные циклы.
    • Функция 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 }
        )
    }
}

Основные сведения о коде

  • Composable-функция MomentaryIconButtonExample отображает Row, содержащий два экземпляра MomentaryIconButton и composable-функцию Text, для создания пользовательского интерфейса, позволяющего увеличивать и уменьшать значение счетчика.
  • Он поддерживает изменяемую переменную состояния pressedCount с помощью remember и mutableIntStateOf, инициализированную значением 0. Когда pressedCount меняется, все composable-функции, которые его отслеживают (например, Text), перекомпонуются, чтобы отразить новое значение.
  • Первая кнопка MomentaryIconButton уменьшает значение pressedCount при нажатии или удержании.
  • Вторая кнопка MomentaryIconButton увеличивает pressedCount при нажатии или удержании.
  • Для обеих кнопок задано значение stepDelay, равное 100 миллисекундам. Это значит, что действие onClick повторяется каждые 100 миллисекунд, пока кнопка нажата.

Результат

На видео ниже показан интерфейс с кнопками-значками и счетчиком.

Рисунок 3. Интерфейс счетчика с двумя кнопками-значками (плюс и минус), которые увеличивают и уменьшают значение счетчика.

Обновление M3 Expressive

В обновлении M3 Expressive для кнопок со значками поддерживаются дополнительные параметры размера, угла и ширины, а также возможность изменения формы при нажатии или выборе. При размещении в стандартных группах кнопок кнопки со значками также взаимодействуют с соседними кнопками при нажатии.

Анимированная фигура

Форма кнопок со значками может меняться при нажатии, а форма кнопок-переключателей со значками – в зависимости от состояния. Чтобы включить анимацию фигур, передайте IconButtonDefaults.shapes() или IconButtonDefaults.toggleableShapes() в параметр shapes метода IconButton или IconToggleButton.

Кнопки со значками

Состояния кнопки со значком
Рисунок 4. Анимация кнопки со значком в виде круга и квадрата.

В следующем фрагменте показано, как реализовать кнопку со значком, которая анимирует свою форму при нажатии:

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

Кнопки-переключатели со значками

Состояния кнопки-переключателя со значком
Рисунок 5. Переключатель формы значка в выбранном и невыбранном состояниях.

В следующем фрагменте кода показано, как реализовать кнопку-переключатель со значком, форма которого анимируется в зависимости от состояния:

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

Размер, ширина и форма

Кнопки со значками доступны в круглой и квадратной формах, пяти размерах и трех вариантах ширины.

Примеры размеров, форм и ширины кнопок со значками.
Рисунок 6. Доступно пять размеров, две формы и три варианта ширины.

Дополнительную информацию об обновлениях M3 Expressive для кнопок со значками можно найти в руководстве по кнопкам со значками в Material Design 3.

Существует пять вариантов размера кнопок со значками: очень маленький, маленький, средний, большой и очень большой. Для каждого размера поддерживается три варианта ширины: стандартная (по умолчанию), узкая и широкая.

Пять строк и три столбца кнопок со значком сердца. Размер каждой строки увеличивается, а три столбца различаются по ширине: равномерный, узкий и широкий.
Рисунок 7. Кнопки со значками, показывающие пять размеров и три варианта ширины: стандартная, узкая и широкая.

Кнопки со значками доступны в вариантах с круглыми или квадратными углами, а кнопки-переключатели со значками меняют свою форму при нажатии или выборе.

Два ряда по пять кнопок со значком сердца, увеличивающихся в размере слева направо. У верхнего ряда закругленные углы, а у нижнего – квадратные.
Рисунок 8. Кнопки со значками могут быть круглыми или с закругленными углами.

Рекомендации по выбору вариантов углов можно найти в руководстве по кнопкам со значками в Material Design 3.

Дополнительные ресурсы