DatePicker#
数据录入
@rockshin/tao-ui输入或选择单个日期,并可选择时间。
#何时使用
自由文本日期容易出错,或用户需要日历上下文时使用 DatePicker。
推荐
- 熟悉日期的用户应能直接键盘输入。
- 常用相对日期可以提供预设。
避免
- 选择久远日期时,不要强迫用户只能逐月翻阅日历。
#代码演示
#基础用法
TSX
import { DatePicker, FormField } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';
function DatePickerExample() {
const [value, setValue] = useState<Dayjs | null>(null);
return (
<FormField label="Start date">
<DatePicker
value={value}
onChange={setValue}
placeholder="Select a date"
/>
</FormField>
);
}
export default DatePickerExample;#选择模式
TSX
import { DatePicker, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import { useState } from 'react';
function DatePickerModes() {
const [date, setDate] = useState<Dayjs | null>(null);
const [month, setMonth] = useState<Dayjs | null>(null);
const [year, setYear] = useState<Dayjs | null>(null);
return (
<Stack gap="md" style={{ maxWidth: 320 }}>
<DatePicker
value={date}
onChange={setDate}
picker="date"
placeholder="Select date"
/>
<DatePicker
value={month}
onChange={setMonth}
picker="month"
placeholder="Select month"
/>
<DatePicker
value={year}
onChange={setYear}
picker="year"
placeholder="Select year"
/>
</Stack>
);
}
export default DatePickerModes;#时间、预设与禁用日期
TSX
import { DatePicker, Stack } from '@rockshin/tao-ui';
import dayjs, { type Dayjs } from 'dayjs';
import { useState } from 'react';
function AdvancedDatePicker() {
const [dateTime, setDateTime] = useState<Dayjs | null>(null);
const [preset, setPreset] = useState<Dayjs | null>(null);
const [future, setFuture] = useState<Dayjs | null>(null);
return (
<Stack gap="md" style={{ maxWidth: 320 }}>
<DatePicker
value={dateTime}
onChange={setDateTime}
showTime
placeholder="Select date and time"
/>
<DatePicker
value={preset}
onChange={setPreset}
presets={[
{ label: 'Today', value: dayjs() },
{ label: 'Tomorrow', value: dayjs().add(1, 'day') },
]}
/>
<DatePicker
value={future}
onChange={setFuture}
disabledDate={(current) => current.isBefore(dayjs().startOf('day'))}
placeholder="Future dates only"
/>
</Stack>
);
}
export default AdvancedDatePicker;#日期与时间
showTime 将日期和时间组合选择,格式应同时包含需要展示的部分。
Value: 2026-11-16 12:42:22
TSX
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerWithTime() {
function Demo() {
const [val, setVal] = useState<Dayjs | null>(dayjs());
return (
<Stack gap="md" style={{ maxWidth: 300 }}>
<FormField label="Date & Time">
<DatePicker value={val} onChange={(d) => setVal(d)} showTime />
</FormField>
<p style={{ fontSize: 13, color: 'var(--tao-color-text-secondary)' }}>
Value: {val ? val.format('YYYY-MM-DD HH:mm:ss') : 'none'}
</p>
</Stack>
);
}
return <Demo />;
}#常用日期预设
用 presets 提供常见日期,减少重复打开日历和定位日期的操作。
TSX
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerWithPresets() {
function Demo() {
const [val, setVal] = useState<Dayjs | null>(null);
return (
<Stack gap="md" style={{ maxWidth: 300 }}>
<FormField label="With Presets">
<DatePicker
value={val}
onChange={(d) => setVal(d)}
presets={[
{ label: 'Today', value: dayjs() },
{ label: 'Yesterday', value: dayjs().subtract(1, 'day') },
{ label: 'Last week', value: dayjs().subtract(7, 'day') },
{ label: 'Last month', value: dayjs().subtract(1, 'month') },
]}
/>
</FormField>
</Stack>
);
}
return <Demo />;
}#限制可选日期
disabledDate 按业务规则限制日期;本例使用本地日期计算。
TSX
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerDisabledDates() {
function Demo() {
const [val, setVal] = useState<Dayjs | null>(null);
return (
<Stack gap="md" style={{ maxWidth: 300 }}>
<FormField label="Only future dates">
<DatePicker
value={val}
onChange={(d) => setVal(d)}
disabledDate={(d) => d.isBefore(dayjs(), 'day')}
/>
</FormField>
<FormField label="With min/max">
<DatePicker
value={val}
onChange={(d) => setVal(d)}
minDate={dayjs().subtract(7, 'day')}
maxDate={dayjs().add(30, 'day')}
/>
</FormField>
</Stack>
);
}
return <Demo />;
}#尺寸与外观
选择不同尺寸与 variant,匹配页面中的其他输入控件。
TSX
import { DatePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
<Stack direction="vertical">
{(['small', 'medium', 'large'] as const).map((size) => (
<DatePicker key={size} size={size} />
))}
<DatePicker variant="filled" />
<DatePicker variant="borderless" />
</Stack>
);
}#状态与禁用
error 与 warning 表达校验状态,disabled 用于不可编辑的值。
TSX
import { DatePicker, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
<Stack direction="vertical">
<DatePicker status="error" />
<DatePicker status="warning" />
<DatePicker disabled />
</Stack>
);
}#切换语言
通过 TaoProvider 的 locale 同步内置按钮、占位文字与日历标签。
TSX
import { useState } from 'react';
import {
DatePicker,
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}>
<DatePicker />
</TaoProvider>
</Stack>
);
}#限制日期范围
minDate 与 maxDate 同时限制输入和日历导航,示例固定为 2026 年以便复现。
TSX
import dayjs from 'dayjs';
import { DatePicker } from '@rockshin/tao-ui';
export default function Example() {
return (
<DatePicker
minDate={dayjs('2026-01-01')}
maxDate={dayjs('2026-12-31')}
defaultValue={dayjs('2026-06-10')}
/>
);
}#受控值与清空
在 onChange 中保存值;清空后将值设为 null。
TSX
import { useState } from 'react';
import type { Dayjs } from 'dayjs';
import { DatePicker, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [value, setValue] = useState<Dayjs | null>(null);
return (
<Stack direction="vertical">
<DatePicker value={value} onChange={setValue} allowClear />
<Button onClick={() => setValue(null)}>Clear value</Button>
<output>{value?.format('YYYY-MM-DD') || 'No selection'}</output>
</Stack>
);
}#自定义显示格式
format 控制显示文本,值仍是 Dayjs;不要将显示格式误认为存储格式。
TSX
import { DatePicker } from '@rockshin/tao-ui';
export default function Example() {
return <DatePicker format="DD/MM/YYYY" />;
}#手机日期抽屉
通过 mobile 在桌面也能试用抽屉,确认操作完成后提交选中日期。
TSX
import { DatePicker, FormField, Stack } from '@rockshin/tao-ui';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';
import { useState } from 'react';
export default function DatePickerMobileDatePicker() {
function Demo() {
const [val, setVal] = useState<Dayjs | null>(null);
return (
<Stack gap="md" style={{ maxWidth: 300 }}>
<p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
Using <code>mobile</code> prop to force Drawer mode.
</p>
<FormField label="Mobile DatePicker">
<DatePicker
value={val}
onChange={(d) => setVal(d)}
mobile
presets={[
{ label: 'Today', value: dayjs() },
{ label: 'Yesterday', value: dayjs().subtract(1, 'day') },
]}
/>
</FormField>
</Stack>
);
}
return <Demo />;
}移动端抽屉标题按 mobileTitle → 最近的 Form.Item / FormField 的 label → 本地化默认文案取值。必填星号和帮助信息不会带入标题,placeholder 只用于输入提示。独立使用或搭配原生 HTML label 时,可显式设置 mobileTitle="出发日期"。
#移动端选择
在手机预览中打开选择器,体验抽屉内的选择、确认和清空。
TSX
import { DatePicker, TaoProvider, zhCN } from '@rockshin/tao-ui';
export default function Example() {
return (
<TaoProvider locale={zhCN}>
<DatePicker allowClear />
</TaoProvider>
);
}#API
#DatePicker
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| disabled | 是否禁用 | boolean | undefined | - |
| mobileTitle | Mobile drawer title. Defaults to the Form.Item/FormField label, then locale text. | ReactNode | - |
| className | 节点类名 | string | undefined | - |
| style | 节点样式 | CSSProperties | undefined | - |