DatePicker (日期选择器)

日期 / 日期范围选择器(基于 date-fns),支持格式化、最小/最大值与禁用日期。

基础用法

Value: —

Basic.vue

日期范围

起始:—

结束:—

Range.vue

选择粒度(日 / 月 / 年)

2026-09-05

2026-09

2026

2018 → 2024

Precision.vue

格式与禁用日期

Value: —

已禁用过去的日期、周六与周日

Format.vue

颜色

Colors.vue

清除与禁用

States.vue

错误

请选择一个有效的日期

Error.vue

属性

属性类型默认值说明
classNamestring""Extra classes for the outer wrapper. Use `classNames` to reach the trigger, panel, grid or cells.
classNamesKunDatePickerClassNames—Per-part class hooks (root / trigger / popup / grid / cell), merged after the component's own classes so yours wins the conflict — KunUI's own `rounded-kun-*` / `shadow-kun-*` / `z-kun-*` scales included. There is no `popupWidth`: the panel is always content-width with a 260px floor and never follows the trigger, so a short pill still gets a full calendar.
clearablebooleantrueShow an X in the trigger that clears the value. The X is pointer-only; from the keyboard, Backspace or Delete on the focused trigger clears it, and the panel's Clear button is the path for a screen reader.
colorKunUIColor"default"Focus-ring accent (the resting border/text stay neutral).
darkBorderbooleantrueLegacy dark-mode border toggle. 已废弃:No-op since 0.18.0. Every neutral border now resolves to the unified `--color-kun-border` token (the `border-kun` utility), which already flips light↔dark — so the old light-translucent / dark-solid split this prop toggled is gone. Safe to remove from call sites.
disabledbooleanfalse
errorstring""
formatstring'yyyy-MM-dd' | 'yyyy-MM' | 'yyyy'date-fns pattern for the text shown in the trigger, formatted in the picker's locale, so `MMMM` or `EEEE` give month and weekday names in that language. Defaults follow `precision`.
fullWidthbooleantrueStretch the control to its container. Turn it off in a filter bar, so the trigger shrinks to its own content. The wrapper shrink-wraps its widest child, so a long `label` or `error` widens it too — a filter pill wants neither.
iconstring""Icon rendered before the value in the trigger — a filter glyph for a filter bar, a category glyph for a field. The trailing calendar glyph is the disclosure indicator and stays either way. Must be one of the bundled icon names.
isDateDisabled((date: Date) => boolean)—Extra per-cell veto. Called with the FIRST instant of the period a cell covers — the day itself, the 1st of the month, or January 1st — so one predicate works at every precision.
labelstring""
localestringthe active KunUI locale's dateLocale, else its codeLanguage of the calendar GRID — weekday and month names, and the full date each day cell announces. Only `'zh-CN'` / `'ja'` / `'en'` are bundled; for anything else put a date-fns locale object on your `KunLocale.dateLocale` instead of passing a tag here.
maxDatestring | Date—
minDatestring | Date—
modeKunDatePickerMode"single"
modelValuestring | [string | null, string | null] | null""
monthsstring[]—Full month names. Also the source for the month grid's labels, where the abbreviated form is used unless this overrides it.
placeholderstringlocale datePicker.placeholderDay | datePicker.placeholderMonth | datePicker.placeholderYearTrigger text when nothing is selected. Defaults follow `precision`.
precisionKunDatePickerPrecision"day"What one click commits: a day, a whole month, or a whole year. The panel opens on the matching grid and the value is the first instant of the period, so `month` emits `'2026-09'` and `year` emits `'2026'`.
roundedKunUIRounded—Corner radius. When unset it follows the nearest KunUIConfigProvider's `rounded`. `full` means a pill, which is only defined for the single-line trigger — the floating panel falls back to `lg`, because `9999px` on an n-row panel is clamped by the browser to half its short side. Every other bucket applies to both.
sizeKunUISize"md"
valueFormatstring'yyyy-MM-dd' | 'yyyy-MM' | 'yyyy'date-fns pattern for the emitted v-model string. Defaults follow `precision`; keep it ISO-shaped so the value parses back.
weekdaysstring[]—Short weekday headers, Sunday first. Overrides the locale's, index by index — a shorter array leaves the rest as the locale had them.

事件

事件回调参数
update:modelValuevalue: string | [string | null, string | null] | null