进度指示器

用于显示操作状态的 Jetpack Compose 进度指示器组件

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.1

Expo UI Progress Indicators 与官方 Jetpack Compose Progress Indicator API 保持一致。

带有两个分别处于 30% 和 75% 的确定性线性进度条的不确定性圆形进度指示器

安装

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

线性进度

用于指示进度的水平填充条。在确定性模式下，提供一个介于 0 和 1 之间的 progress 值。

LinearExample.tsx

import {
  Host,
  LinearProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function LinearExample() {
  return (
    <Host matchContents>
      <LinearProgressIndicator progress={0.5} />
    </Host>
  );
}

圆形进度

通过增大描边来指示进度的旋转圆环。

CircularExample.tsx

import {
  Host,
  CircularProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function CircularExample() {
  return (
    <Host matchContents>
      <CircularProgressIndicator progress={0.75} />
    </Host>
  );
}

不确定性进度

省略 progress 属性，即可在不指示具体完成程度的情况下持续播放动画。

IndeterminateExample.tsx

import {
  CircularProgressIndicator,
  CircularWavyProgressIndicator,
  Column,
  Host,
  LinearProgressIndicator,
  LinearWavyProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function IndeterminateExample() {
  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 16 }}>
        <LinearProgressIndicator />
        <CircularProgressIndicator />
        <CircularWavyProgressIndicator />
        <LinearWavyProgressIndicator />
      </Column>
    </Host>
  );
}

自定义颜色

使用 color 设置指示器颜色，使用 trackColor 设置背景轨道颜色。

ColorsExample.tsx

import {
  Host,
  CircularProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function ColorsExample() {
  return (
    <Host matchContents>
      <CircularProgressIndicator
        progress={0.6}
        color="red"
        trackColor="#cccccc"
      />
    </Host>
  );
}

波浪变体

LinearWavyProgressIndicator 和 CircularWavyProgressIndicator 添加了来自 Material 3 Expressive 的富有表现力的波浪动画。

WavyExample.tsx

import {
  Host,
  LinearWavyProgressIndicator,
  CircularWavyProgressIndicator,
  Column,
} from '@expo/ui/jetpack-compose';

export default function WavyExample() {
  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 16 }}>
        <LinearWavyProgressIndicator progress={0.6} />
        <CircularWavyProgressIndicator progress={0.6} />
      </Column>
    </Host>
  );
}

波浪配置

使用 amplitude 设置波浪高度，从表示平直线条的 0 到表示完整高度的 1。使用 wavelength 设置单个波浪的长度，单位为 dp；使用 waveSpeed 设置波浪移动的速度，单位为每秒 dp。waveSpeed 默认为 wavelength。设置 waveSpeed={0} 可渲染静态波浪。

WaveConfigExample.tsx

import {
  Host,
  LinearWavyProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function WaveConfigExample() {
  return (
    <Host matchContents>
      <LinearWavyProgressIndicator
        progress={0.6}
        amplitude={0.4}
        wavelength={24}
        waveSpeed={18}
      />
    </Host>
  );
}

API

import {
  LinearProgressIndicator,
  CircularProgressIndicator,
  LinearWavyProgressIndicator,
  CircularWavyProgressIndicator,
} from '@expo/ui/jetpack-compose';

Components

`CircularProgressIndicator`

Android

Type: React.Element<ComponentType<CircularProgressIndicatorProps>>

A circular progress indicator that displays progress in a circular format.

Matches the Jetpack Compose CircularProgressIndicator.

Common props shared by all progress indicator variants.

CircularProgressIndicatorProps

`gapSize`

Android

Optional • Type: number

Gap size between the indicator and track in dp.

`strokeCap`

Android

Optional • Type: StrokeCap • Default: 'round'

Stroke cap style for the indicator ends.

`strokeWidth`

Android

Optional • Type: number

Width of the circular stroke in dp.

Inherited props

ProgressCommonConfig

`CircularWavyProgressIndicator`

Android

Type: React.Element<ComponentType<CircularWavyProgressIndicatorProps>>

A circular progress indicator with wavy animation style.

Matches the Jetpack Compose CircularWavyProgressIndicator.

Common props shared by all progress indicator variants.

CircularWavyProgressIndicatorProps

Inherited props

`LinearProgressIndicator`

Android

Type: React.Element<ComponentType<LinearProgressIndicatorProps>>

A linear progress indicator that displays progress in a horizontal bar.

Matches the Jetpack Compose LinearProgressIndicator.

Common props shared by all progress indicator variants.

LinearProgressIndicatorProps

`drawStopIndicator`

Android

Optional • Type: DrawStopIndicatorConfig

Configuration for the stop indicator dot at the end of the determinate progress track.

`gapSize`

Android

Optional • Type: number

Gap size between the indicator and track in dp.

`strokeCap`

Android

Optional • Type: StrokeCap • Default: 'round'

Stroke cap style for the indicator ends.

Inherited props

ProgressCommonConfig

`LinearWavyProgressIndicator`

Android

Type: React.Element<ComponentType<LinearWavyProgressIndicatorProps>>

A linear progress indicator with wavy animation style.

Matches the Jetpack Compose LinearWavyProgressIndicator.

Common props shared by all progress indicator variants.

LinearWavyProgressIndicatorProps

`stopSize`

Android

Optional • Type: number

Size of the stop indicator in dp at the end of the determinate progress track.

Inherited props

Types

`DrawStopIndicatorConfig`

Android

Configuration for the stop indicator dot at the end of the determinate linear progress track. When provided, draws a stop indicator with the given options. Omit to use the Compose default.

Property	Type	Description
color(optional)	`ColorValue`	Color of the stop indicator. Defaults to the indicator's color.
stopSize(optional)	`number`	Size of the stop indicator in dp. Defaults to the Material 3 default.
strokeCap(optional)	`StrokeCap`	Stroke cap style for the stop indicator. Defaults to the indicator's strokeCap.

`ProgressCommonConfig`

Android

Common props shared by all progress indicator variants.

Property	Type	Description
color(optional)	`ColorValue`	Progress indicator color.
modifiers(optional)	`ModifierConfig[]`	Modifiers for the component.
progress(optional)	`number \| null`	The current progress value between `0` and `1`. Omit for indeterminate.
trackColor(optional)	`ColorValue`	Track (background) color.

`StrokeCap`

Android

Literal type: string

Stroke cap style for progress indicators.

Acceptable values are: 'round' | 'butt' | 'square'

`WavyProgressCommonConfig`

Android

Wave configuration shared by the wavy progress indicator variants.

Property	Type	Description
amplitude(optional)	`number`	Height of the wave, where `0` draws a flat line and `1` draws the full wave height. When set, the amplitude stays the same across the whole track. When omitted, a determinate indicator uses the Material 3 default, which flattens the wave as progress approaches `0` and `1`. An indeterminate indicator defaults to the full wave height.
wavelength(optional)	`number`	Length of a single wave in dp. `CircularWavyProgressIndicator` rounds this to fit a whole number of waves around the ring, so the wave it draws can be slightly shorter or longer.
waveSpeed(optional)	`number`	Speed of the wave in dp per second. Defaults to `wavelength`, which advances the wave by one wavelength per second. Set it to `0` to stop the wave from moving.