This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

进度指示器

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

Android

Included in Expo Go

GitHub

npm

更新日志

Expo UI 进度指示器与官方 Jetpack Compose 进度指示器 API 保持一致。

安装

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.