组件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* | boolean | true | — |
| presets* | DatePickerPreset[] | — | — |
| formatDate* | (date: Date) => string | formatDateValue | — |
| calendarProps* | Partial<DayPickerProps & { buttonVariant?: "default" | "destructive" | "secondary" | "outline" | "ghost" | "primary" | "danger" | "quiet" | "subtle" | "ghost-danger"; }> | — | — |
源码
"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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
日期选择输入,通常由 Popover 与 Calendar 组合;区间与格式化由调用方控制。