Leaf UI
  • 简体中文

      • DatePicker 日期选择器

      用于选择日期。

      需要同时选择时间时，使用 DateTimePicker；需要起止区间时，使用 DateRangePicker。

      基础选择

      点击控件打开日历，选择日期后收起。defaultValue 设置初始日期，disabled 禁用整个控件。

      交互预览基础选择
      basic.tsx
      import { DatePicker } from '@sudden3/leaf-ui';

export function DatePickerBasic() {
  return (
    <div className="leaf-demo-stack">
      <DatePicker aria-label="选择日期" placeholder="选择一个好日子" />
      <DatePicker aria-label="默认日期" defaultValue={new Date(2026, 9, 15)} />
      <DatePicker aria-label="禁用日期" defaultValue={new Date(2026, 9, 15)} disabled />
    </div>
  );
}

      受控与日期限制

      通过 minDate / maxDate 限定可选日期，边界当天也可以选择。onChange 同时提供 Date 对象和本地日期字符串。

      交互预览受控与日期限制
      可选 10 月 5–25 日，当前值：2026-10-15
      controlled.tsx
      import { DatePicker } from '@sudden3/leaf-ui';
import { useState } from 'react';

export function DatePickerControlled() {
  const [date, setDate] = useState<Date | null>(new Date(2026, 9, 15));
  const [dateString, setDateString] = useState('2026-10-15');
  return (
    <div className="leaf-demo-stack">
      <DatePicker
        aria-label="十月的日期"
        value={date}
        minDate={new Date(2026, 9, 5)}
        maxDate={new Date(2026, 9, 25)}
        onChange={(next, text) => {
          setDate(next);
          setDateString(text);
        }}
      />
      <span className="leaf-demo-note">可选 10 月 5–25 日，当前值：{dateString || '未选择'}</span>
      <DatePicker aria-label="必填日期" status="error" required placeholder="请设置截止日期" />
    </div>
  );
}

      快捷日期

      通过 todayText 修改今天按钮文字，renderExtraFooter 增加快捷操作，showToday=false 隐藏今天按钮。

      交互预览快捷日期
      footer.tsx
      import { Button, DatePicker } from '@sudden3/leaf-ui';
import { useState } from 'react';
export function DatePickerFooter() {
  const [value, setValue] = useState<Date | null>(null);
  const tomorrow = () => {
    const next = new Date();
    next.setDate(next.getDate() + 1);
    next.setHours(0, 0, 0, 0);
    setValue(next);
  };
  return (
    <DatePicker
      aria-label="自定义快捷日期"
      value={value}
      onChange={setValue}
      todayText="今天"
      renderExtraFooter={
        <Button variant="ghost" size="sm" onClick={tomorrow}>
          明天
        </Button>
      }
    />
  );
}

      DatePicker API

      属性类型默认值说明
      value / defaultValueDate | nullnull受控日期 / 非受控初始日期
      onChange(date: Date | null, dateString: string) => void—日期变更；清除时返回 null 和空字符串
      minDate / maxDateDate—最早 / 最晚可选日期，按本地年月日比较
      showTodaybooleantrue展示今天快捷按钮
      todayTextReactNode语言默认值自定义今天按钮文字
      renderExtraFooterReactNode—额外底部内容，可放快捷操作
      allowClearbooleantrue展示清除按钮
      placeholderstring'请选择日期'未选择时的提示文字
      size'sm' | 'md' | 'lg''md'选择器尺寸
      status'error' | 'warning'—校验状态
      disabledbooleanfalse禁用输入与浮层
      name / formstring—字段名 / 关联的表单 ID
      requiredbooleanfalse要求选择日期
      onOpenChange(open: boolean) => void—日历展开或收起
      refRef<HTMLInputElement>—输入框引用

      其余原生 input 属性和 aria-* 透传至输入框；className / style 作用于外层容器。

      类型

      可导入 DatePickerProps 定义组件属性，或单独使用尺寸、校验状态类型：

      import type { DatePickerProps, ControlSize, ControlStatus } from '@sudden3/leaf-ui';

      日期与表单

      传入有效 Date 对象，且 minDate 不晚于 maxDate。组件按本地日期处理：可用 new Date(2026, 9, 15) 表示 2026 年 10 月 15 日，月份从 0 开始。选择结果为本地当天零点；避免用 UTC 字符串转换代替本地日期构造。

      设置 name 后，FormData 中的值为 YYYY-MM-DD，清除后为空字符串。非受控组件支持表单 reset，受控组件需同步重置自己的状态。当前提供单日期选择，日历从周一开始。

      键盘与主题

      点击控件打开日历，↓ 移入日历。方向键按日或周移动，Home / End 移至本周首尾，PageUp / PageDown 切换月份，Enter 选择。Tab 依次访问月切换与日期；离开面板时回到表单中的后续控件，Escape 收起并聚焦输入框。

      为控件提供 label 或 aria-label。日历沿用控件所在容器的主题色、圆角和浅深色变量；点击外部或移走焦点会收起。

      可以直接输入 YYYY-MM-DD，按 Enter 或移走焦点提交。无效日期和超出 minDate / maxDate 的值不会提交。点击日历顶部的月份、年份可切换选择面板；默认展示“今天”快捷按钮，可通过 showToday、todayText 与 renderExtraFooter 定制。

      点击输入框保留输入焦点；↓ 将焦点移入日历，Escape 放弃未完成输入。