Индикаторы прогресса

Индикаторы выполнения визуально показывают статус операции. Они используют движение, чтобы привлечь внимание пользователя к тому, насколько близок процесс к завершению, например, загрузка или обработка данных. Они также могут указывать на то, что обработка выполняется, без ссылки на то, насколько близко она может быть к завершению.

Рассмотрим три варианта использования, в которых вы можете использовать индикатор выполнения:

  • Загрузка контента. При получении контента из сети, например при загрузке изображения или данных для профиля пользователя.
  • Загрузка файла. Сообщите пользователю, сколько времени может занять загрузка.
  • Долгая обработка. Если приложение обрабатывает большой объем данных, показывайте пользователю, какая часть работы уже выполнена.

В Material Design есть два типа индикаторов выполнения:

  • Определенный. Показывает, какая часть процесса уже выполнена.
  • Неопределенный. Анимация воспроизводится непрерывно, независимо от прогресса.

Индикатор выполнения может быть двух видов:

  • Линейный. Горизонтальная полоса, которая заполняется слева направо.
  • Круг. Круг, обводка которого увеличивается, пока не охватит всю окружность.
Линейный и круговой индикаторы выполнения.
Рисунок 1. Два типа индикаторов выполнения.

API surface

Хотя для создания индикаторов прогресса в соответствии с Material Design можно использовать несколько composable-функций, их параметры не сильно различаются. Вот основные параметры, которые следует учитывать:

  • progress – текущий прогресс, который показывает индикатор. Передайте Float в диапазоне от 0.0 до 1.0.
  • color – цвет индикатора. То есть часть компонента, которая отражает прогресс и которая полностью охватывает компонент, когда прогресс завершен.
  • trackColor – цвет дорожки, на которой нарисован индикатор.

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

В Material 3 Expressive представлены дополнительные варианты LinearWavyProgressIndicator и CircularWavyProgressIndicator, а также стандартные плоские LinearProgressIndicator и CircularProgressIndicator. Эти индикаторы имеют закругленный стиль и конфигурации для высоты дорожки и формы волны. Выберите визуальный стиль, который лучше всего подходит для вашего товара.

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

Рисунок 2. Волнистые формы и переменная высота дорожки индикатора выполнения Material 3 Expressive.

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

Волнистый мир

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

Рисунок 3. Волнообразные индикаторы выполнения с выразительными параметрами волны.

Волнистые линейные индикаторы увеличивают высоту контейнера.

Есть два варианта переливающихся индикаторов выполнения: линейный и круглый.

Определенный линейный волнообразный индикатор выполнения

По умолчанию при использовании волнистого индикатора выполнения применяется скорость волны, чтобы создать постоянное волновое движение, даже в детерминированном режиме. Вы можете отключить это волнообразное движение, передав 0.dp в waveSpeed.

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

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LinearWavyProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearWavyProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

Неопределенный линейный волнообразный индикатор выполнения

Используйте неопределенные индикаторы, чтобы показать, что процесс происходит, когда время ожидания неизвестно. В следующем фрагменте кода показано, как реализовать неопределенный индикатор LinearWavyProgressIndicator:

@Composable
fun IndeterminateLinearWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearWavyProgressIndicator() }
}

Определенный круговой волнообразный индикатор выполнения

Волнистая форма делает длительные процессы менее статичными и лучше всего подходит, когда уместен более выразительный стиль. В следующем фрагменте кода показано, как реализовать определенный индикатор CircularWavyProgressIndicator, управляемый с помощью Slider:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CircularWavyProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        CircularWavyProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

Неопределенный круговой волнообразный индикатор выполнения

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

@Composable
fun IndeterminateCircularWavyProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularWavyProgressIndicator() }
}

Фиксированный

Индикаторы с определенным значением

Определенный индикатор показывает, насколько завершено действие. Используйте composable-функцию LinearProgressIndicator или CircularProgressIndicator и передайте значение для параметра progress.

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

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LinearProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        LinearProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

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

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CircularProgressIndicatorSample() {
    val sliderState = rememberSliderState(0.1f)
    val animatedProgress by animateFloatAsState(
            targetValue = sliderState.value,
            animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
        )

    Column(horizontalAlignment = Alignment.CenterHorizontally) {
        CircularProgressIndicator(progress = { animatedProgress })
        Spacer(Modifier.requiredHeight(30.dp))
        Text("Set progress:")
        Slider(
            state = sliderState,
            onValueChange = { sliderState.value = it },
            modifier = Modifier.width(300.dp),
        )
    }
}

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

@Composable
fun LinearDeterminateIndicator() {
    var currentProgress by remember { mutableFloatStateOf(0f) }
    var loading by remember { mutableStateOf(false) }
    val scope = rememberCoroutineScope() // Create a coroutine scope
    // Animate between progress updates so the indicator fills smoothly.
    val animatedProgress by animateFloatAsState(
        targetValue = currentProgress,
        animationSpec = ProgressIndicatorDefaults.ProgressAnimationSpec,
    )

    if (loading) {
        LinearProgressIndicator(
            progress = { animatedProgress },
            modifier = Modifier.fillMaxWidth(),
        )
    } else {
        Button(onClick = {
            loading = true
            scope.launch {
                loadProgress { progress ->
                    currentProgress = progress
                }
                loading = false // Reset loading when the coroutine finishes
            }
        }) {
            Text("Start loading")
        }
    }
}

/** Iterate the progress value */
suspend fun loadProgress(updateProgress: (Float) -> Unit) {
    for (i in 1..100) {
        updateProgress(i.toFloat() / 100)
        delay(100)
    }
}

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

Рисунок 4. Линейный индикатор выполнения.

Круглый индикатор выглядит следующим образом:

Рисунок 5. Круговой индикатор выполнения.

Индикаторы неопределенного состояния

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

Чтобы создать неопределенный индикатор выполнения, используйте composable-функцию LinearProgressIndicator или CircularProgressIndicator, но не передавайте значение для progress. В следующем фрагменте кода показано, как реализовать неопределенный индикатор LinearProgressIndicator:

@Composable
fun IndeterminateLinearProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { LinearProgressIndicator() }
}

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

@Composable
fun IndeterminateCircularProgressIndicatorSample() {
    Column(horizontalAlignment = Alignment.CenterHorizontally) { CircularProgressIndicator() }
}

В следующем примере показано, как можно переключать неопределенный индикатор нажатием кнопки. В этом примере также показано, как передавать значения параметров color и trackColor, чтобы настроить внешний вид индикатора.

@Composable
fun IndeterminateCircularIndicator() {
    var loading by remember { mutableStateOf(false) }

    if (loading) {
        CircularProgressIndicator(
            modifier = Modifier.size(64.dp),
            color = MaterialTheme.colorScheme.secondary,
            trackColor = MaterialTheme.colorScheme.surfaceVariant,
        )
    } else {
        Button(onClick = { loading = true }) {
            Text("Start loading")
        }
    }
}

Ниже приведен пример реализации, когда индикатор активен.

Рисунок 6. Круговой индикатор выполнения.

Ниже приведен пример той же реализации, но с LinearProgressIndicator вместо CircularProgressIndicator:

Рисунок 7. Линейный индикатор выполнения.

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