DatePicker (日期选择器)
日期 / 日期范围选择器(基于 date-fns),支持格式化、最小/最大值与禁用日期。
基础用法
请选择日期
Value: —
Basic.vue
日期范围
请选择日期
起始:—
结束:—
Range.vue
选择粒度(日 / 月 / 年)
2026-09-05
2026-09-05
2026-09
2026-09
2026
2026
2018 - 2024
2018 → 2024
Precision.vue
格式与禁用日期
请选择日期
Value: —
已禁用过去的日期、周六与周日
Format.vue
颜色
请选择日期
请选择日期
请选择日期
Colors.vue
清除与禁用
2026-06-14
2026-06-14
States.vue
错误
请选择日期
请选择一个有效的日期
Error.vue
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className | string | "" | Extra classes for the outer wrapper. Use `classNames` to reach the trigger, panel, grid or cells. |
| classNames | KunDatePickerClassNames | — | 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. |
| clearable | boolean | true | Show 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. |
| color | KunUIColor | "default" | Focus-ring accent (the resting border/text stay neutral). |
| darkBorder | boolean | true | Legacy 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. |
| disabled | boolean | false | |
| error | string | "" | |
| format | string | '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`. |
| fullWidth | boolean | true | Stretch 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. |
| icon | string | "" | 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. |
| label | string | "" | |
| locale | string | the active KunUI locale's dateLocale, else its code | Language 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. |
| maxDate | string | Date | — | |
| minDate | string | Date | — | |
| mode | KunDatePickerMode | "single" | |
| modelValue | string | [string | null, string | null] | null | "" | |
| months | string[] | — | Full month names. Also the source for the month grid's labels, where the abbreviated form is used unless this overrides it. |
| placeholder | string | locale datePicker.placeholderDay | datePicker.placeholderMonth | datePicker.placeholderYear | Trigger text when nothing is selected. Defaults follow `precision`. |
| precision | KunDatePickerPrecision | "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'`. |
| rounded | KunUIRounded | — | 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. |
| size | KunUISize | "md" | |
| valueFormat | string | '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. |
| weekdays | string[] | — | Short weekday headers, Sunday first. Overrides the locale's, index by index — a shorter array leaves the rest as the locale had them. |
事件
| 事件 | 回调参数 |
|---|---|
| update:modelValue | value: string | [string | null, string | null] | null |