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.
classNamesKunDatePickerClassNamesPer-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.
clearablebooleantrue
colorKunUIColor"default"Focus-ring accent (the resting border/text stay neutral).
darkBorderbooleantrueLegacy dark-mode border toggle.
disabledbooleanfalse
errorstring""
formatstring'yyyy-MM-dd' | 'yyyy-MM' | 'yyyy'date-fns pattern for the text shown in the trigger. 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""
localestring
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.
placeholderstring'请选择日期' | '请选择月份' | '请选择年份'Trigger 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'`.
roundedKunUIRoundedCorner 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[]

事件

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