Кнопки со значками показывают действия, которые могут выполнить пользователи. Кнопки со значками должны использовать значок с понятным значением и обычно представляют собой общие или часто используемые действия.
Существует два типа кнопок со значками:
- По умолчанию. Эти кнопки могут открывать другие элементы, например меню или поиск.
- Переключатель. Эти кнопки могут представлять бинарные действия, которые можно включать или выключать, например "Избранное" или "Закладка".
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. - Параметр
paintercomposable-функции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, ) } }
Основные сведения о коде
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 миллисекунд, пока кнопка нажата.
Результат
На видео ниже показан интерфейс с кнопками-значками и счетчиком.
Обновление M3 Expressive
В обновлении M3 Expressive для кнопок со значками поддерживаются дополнительные параметры размера, угла и ширины, а также возможность изменения формы при нажатии или выборе. При размещении в стандартных группах кнопок кнопки со значками также взаимодействуют с соседними кнопками при нажатии.
Анимированная фигура
Форма кнопок со значками может меняться при нажатии, а форма кнопок-переключателей со значками – в зависимости от состояния. Чтобы включить анимацию фигур, передайте IconButtonDefaults.shapes() или IconButtonDefaults.toggleableShapes() в параметр shapes метода IconButton или IconToggleButton.
Кнопки со значками
В следующем фрагменте показано, как реализовать кнопку со значком, которая анимирует свою форму при нажатии:
@Composable fun IconButtonWithAnimatedShapeSample() { IconButton( onClick = { /* doSomething() */ }, shapes = IconButtonDefaults.shapes(), ) { Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description") } }
Кнопки-переключатели со значками
В следующем фрагменте кода показано, как реализовать кнопку-переключатель со значком, форма которого анимируется в зависимости от состояния:
@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") } } }
Размер, ширина и форма
Кнопки со значками доступны в круглой и квадратной формах, пяти размерах и трех вариантах ширины.
Дополнительную информацию об обновлениях M3 Expressive для кнопок со значками можно найти в руководстве по кнопкам со значками в Material Design 3.
Существует пять вариантов размера кнопок со значками: очень маленький, маленький, средний, большой и очень большой. Для каждого размера поддерживается три варианта ширины: стандартная (по умолчанию), узкая и широкая.
Кнопки со значками доступны в вариантах с круглыми или квадратными углами, а кнопки-переключатели со значками меняют свою форму при нажатии или выборе.
Рекомендации по выбору вариантов углов можно найти в руководстве по кнопкам со значками в Material Design 3.