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

更新日志

信息有关跨平台用法，请参见通用的 Slider —— 它会根据平台渲染相应的原生组件。

Expo UI Slider 与官方的 Jetpack Compose Slider 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.

用法

基础滑块

BasicSliderExample.tsx

import { useState } from 'react';
import { Host, Slider } from '@expo/ui/jetpack-compose';

export default function BasicSliderExample() {
  const [value, setValue] = useState(0.5);

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <Slider value={value} onValueChange={setValue} />
    </Host>
  );
}

带自定义范围的滑块

使用 min 和 max 属性来定义滑块的数值范围。

CustomRangeSliderExample.tsx

import { useState } from 'react';
import { Host, Slider } from '@expo/ui/jetpack-compose';

export default function CustomRangeSliderExample() {
  const [value, setValue] = useState(50);

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <Slider
        value={value}
        min={0}
        max={100}
        onValueChange={setValue}
      />
    </Host>
  );
}

带步进的滑块

使用 steps 属性来定义离散增量。将 steps 设为 0 可表示连续值。

SteppedSliderExample.tsx

import { useState } from 'react';
import { Host, Slider } from '@expo/ui/jetpack-compose';

export default function SteppedSliderExample() {
  const [value, setValue] = useState(0);

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <Slider
        value={value}
        min={0}
        max={100}
        steps={10}
        onValueChange={setValue}
      />
    </Host>
  );
}

自定义颜色

使用 colors 属性覆盖滑块拇指、轨道和刻度标记的默认 Material3 颜色。

CustomColorsSliderExample.tsx

import { useState } from 'react';
import { Host, Slider } from '@expo/ui/jetpack-compose';

export default function CustomColorsSliderExample() {
  const [value, setValue] = useState(0.5);

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <Slider
        value={value}
        colors={{
          thumbColor: '#6200EE',
          activeTrackColor: '#6200EE',
          inactiveTrackColor: '#E0E0E0',
        }}
        onValueChange={setValue}
      />
    </Host>
  );
}

自定义拇指和轨道

同时使用 Slider.Thumb 和 Slider.Track 插槽即可实现完全自定义的滑块外观。

FullyCustomSliderExample.tsx

import { useState } from 'react';
import {
  Host,
  Slider,
  Shape,
  Row,
  Box,
} from '@expo/ui/jetpack-compose';
import {
  fillMaxWidth,
  height,
  weight,
  size,
  clip,
  background,
  Shapes,
} from '@expo/ui/jetpack-compose/modifiers';

export default function FullyCustomSliderExample() {
  const [value, setValue] = useState(0.5);

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <Slider value={value} onValueChange={setValue}>
        <Slider.Thumb>
          <Box
            modifiers={[
              size(24, 24),
              clip(Shapes.Circle),
              background('#6200EE'),
            ]}
          />
        </Slider.Thumb>
        <Slider.Track>
          <Row modifiers={[fillMaxWidth(), height(8)]}>
            <Shape.RoundedCorner
              color="#6200EE"
              cornerRadii={{ topStart: 4, bottomStart: 4 }}
              modifiers={[weight(Math.max(value, 0.01)), height(8)]}
            />
            <Shape.RoundedCorner
              color="#BDBDBD"
              cornerRadii={{ topEnd: 4, bottomEnd: 4 }}
              modifiers={[
                weight(Math.max(1 - value, 0.01)),
                height(8),
              ]}
            />
          </Row>
        </Slider.Track>
      </Slider>
    </Host>
  );
}

垂直滑块

使用 VerticalSlider 沿垂直轨道选择单个数值。设置 reverseDirection 可使数值从下往上递增，而不是从上往下递增。

VerticalSliderExample.tsx

import { useState } from 'react';
import { Host, VerticalSlider } from '@expo/ui/jetpack-compose';
import { height } from '@expo/ui/jetpack-compose/modifiers';

export default function VerticalSliderExample() {
  const [value, setValue] = useState(0.5);

  return (
    <Host matchContents>
      <VerticalSlider
        value={value}
        reverseDirection
        onValueChange={setValue}
        modifiers={[height(240)]}
      />
    </Host>
  );
}

API

import { Slider, VerticalSlider } from '@expo/ui/jetpack-compose';

Components

`Slider`

Android

Type: React.Element<SliderProps>

A slider component that wraps Material3's Slider.

SliderProps

`children`

Android

Optional • Type: ReactNode

Slot children for custom thumb and track.

`colors`

Android

Optional • Type: SliderColors

Colors for slider elements. Maps to Material3's SliderDefaults.colors().

`enabled`

Android

Optional • Type: boolean • Default: true

Whether the slider is enabled for user interaction.

`lowerLimit`

Android

Optional • Type: number

Lower limit the user can drag the thumb to. The visible track still spans min..max, but the thumb stops at lowerLimit during drag.

`max`

Android

Optional • Type: number • Default: 1

The maximum value of the slider. Updating this value does not trigger callbacks if the current value is above max.

`min`

Android

Optional • Type: number • Default: 0

The minimum value of the slider. Updating this value does not trigger callbacks if the current value is below min.

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`onValueChange`

Android

Optional • Type: (value: number) => void

Callback triggered on dragging along the slider.

`onValueChangeFinished`

Android

Optional • Type: () => void

Callback triggered when the user finishes changing the value (for example, lifts a finger). Maps to Material3's onValueChangeFinished.

`steps`

Android

Optional • Type: number • Default: 0

The number of steps between the minimum and maximum values, 0 signifies infinite steps.

`upperLimit`

Android

Optional • Type: number

Upper limit the user can drag the thumb to. The visible track still spans min..max, but the thumb stops at upperLimit during drag.

`value`

Android

Optional • Type: number • Default: 0

The current value of the slider.

`VerticalSlider`

Android

Type: React.Element<VerticalSliderProps>

A vertical slider component that wraps Material3's VerticalSlider.

VerticalSliderProps

`reverseDirection`

Android

Optional • Type: boolean • Default: false

Whether the direction of the slider is reversed. By default, values increase from top to bottom.

Inherited props

SliderProps

Types

`SliderColors`

Android

Colors for slider elements. Maps directly to Material3's SliderDefaults.colors().

Property	Type	Description
activeTickColor(optional)	`ColorValue`	-
activeTrackColor(optional)	`ColorValue`	-
inactiveTickColor(optional)	`ColorValue`	-
inactiveTrackColor(optional)	`ColorValue`	-
thumbColor(optional)	`ColorValue`	-