> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# RangePicker

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

选择开始与结束日期，并可包含时间和快捷预设。

## 何时使用

筛选、报表或预订流程需要明确时间范围时使用 RangePicker。

**推荐**

- 提供常用范围预设。
- 清晰表达开始与结束顺序。

**避免**

- 只选单日时不要使用 RangePicker。

## 代码演示


### 基础用法
```tsx preview
import { FormField, RangePicker } from '@rockshin/tao-ui';

function RangePickerExample() {
  return (
    <FormField label="Reporting period">
      <RangePicker />
    </FormField>
  );
}

export default RangePickerExample;
```

### 受控日期范围
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';

function ControlledRangePicker() {
  const [value, setValue] = useState<[Dayjs | null, Dayjs | null] | null>([
    dayjs().startOf('week'),
    dayjs().endOf('week'),
  ]);

  return <RangePicker value={value} onChange={setValue} />;
}

export default ControlledRangePicker;
```

### 预设与时间
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
import dayjs from 'dayjs';

function RangePickerPresets() {
  return (
    <Stack gap="md">
      <RangePicker
        presets={[
          {
            label: 'This week',
            value: [dayjs().startOf('week'), dayjs().endOf('week')],
          },
          {
            label: 'This month',
            value: [dayjs().startOf('month'), dayjs().endOf('month')],
          },
        ]}
      />
      <RangePicker showTime />
    </Stack>
  );
}

export default RangePickerPresets;
```

### 范围选择与清除
依次选择开始和结束日期，维护范围值并提供清除入口。
```tsx preview
import { FormField, RangePicker, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import { useState } from 'react';

export default function DatePickerRangePickerBasic() {
  function Demo() {
    const [val, setVal] = useState<[Dayjs | null, Dayjs | null] | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 500 }}>
        <FormField label="Date Range">
          <RangePicker value={val} onChange={(d) => setVal(d)} />
        </FormField>
        <p style={{ fontSize: 13, color: 'var(--tao-color-text-secondary)' }}>
          Range: {val?.[0]?.format('YYYY-MM-DD') ?? '?'} ~{' '}
          {val?.[1]?.format('YYYY-MM-DD') ?? '?'}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 常用时间范围
为报表和筛选提供常用范围；预设值与用户手选范围使用同一值结构。
```tsx preview
import { FormField, RangePicker, Stack } from '@rockshin/tao-ui';

import type { Dayjs } from 'dayjs';

import dayjs from 'dayjs';

import { useState } from 'react';

export default function DatePickerRangePickerPresets() {
  function Demo() {
    const [val, setVal] = useState<[Dayjs | null, Dayjs | null] | null>(null);
    return (
      <Stack gap="md" style={{ maxWidth: 500 }}>
        <FormField label="Range with presets">
          <RangePicker
            value={val}
            onChange={(d) => setVal(d)}
            presets={[
              {
                label: 'This week',
                value: [dayjs().startOf('week'), dayjs().endOf('week')],
              },
              {
                label: 'This month',
                value: [dayjs().startOf('month'), dayjs().endOf('month')],
              },
              {
                label: 'Last 7 days',
                value: [dayjs().subtract(7, 'day'), dayjs()],
              },
              {
                label: 'Last 30 days',
                value: [dayjs().subtract(30, 'day'), dayjs()],
              },
            ]}
          />
        </FormField>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 尺寸与外观
选择不同尺寸与 variant，匹配页面中的其他输入控件。
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <RangePicker key={size} size={size} />
      ))}
      <RangePicker variant="filled" />
      <RangePicker variant="borderless" />
    </Stack>
  );
}
```

### 状态与禁用
error 与 warning 表达校验状态，disabled 用于不可编辑的值。
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <RangePicker status="error" />
      <RangePicker status="warning" />
      <RangePicker disabled />
    </Stack>
  );
}
```

### 切换语言
通过 TaoProvider 的 locale 同步内置按钮、占位文字与日历标签。
```tsx preview
import { useState } from 'react';
import {
  RangePicker,
  TaoProvider,
  zhCN,
  enUS,
  Button,
  Stack,
} from '@rockshin/tao-ui';
export default function Example() {
  const [chinese, setChinese] = useState(false);
  return (
    <Stack direction="vertical">
      <Button onClick={() => setChinese(!chinese)}>
        {chinese ? 'Switch to English' : '切换到中文'}
      </Button>
      <TaoProvider locale={chinese ? zhCN : enUS}>
        <RangePicker />
      </TaoProvider>
    </Stack>
  );
}
```

### 限制日期范围
minDate 与 maxDate 同时限制输入和日历导航，示例固定为 2026 年以便复现。
```tsx preview
import dayjs from 'dayjs';
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <RangePicker
      minDate={dayjs('2026-01-01')}
      maxDate={dayjs('2026-12-31')}
      defaultValue={[dayjs('2026-06-10'), dayjs('2026-06-15')]}
    />
  );
}
```

### 受控值与清空
传入 `value` 控制范围，并在 `onChange` 中保存新值。应用需要重置范围时，将 `value` 设为 `null`。
两端均可编辑时，内置清空按钮会触发 `onChange(null, ['', ''])`。从 [0.0.49](https://rickyshin93.github.io/tao-ui/zh/guide/changelog.md) 起，组件会直接丢弃正在编辑的文本，避免先把它作为已选范围发出。
```tsx preview
import { useState } from 'react';
import type { Dayjs } from 'dayjs';
import { RangePicker, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [value, setValue] = useState<[Dayjs | null, Dayjs | null] | null>(null);
  return (
    <Stack direction="vertical">
      <RangePicker value={value} onChange={setValue} allowClear />
      <Button onClick={() => setValue(null)}>Clear value</Button>
      <output>
        {value?.map((date) => date?.format('YYYY-MM-DD') || '—').join(' → ') ||
          'No selection'}
      </output>
    </Stack>
  );
}
```

### 自定义显示格式
format 控制显示文本，值仍是 Dayjs；不要将显示格式误认为存储格式。
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return <RangePicker format="DD/MM/YYYY" />;
}
```

### 日期与时间范围
showTime 增加两端的时间选择，确认后提交完整区间。
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return <RangePicker showTime format="YYYY-MM-DD HH:mm" />;
}
```

### 月份与年份范围
picker 选择月份或年份粒度。
```tsx preview
import { RangePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <RangePicker picker="month" />
      <RangePicker picker="year" />
    </Stack>
  );
}
```

### 仅禁用一端
元组形式的 disabled 可单独锁定开始或结束输入。
```tsx preview
import { RangePicker } from '@rockshin/tao-ui';
export default function Example() {
  return <RangePicker disabled={[true, false]} />;
}
```

移动端抽屉标题按 `mobileTitle` → 最近的 `Form.Item` / `FormField` 的 label → 本地化默认文案取值。必填星号和帮助信息不会带入标题，placeholder 只用于输入提示。独立使用或搭配原生 HTML label 时，可显式设置 `mobileTitle="出发日期"`。
### 移动端选择
在手机预览中打开选择器，体验抽屉内的选择、确认和清空。
```tsx preview="iframe-follow"
import { RangePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider locale={zhCN}>
      <RangePicker allowClear />
    </TaoProvider>
  );
}
```

## API


### [#](#rangepicker)RangePicker



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | [boolean, boolean] | undefined` | `-` |
| mobileTitle | Mobile drawer title. Defaults to the Form.Item/FormField label, then locale text. | `ReactNode` | `-` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

