Slider - Kumo 中文文档

Price range

import { Slider } from "@cloudflare/kumo";

export function SliderRangeDemo() {
  return (
    <Slider
      label="Price range"
      defaultValue={[25, 75]}
      getAriaLabel={(index) =>
        index === 0 ? "Minimum price" : "Maximum price"
      }
      className="w-72"
    />
  );
}

安装

批量导入

import { Slider } from "@cloudflare/kumo";

细粒度导入

import { Slider } from "@cloudflare/kumo/components/slider";

用法

import { Slider } from "@cloudflare/kumo";

export default function Example() {
  return <Slider label="Volume" defaultValue={40} />;
}

Slider 基于 Base UI 的 Slider 构建。 value、defaultValue、min、max、step、format、onValueChange 等属性会直接透传给它。

示例

基础 Slider

单个滑块，下方徽章显示当前值，两端分别是最小值和最大值。

Volume

import { Slider } from "@cloudflare/kumo";

export function SliderBasicDemo() {
  return <Slider label="Volume" defaultValue={40} className="w-72" />;
}

范围

向 value 或 defaultValue 传入数组，即可为每个值渲染一个滑块。用 getAriaLabel 为每个滑块指定各自的无障碍名称。

Price range

import { Slider } from "@cloudflare/kumo";

export function SliderRangeDemo() {
  return (
    <Slider
      label="Price range"
      defaultValue={[25, 75]}
      getAriaLabel={(index) =>
        index === 0 ? "Minimum price" : "Maximum price"
      }
      className="w-72"
    />
  );
}

自定义范围与步长

设置 min、max 和 step 来约束取值。

Match count

import { Slider } from "@cloudflare/kumo";

export function SliderStepDemo() {
  return (
    <Slider label="Match count" defaultValue={2} max={5} className="w-72" />
  );
}

格式化数值

format 接受 Intl.NumberFormat 的选项，并作用于数值徽章、范围标签以及向辅助技术播报的值。

Sampling rate

import { Slider } from "@cloudflare/kumo";

export function SliderFormatDemo() {
  return (
    <Slider
      label="Sampling rate"
      defaultValue={0.25}
      min={0}
      max={1}
      step={0.05}
      format={{ style: "percent" }}
      className="w-72"
    />
  );
}

尺寸

密集布局中可使用 size="sm"。

Small

Base

import { Slider } from "@cloudflare/kumo";

export function SliderSizesDemo() {
  return (
    <div className="flex w-72 flex-col gap-6">
      <Slider label="Small" size="sm" defaultValue={30} />
      <Slider label="Base" defaultValue={30} />
    </div>
  );
}

受控用法

传入 value 和 onValueChange 即可受控使用滑块。

Brightness

Brightness: 50%

import { useState } from "react";
import { Slider } from "@cloudflare/kumo";

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

  return (
    <div className="flex w-72 flex-col gap-3">
      <Slider
        label="Brightness"
        value={value}
        onValueChange={(next) => setValue(next)}
      />
      <p className="text-sm text-kumo-subtle">Brightness: {value}%</p>
    </div>
  );
}

禁用状态

Locked

import { Slider } from "@cloudflare/kumo";

export function SliderDisabledDemo() {
  return <Slider label="Locked" defaultValue={70} disabled className="w-72" />;
}

无障碍

每个滑块都是原生的 range input，因此方向键、Page Up/Page Down 和 Home/End 默认就可用。
label 为滑块及其滑块头命名。没有可见标签时，请传入 getAriaLabel。
数值徽章和范围标签对辅助技术隐藏，因为每个滑块头已经会播报自己格式化后的值。

API 参考

属性	类型	默认值	说明
size	`"sm" \| "base"`	`"base"`	-
label	`ReactNode`	-	Label displayed above the slider track.
getAriaLabel	`(index: number) => string`	-	Accessible name for each thumb. Use it when there is no visible `label`, or to tell the thumbs of a range slider apart.
value	`number \| readonly number[]`	-	Controlled value. Pass an array to render one thumb per value (a range).
defaultValue	`number \| readonly number[]`	-	Uncontrolled initial value. Pass an array to render one thumb per value (a range).
onValueChange	`(value: number \| readonly number[], eventDetails: SliderRoot.ChangeEventDetails) => void`	-	Called when the value changes while dragging or from the keyboard
min	`number`	-	Minimum value of the slider (default: 0)
max	`number`	-	Maximum value of the slider (default: 100)
step	`number`	-	Amount the value changes per step (default: 1)
format	`Intl.NumberFormatOptions`	-	Formats the value badges, range labels, and the value announced to assistive technology
disabled	`boolean`	-	Whether the slider is disabled