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 | |
| color | KunUIColor | "default" | Focus-ring accent (the resting border/text stay neutral). |
| darkBorder | boolean | true | Legacy dark-mode border toggle. |
| disabled | boolean | false | |
| error | string | "" | |
| format | string | 'yyyy-MM-dd' | 'yyyy-MM' | 'yyyy' | date-fns pattern for the text shown in the trigger. 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 | — | |
| 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 | '请选择日期' | '请选择月份' | '请选择年份' | 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[] | — |
事件
| 事件 | 回调参数 |
|---|---|
| update:modelValue | value: string | [string | null, string | null] | null |