Ordo UI
组件Controls

DatePicker

@mox-hub/ui 组件 · Controls · canonical

date-picker@mox-hub/uiControlscanonicalsrc/components/date-picker.tsx
变体演示date-picker

Props API

Prop类型默认值说明
value*Date——
onValueChange*(date: Date) => void——
placeholder*string——
trigger*ReactElement<unknown, string | JSXElementConstructor<any>>——
footer*ReactNode——
buttonClassName*string——
className*string——
popoverAlign*"center" | "start" | "end""start"—
disabled*boolean——
closeOnSelect*booleantrue—
presets*DatePickerPreset[]——
formatDate*(date: Date) => stringformatDateValue—
calendarProps*Partial<DayPickerProps & { buttonVariant?: "default" | "destructive" | "secondary" | "outline" | "ghost" | "primary" | "danger" | "quiet" | "subtle" | "ghost-danger"; }>——

源码

packages/ui/src/components/date-picker.tsx
"use client"

import { CalendarIcon } from "lucide-react"
import * as React from "react"

import { formatDate as formatDateValue } from "../format"
import { useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { Button } from "./button"
import { Calendar } from "./calendar"
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "./popover"

/*
 * Date Picker —— coss ui 组合模式(registry @coss/date-picker 的组合配方)
 * Popover + Calendar + Button 标准件,收敛各处手写的弹层日历组合。
 * `trigger` 传入自定义触发元素(如 Linear 风格胶囊),`footer` 追加弹层尾部内容(如清除)。
 */

export interface DatePickerPreset {
  label: React.ReactNode
  date: Date
}

export interface DatePickerProps {
  value?: Date
  onValueChange?: (date: Date | undefined) => void
  placeholder?: string
  /** 自定义触发元素(内容自定,样式与开启态由本组件接管);缺省渲染 outline 按钮 */
  trigger?: React.ReactElement
  /** 弹层尾部附加内容(如"清除"操作行) */
  footer?: React.ReactNode
  /** 触发按钮宽度,默认 240px */
  buttonClassName?: string
  className?: string
  /** 弹层对齐,默认 start */
  popoverAlign?: "start" | "center" | "end"
  disabled?: boolean
  /** 选择后关闭弹层,默认 true */
  closeOnSelect?: boolean
  presets?: DatePickerPreset[]
  /** 日期显示格式化,默认 yyyy-MM-dd */
  formatDate?: (date: Date) => string
  /** 透传给 Calendar 的其余 props(disabled 匹配、locale 等) */
  calendarProps?: Partial<React.ComponentProps<typeof Calendar>>
}

export function DatePicker({
  value,
  onValueChange,
  placeholder,
  trigger,
  footer,
  buttonClassName,
  className,
  popoverAlign = "start",
  disabled,
  closeOnSelect = true,
  presets,
  // 走 @mox-hub/ui/format 的容错实现:非法 Date 返回空串而不是抛 RangeError
  formatDate = formatDateValue,
  calendarProps,
}: DatePickerProps) {
  const M = useMessages()
  const resolvedPlaceholder = placeholder ?? M.datePicker.placeholder
  const [open, setOpen] = React.useState(false)

  const handleSelect = (date: Date | undefined) => {
    onValueChange?.(date)
    if (closeOnSelect && date) {
      setOpen(false)
    }
  }

  return (
    <Popover
      open={disabled ? false : open}
      onOpenChange={(next) => {
        // P3-12:disabled 时阻止自定义 trigger 绕过禁用态
        if (!disabled) setOpen(next)
      }}
    >
      {trigger ? (
        <PopoverTrigger
          render={trigger}
          disabled={disabled}
          aria-disabled={disabled || undefined}
        />
      ) : (
        <PopoverTrigger
          render={
            <Button
              variant="outline"
              disabled={disabled}
              data-slot="date-picker-trigger"
              className={cn(
                "w-60 justify-start px-3 font-normal",
                !value && "text-muted-foreground",
                buttonClassName
              )}
            />
          }
        >
          <CalendarIcon data-icon="inline-start" />
          {value ? formatDate(value) : resolvedPlaceholder}
        </PopoverTrigger>
      )}
      <PopoverContent
        align={popoverAlign}
        sideOffset={4}
        className={cn("w-auto gap-0 p-0", className)}
      >
        {presets?.length ? (
          <div data-slot="date-picker-presets" className="flex flex-wrap gap-1 border-b border-border p-2">
            {presets.map((preset, index) => (
              <Button
                key={index}
                variant="secondary"
                size="xs"
                onClick={() => handleSelect(preset.date)}
              >
                {preset.label}
              </Button>
            ))}
          </div>
        ) : null}
        <Calendar
          {...({
            mode: "single",
            selected: value,
            onSelect: handleSelect,
            ...calendarProps,
          } as React.ComponentProps<typeof Calendar>)}
        />
        {footer ? (
          <div data-slot="date-picker-footer" className="border-t border-border p-2">
            {footer}
          </div>
        ) : null}
      </PopoverContent>
    </Popover>
  )
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

日期选择输入,通常由 Popover 与 Calendar 组合;区间与格式化由调用方控制。