DatePickerPane 日期选择器面板 ^(beta)
DatePickerPanel是DatePicker的核心组件。
选择某一天
以”日“为基本单位，基础的日期选择控件
2026 October
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
27 | 28 | 29 | 30 | 1 | 2 | 3 |
4 | 5 | 6 | 7 | 8 | 9 | 10 |
11 | 12 | 13 | 14 | 15 | 16 | 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 |
25 | 26 | 27 | 28 | 29 | 30 | 31 |
1 | 2 | 3 | 4 | 5 | 6 | 7 |
"use client";import { useEffect, useRef, useState, type ReactNode } from "react";import { ElCard } from "@/components/element-plus/card";import { ElConfigProvider, en } from "@/components/element-plus/config-provider";import { ElDatePickerPanel } from "@/components/element-plus/date-picker-panel";import { ElDivider } from "@/components/element-plus/divider";import { ElSelect } from "@/components/element-plus/select";import { ElSwitch } from "@/components/element-plus/switch";import type { DateModelValue, DatePickerType,} from "@/components/element-plus/date-picker-panel";const DATE_PICKER_TYPES: DatePickerType[] = [ "year", "years", "month", "months", "date", "dates", "week", "datetime", "datetimerange", "daterange", "monthrange", "quarterrange", "yearrange",];function DatePickerPanelBasicDemo() { const [value, setValue] = useState<DateModelValue>(null); return ( <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={value} onChange={setValue} /> </div> );}function DatePickerPanelAllTypesDemo() { const [type, setType] = useState<DatePickerType>("date"); const [date, setDate] = useState<DateModelValue>(null); return ( <div> <div style={{ display: "flex", gap: "16px" }}> <div style={{ display: "flex", flexDirection: "column", flexBasis: 150, gap: 4, }} > <span>Type:</span> <ElSelect value={type} options={DATE_PICKER_TYPES.map((item) => ({ value: item, label: item, }))} onChange={(next) => { setType(next as DatePickerType); setDate(null); }} /> </div> </div> <ElDivider /> <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={date} onChange={setDate} type={type} /> </div> </div> );}function DatePickerPanelBorderDemo() { const [value, setValue] = useState<DateModelValue>(null); const [isNarrow, setIsNarrow] = useState(true); const containerRef = useRef<HTMLDivElement>(null); useEffect(() => { const container = containerRef.current; if (!container) return; const observer = new ResizeObserver(([entry]) => { setIsNarrow(entry.contentRect.width < 815); }); observer.observe(container); return () => observer.disconnect(); }, []); return ( <div ref={containerRef}> <div style={{ textAlign: "center" }}>No border:</div> <ElDivider /> <div style={{ display: "flex", flexWrap: "wrap", gap: 16, justifyContent: "center", }} > <div style={{ padding: 20 }}> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </div> <ElDivider style={{ height: "auto" }} direction={isNarrow ? "horizontal" : "vertical"} /> <ElCard> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </ElCard> </div> </div> );}function DatePickerPanelDisabledDemo() { const [value, setValue] = useState<DateModelValue>(null); const [disabled, setDisabled] = useState(true); return ( <div style={{ display: "flex", flexDirection: "column", alignItems: "center", }} > <ElSwitch checked={disabled} onCheckedChange={setDisabled} activeText="Disabled" inactiveText="Enabled" /> <ElDatePickerPanel value={value} onChange={setValue} disabled={disabled} /> </div> );}function withEn(Component: () => ReactNode) { return function Demo() { return ( <ElConfigProvider locale={en}> <Component /> </ElConfigProvider> ); };}export const DatePickerPanelBasic = withEn(DatePickerPanelBasicDemo);export const DatePickerPanelAllTypes = withEn(DatePickerPanelAllTypesDemo);export const DatePickerPanelBorder = withEn(DatePickerPanelBorderDemo);export const DatePickerPanelDisabled = withEn(DatePickerPanelDisabledDemo);边框
默认情况下，边框是默认的，如果你不想要边框请参考示例。例如，DatePicker不继承border。
No border:
2026 October
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
27 | 28 | 29 | 30 | 1 | 2 | 3 |
4 | 5 | 6 | 7 | 8 | 9 | 10 |
11 | 12 | 13 | 14 | 15 | 16 | 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 |
25 | 26 | 27 | 28 | 29 | 30 | 31 |
1 | 2 | 3 | 4 | 5 | 6 | 7 |
2026 October
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
27 | 28 | 29 | 30 | 1 | 2 | 3 |
4 | 5 | 6 | 7 | 8 | 9 | 10 |
11 | 12 | 13 | 14 | 15 | 16 | 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 |
25 | 26 | 27 | 28 | 29 | 30 | 31 |
1 | 2 | 3 | 4 | 5 | 6 | 7 |
"use client";import { useEffect, useRef, useState, type ReactNode } from "react";import { ElCard } from "@/components/element-plus/card";import { ElConfigProvider, en } from "@/components/element-plus/config-provider";import { ElDatePickerPanel } from "@/components/element-plus/date-picker-panel";import { ElDivider } from "@/components/element-plus/divider";import { ElSelect } from "@/components/element-plus/select";import { ElSwitch } from "@/components/element-plus/switch";import type { DateModelValue, DatePickerType,} from "@/components/element-plus/date-picker-panel";const DATE_PICKER_TYPES: DatePickerType[] = [ "year", "years", "month", "months", "date", "dates", "week", "datetime", "datetimerange", "daterange", "monthrange", "quarterrange", "yearrange",];function DatePickerPanelBasicDemo() { const [value, setValue] = useState<DateModelValue>(null); return ( <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={value} onChange={setValue} /> </div> );}function DatePickerPanelAllTypesDemo() { const [type, setType] = useState<DatePickerType>("date"); const [date, setDate] = useState<DateModelValue>(null); return ( <div> <div style={{ display: "flex", gap: "16px" }}> <div style={{ display: "flex", flexDirection: "column", flexBasis: 150, gap: 4, }} > <span>Type:</span> <ElSelect value={type} options={DATE_PICKER_TYPES.map((item) => ({ value: item, label: item, }))} onChange={(next) => { setType(next as DatePickerType); setDate(null); }} /> </div> </div> <ElDivider /> <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={date} onChange={setDate} type={type} /> </div> </div> );}function DatePickerPanelBorderDemo() { const [value, setValue] = useState<DateModelValue>(null); const [isNarrow, setIsNarrow] = useState(true); const containerRef = useRef<HTMLDivElement>(null); useEffect(() => { const container = containerRef.current; if (!container) return; const observer = new ResizeObserver(([entry]) => { setIsNarrow(entry.contentRect.width < 815); }); observer.observe(container); return () => observer.disconnect(); }, []); return ( <div ref={containerRef}> <div style={{ textAlign: "center" }}>No border:</div> <ElDivider /> <div style={{ display: "flex", flexWrap: "wrap", gap: 16, justifyContent: "center", }} > <div style={{ padding: 20 }}> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </div> <ElDivider style={{ height: "auto" }} direction={isNarrow ? "horizontal" : "vertical"} /> <ElCard> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </ElCard> </div> </div> );}function DatePickerPanelDisabledDemo() { const [value, setValue] = useState<DateModelValue>(null); const [disabled, setDisabled] = useState(true); return ( <div style={{ display: "flex", flexDirection: "column", alignItems: "center", }} > <ElSwitch checked={disabled} onCheckedChange={setDisabled} activeText="Disabled" inactiveText="Enabled" /> <ElDatePickerPanel value={value} onChange={setValue} disabled={disabled} /> </div> );}function withEn(Component: () => ReactNode) { return function Demo() { return ( <ElConfigProvider locale={en}> <Component /> </ElConfigProvider> ); };}export const DatePickerPanelBasic = withEn(DatePickerPanelBasicDemo);export const DatePickerPanelAllTypes = withEn(DatePickerPanelAllTypesDemo);export const DatePickerPanelBorder = withEn(DatePickerPanelBorderDemo);export const DatePickerPanelDisabled = withEn(DatePickerPanelDisabledDemo);禁用
"禁用"属性决定日期选择器是否完全禁用。
EnabledDisabled
2026 October
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
27 | 28 | 29 | 30 | 1 | 2 | 3 |
4 | 5 | 6 | 7 | 8 | 9 | 10 |
11 | 12 | 13 | 14 | 15 | 16 | 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 |
25 | 26 | 27 | 28 | 29 | 30 | 31 |
1 | 2 | 3 | 4 | 5 | 6 | 7 |
"use client";import { useEffect, useRef, useState, type ReactNode } from "react";import { ElCard } from "@/components/element-plus/card";import { ElConfigProvider, en } from "@/components/element-plus/config-provider";import { ElDatePickerPanel } from "@/components/element-plus/date-picker-panel";import { ElDivider } from "@/components/element-plus/divider";import { ElSelect } from "@/components/element-plus/select";import { ElSwitch } from "@/components/element-plus/switch";import type { DateModelValue, DatePickerType,} from "@/components/element-plus/date-picker-panel";const DATE_PICKER_TYPES: DatePickerType[] = [ "year", "years", "month", "months", "date", "dates", "week", "datetime", "datetimerange", "daterange", "monthrange", "quarterrange", "yearrange",];function DatePickerPanelBasicDemo() { const [value, setValue] = useState<DateModelValue>(null); return ( <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={value} onChange={setValue} /> </div> );}function DatePickerPanelAllTypesDemo() { const [type, setType] = useState<DatePickerType>("date"); const [date, setDate] = useState<DateModelValue>(null); return ( <div> <div style={{ display: "flex", gap: "16px" }}> <div style={{ display: "flex", flexDirection: "column", flexBasis: 150, gap: 4, }} > <span>Type:</span> <ElSelect value={type} options={DATE_PICKER_TYPES.map((item) => ({ value: item, label: item, }))} onChange={(next) => { setType(next as DatePickerType); setDate(null); }} /> </div> </div> <ElDivider /> <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={date} onChange={setDate} type={type} /> </div> </div> );}function DatePickerPanelBorderDemo() { const [value, setValue] = useState<DateModelValue>(null); const [isNarrow, setIsNarrow] = useState(true); const containerRef = useRef<HTMLDivElement>(null); useEffect(() => { const container = containerRef.current; if (!container) return; const observer = new ResizeObserver(([entry]) => { setIsNarrow(entry.contentRect.width < 815); }); observer.observe(container); return () => observer.disconnect(); }, []); return ( <div ref={containerRef}> <div style={{ textAlign: "center" }}>No border:</div> <ElDivider /> <div style={{ display: "flex", flexWrap: "wrap", gap: 16, justifyContent: "center", }} > <div style={{ padding: 20 }}> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </div> <ElDivider style={{ height: "auto" }} direction={isNarrow ? "horizontal" : "vertical"} /> <ElCard> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </ElCard> </div> </div> );}function DatePickerPanelDisabledDemo() { const [value, setValue] = useState<DateModelValue>(null); const [disabled, setDisabled] = useState(true); return ( <div style={{ display: "flex", flexDirection: "column", alignItems: "center", }} > <ElSwitch checked={disabled} onCheckedChange={setDisabled} activeText="Disabled" inactiveText="Enabled" /> <ElDatePickerPanel value={value} onChange={setValue} disabled={disabled} /> </div> );}function withEn(Component: () => ReactNode) { return function Demo() { return ( <ElConfigProvider locale={en}> <Component /> </ElConfigProvider> ); };}export const DatePickerPanelBasic = withEn(DatePickerPanelBasicDemo);export const DatePickerPanelAllTypes = withEn(DatePickerPanelAllTypesDemo);export const DatePickerPanelBorder = withEn(DatePickerPanelBorderDemo);export const DatePickerPanelDisabled = withEn(DatePickerPanelDisabledDemo);展示类型
时间面板的类型由 type 属性指定。
Type:
date
2026 October
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
27 | 28 | 29 | 30 | 1 | 2 | 3 |
4 | 5 | 6 | 7 | 8 | 9 | 10 |
11 | 12 | 13 | 14 | 15 | 16 | 17 |
18 | 19 | 20 | 21 | 22 | 23 | 24 |
25 | 26 | 27 | 28 | 29 | 30 | 31 |
1 | 2 | 3 | 4 | 5 | 6 | 7 |
"use client";import { useEffect, useRef, useState, type ReactNode } from "react";import { ElCard } from "@/components/element-plus/card";import { ElConfigProvider, en } from "@/components/element-plus/config-provider";import { ElDatePickerPanel } from "@/components/element-plus/date-picker-panel";import { ElDivider } from "@/components/element-plus/divider";import { ElSelect } from "@/components/element-plus/select";import { ElSwitch } from "@/components/element-plus/switch";import type { DateModelValue, DatePickerType,} from "@/components/element-plus/date-picker-panel";const DATE_PICKER_TYPES: DatePickerType[] = [ "year", "years", "month", "months", "date", "dates", "week", "datetime", "datetimerange", "daterange", "monthrange", "quarterrange", "yearrange",];function DatePickerPanelBasicDemo() { const [value, setValue] = useState<DateModelValue>(null); return ( <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={value} onChange={setValue} /> </div> );}function DatePickerPanelAllTypesDemo() { const [type, setType] = useState<DatePickerType>("date"); const [date, setDate] = useState<DateModelValue>(null); return ( <div> <div style={{ display: "flex", gap: "16px" }}> <div style={{ display: "flex", flexDirection: "column", flexBasis: 150, gap: 4, }} > <span>Type:</span> <ElSelect value={type} options={DATE_PICKER_TYPES.map((item) => ({ value: item, label: item, }))} onChange={(next) => { setType(next as DatePickerType); setDate(null); }} /> </div> </div> <ElDivider /> <div style={{ display: "flex", justifyContent: "center" }}> <ElDatePickerPanel value={date} onChange={setDate} type={type} /> </div> </div> );}function DatePickerPanelBorderDemo() { const [value, setValue] = useState<DateModelValue>(null); const [isNarrow, setIsNarrow] = useState(true); const containerRef = useRef<HTMLDivElement>(null); useEffect(() => { const container = containerRef.current; if (!container) return; const observer = new ResizeObserver(([entry]) => { setIsNarrow(entry.contentRect.width < 815); }); observer.observe(container); return () => observer.disconnect(); }, []); return ( <div ref={containerRef}> <div style={{ textAlign: "center" }}>No border:</div> <ElDivider /> <div style={{ display: "flex", flexWrap: "wrap", gap: 16, justifyContent: "center", }} > <div style={{ padding: 20 }}> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </div> <ElDivider style={{ height: "auto" }} direction={isNarrow ? "horizontal" : "vertical"} /> <ElCard> <ElDatePickerPanel value={value} onChange={setValue} border={false} /> </ElCard> </div> </div> );}function DatePickerPanelDisabledDemo() { const [value, setValue] = useState<DateModelValue>(null); const [disabled, setDisabled] = useState(true); return ( <div style={{ display: "flex", flexDirection: "column", alignItems: "center", }} > <ElSwitch checked={disabled} onCheckedChange={setDisabled} activeText="Disabled" inactiveText="Enabled" /> <ElDatePickerPanel value={value} onChange={setValue} disabled={disabled} /> </div> );}function withEn(Component: () => ReactNode) { return function Demo() { return ( <ElConfigProvider locale={en}> <Component /> </ElConfigProvider> ); };}export const DatePickerPanelBasic = withEn(DatePickerPanelBasicDemo);export const DatePickerPanelAllTypes = withEn(DatePickerPanelAllTypesDemo);export const DatePickerPanelBorder = withEn(DatePickerPanelBorderDemo);export const DatePickerPanelDisabled = withEn(DatePickerPanelDisabledDemo);本地化
由于 Element Plus 的默认语言为英语，如果你需要设置其它的语言，请参考国际化文档。
要注意的是：日期相关的文字（月份，每一周的第一天等等）也都进行了本地化配置。
DatePickerPanel API
DatePickerPanel 是 DatePicker 的核心组件。
Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 绑定值，对应官方 model-value；范围选择器应为长度为 2 的数组 | number / string / Date / array | '' |
| border | 是否显示边框 | boolean | true |
| disabled | 是否禁用 | boolean | false |
| clearable | 是否显示清空按钮 | boolean | true |
| editable | 输入框是否可编辑 | boolean | true |
| type | 选择器类型 | enum | date |
| defaultValue | 日历默认显示日期 | object | — |
| defaultTime | 选择范围时使用的时间值 | object | — |
| valueFormat | 绑定值格式，不传时绑定值为 Date | string | — |
| dateFormat | 面板中日期显示格式 | string | YYYY-MM-DD |
| timeFormat | 面板中时间显示格式 | string | HH:mm:ss |
| unlinkPanels | 范围选择时左右面板不联动 | boolean | false |
| singlePanel | 范围选择时只显示一个面板 | boolean | false |
| disabledDate | 判断日期是否禁用 | Function | — |
| shortcuts | 快捷选项 | array | [] |
| cellClassName | 自定义单元格类名 | Function | — |
| showFooter | 是否显示底栏，仅 dates / months / years / datetime / datetimerange | boolean | false |
| showConfirm | 是否显示确认按钮 | boolean | false |
| showWeekNumber | 是否显示周数 | boolean | false |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| onChange | 绑定值变化，对应官方 v-model | Function |
| onCalendarChange | 日历选中日期变化时触发，仅范围模式 | Function |
| onPanelChange | 点击导航按钮时触发 | Function |
| onClear | 点击清空按钮时触发 | Function |
Slots
| 插槽名 | 说明 |
|---|---|
| renderCell | 自定义单元格内容，对应官方 default 插槽 |
| prevMonthIcon / nextMonthIcon | 上 / 下个月图标 |
| prevYearIcon / nextYearIcon | 上 / 下一年图标 |
Exposes
| 名称 | 说明 | 类型 |
|---|---|---|
| focus | 聚焦面板 | Function |
| isValidValue | 判断值是否合法 | Function |
| parseUserInput | 解析用户输入 | Function |
| handleClear | 清空面板值 | Function |