DatePicker 日期选择器

新粗野主义风格的日期选择器组件族，基于 v-calendar 与 reka-ui Popover 构建。提供 7 个可直接使用的选择器，以及可独立组合的日期面板和页脚。弹出式选择器共享触发器样式变体，TimePicker 使用独立的时间下拉框布局。

预览

Preview

DatePicker 单日期选择

未选择

DatePickerRange 日期范围

DateTimePicker 日期时间

TimePicker 纯时间

时

:

分

:

秒

WeekPicker 周选择

MonthPicker 月份

YearPicker 年份

程序化控制（通过 ref 打开面板）

通过 pickerRef.open 可在外部按钮中打开或关闭日期面板。

安装

pnpm dlx brutx-vue@latest add date-picker

需要额外安装依赖：

pnpm add v-calendar

用法

DatePicker 单日期选择

<script setup>
import { ref } from 'vue'
import { DatePicker } from 'brutx-ui-vue/date-picker'

const date = ref(null)
</script>

<template>
    <DatePicker v-model="date" placeholder="选择日期" />
</template>

带快捷选项

<script setup>
import { ref } from 'vue'
import { DatePicker } from 'brutx-ui-vue/date-picker'

const date = ref(null)

const shortcuts = [
    { label: '今天', value: () => new Date() },
    { label: '明天', value: () => {
        const d = new Date()
        d.setDate(d.getDate() + 1)
        return d
    }},
    { label: '一周后', value: () => {
        const d = new Date()
        d.setDate(d.getDate() + 7)
        return d
    }},
]
</script>

<template>
    <DatePicker v-model="date" :shortcuts="shortcuts" :clearable="true" />
</template>

DatePickerRange 日期范围选择

<script setup>
import { ref } from 'vue'
import { DatePickerRange } from 'brutx-ui-vue/date-picker'

const dateRange = ref(null)
</script>

<template>
    <DatePickerRange
        v-model="dateRange"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
    />
</template>

DateTimePicker 日期时间选择

<script setup>
import { ref } from 'vue'
import { DateTimePicker } from 'brutx-ui-vue/date-picker'

const dateTime = ref(null)
</script>

<template>
    <DateTimePicker
        v-model="dateTime"
        placeholder="选择日期时间"
        :show-seconds="true"
    />
</template>

DateTimePicker 支持时间步进配置：

<template>
    <DateTimePicker
        v-model="dateTime"
        :time-step="{ hour: 2, minute: 15, second: 10 }"
    />
</template>

TimePicker 纯时间选择

TimePicker 基于 Select 组件组合小时、分钟和可选的秒下拉框，使用 disabled、showSeconds、timeStep、embedded 和 ariaLabel 配置。弹出日期选择器的 open、readonly、clearable、size、variant、shortcuts、minDate、maxDate 和 displayFormat 不属于其公开属性。

<script setup>
import { ref } from 'vue'
import { TimePicker } from 'brutx-ui-vue/date-picker'

const time = ref(null)
</script>

<template>
    <TimePicker v-model="time" :show-seconds="true" />
</template>

WeekPicker 周选择

<script setup>
import { ref } from 'vue'
import { WeekPicker } from 'brutx-ui-vue/date-picker'

const week = ref(null)
</script>

<template>
    <WeekPicker v-model="week" :week-starts-on="1" placeholder="选择周" />
</template>

weekStartsOn：0 = 周日起始，1 = 周一起始（默认）。选中任意日期后，modelValue 会自动对齐到当周起始日，并整周高亮。

注意：weekStartsOn 默认值（1，周一起始）不随 useLocale 区域设置自动推导，是设计限制。ISO 8601 与中文地区习惯均为周一起始，若业务需要周日起始（如 en-US 习惯），请显式传入 weekStartsOn: 0。

MonthPicker 月份选择

<script setup>
import { ref } from 'vue'
import { MonthPicker } from 'brutx-ui-vue/date-picker'

const month = ref(null)
</script>

<template>
    <MonthPicker v-model="month" placeholder="选择月份" />
</template>

YearPicker 年份选择

<script setup>
import { ref } from 'vue'
import { YearPicker } from 'brutx-ui-vue/date-picker'

const year = ref(null)
</script>

<template>
    <YearPicker v-model="year" placeholder="选择年份" />
</template>

禁用与只读

<template>
    <DatePicker v-model="date" disabled />
    <DatePicker v-model="date" readonly />
</template>

日期范围限制

<script setup>
import { ref } from 'vue'
import { DatePicker } from 'brutx-ui-vue/date-picker'

const date = ref(null)
const minDate = new Date(2026, 0, 1)
const maxDate = new Date(2026, 11, 31)
</script>

<template>
    <DatePicker v-model="date" :min-date="minDate" :max-date="maxDate" />
</template>

自定义显示格式

支持 YYYY、YY、MM、DD、HH、mm、ss、WW（ISO 周数）token：

<template>
    <DatePicker v-model="date" display-format="YYYY/MM/DD" />
    <DateTimePicker v-model="dt" display-format="YYYY-MM-DD HH:mm:ss" />
    <WeekPicker v-model="week" display-format="YYYY-WW" />
    <YearPicker v-model="year" display-format="YY" />
</template>

displayFormat 只影响输入框中的展示字符串，不改变 modelValue、minDate、maxDate、shortcuts 和事件参数的类型；这些公开 API 始终使用 Date、[Date, Date] 或 null。如需跨时区一致的日期时间语义，请在业务层传入已经标准化的 Date、时间戳或带时区偏移的完整 ISO 字符串后再转换为 Date，不要依赖浏览器对任意日期字符串的隐式解析。

子组件

组件	用途
DatePicker	单日期选择
DatePickerRange	日期范围选择（起止日期）
DateTimePicker	日期 + 时间选择
TimePicker	纯时间选择（时/分/秒）
WeekPicker	周选择（整周高亮）
MonthPicker	月份选择
YearPicker	年份选择
DatePickerPanel	可独立嵌入的单日期面板
DatePickerRangePanel	可独立嵌入的日期范围面板
DateTimePickerPanel	组合日历与 TimePicker 的日期时间面板
WeekPickerPanel	将选中日期对齐到周起始日的周面板
MonthPickerPanel	按年份切换视图的月份网格
YearPickerPanel	支持自定义每页年份数量的年份网格
DatePickerPanelFooter	提供清除、确认按钮及对应事件的面板页脚

数据类型

// 单日期快捷选项
interface DatePickerShortcut {
    label: string
    value: Date | (() => Date)
}

// 起止顺序固定的日期范围
type DateRange = readonly [Date, Date]

// 日期范围快捷选项
interface DatePickerRangeShortcut {
    label: string
    value: DateRange | (() => DateRange)
}

组合式函数

DatePicker 等组件的弹出面板触发、显示格式化、清除、确认等逻辑已抽取为独立的 useDatePicker 组合式函数，可在需要构建完全自定义触发器或日历面板时单独使用。它负责管理面板开关状态、显示值与 modelValue 的同步，并通过传入的 emit 触发 open / close / change / update:modelValue 事件。

import { useDatePicker } from 'brutx-ui-vue/useDatePicker'
import type { UseDatePickerOptions } from 'brutx-ui-vue/useDatePicker'

const props = defineProps<{ modelValue?: Date | null }>()

const emit = defineEmits<{
    'update:modelValue': [value: Date | null]
    'change': [value: Date | null]
    'open': []
    'close': []
}>()

const {
    open,                  // 面板是否打开
    displayValue,          // 面板内当前显示的值（未确认前的临时值）
    formattedDisplay,      // 格式化后的展示字符串
    handlePanelUpdate,     // 面板值更新回调
    handlePanelConfirm,    // 面板确认回调
    handlePanelClear,      // 面板清除回调
    handleClearClick,      // 触发器清除按钮点击回调
    handleTriggerKeydown,  // 触发器键盘事件回调
} = useDatePicker({
    modelValue: () => props.modelValue ?? null,
    displayFormat: 'YYYY-MM-DD',
    disabled: false,
    readonly: false,
    emit,
})

UseDatePickerOptions

属性	类型	默认值	说明
modelValue	MaybeRefOrGetter<Date | null>	null	当前选中日期（支持 v-model）
displayFormat	MaybeRefOrGetter<string>	'YYYY-MM-DD'	显示格式（支持 YYYY、YY、MM、DD、HH、mm、ss、WW token）
disabled	MaybeRefOrGetter<boolean>	false	是否禁用
readonly	MaybeRefOrGetter<boolean>	false	阻止内部打开面板
openProp	MaybeRefOrGetter<boolean | undefined>	undefined	受控面板开关；省略时使用内部状态
emitUpdateOpen	(value: boolean) => void	—	请求设置面板开关时调用，配合 openProp 同步受控状态
emit	DatePickerEmit	—	触发事件的函数（必填，类型与组件 emits 一致）

返回值

属性	类型	说明
open	Ref<boolean>	面板是否打开
displayValue	Readonly<Ref<Date | null>>	面板内当前显示的值，对调用方只读
formattedDisplay	ComputedRef<string>	按 displayFormat 格式化后的字符串
handlePanelUpdate(value)	(value: Date | null) => void	面板值更新时调用，同步 displayValue 并触发 update:modelValue
handlePanelConfirm(value)	(value: Date | null) => void	面板确认时调用，触发 update:modelValue / change 并关闭面板
handlePanelClear()	() => void	面板清除时调用，触发 update:modelValue(null) / change(null)
handleClearClick(event)	(event: Event) => void	触发器清除按钮回调，阻止事件冒泡并清除值
handleTriggerKeydown(event)	(event: KeyboardEvent) => void	禁用或只读时阻止 Enter / Space 的默认操作；正常打开行为由触发原语处理

提示：emit 必须符合 DatePickerEmit 签名。请在 setup() 或受管理的 Vue effect scope 中调用，以便清理内部响应式监听。

程序化控制

DatePicker、DateTimePicker、WeekPicker、MonthPicker、YearPicker 通过 defineExpose 暴露 open 响应式引用，允许父组件程序化打开或关闭日期面板。open 是与内部 Popover 双向绑定的可读写引用；受控模式下写入会发出 update:open，由父组件更新 open 后生效。readonly 会阻止组件内部发起打开请求。

注意：DatePickerRange 和 TimePicker 未暴露 open。DatePicker、DateTimePicker、WeekPicker、MonthPicker、YearPicker 同时支持 v-model:open 双向绑定，推荐使用 v-model:open 替代直接操作 ref。

<script setup>
import { ref } from 'vue'
import { DatePicker } from 'brutx-ui-vue/date-picker'
import { Button } from 'brutx-ui-vue/button'

const pickerRef = ref()
const date = ref(null)
</script>

<template>
    <DatePicker ref="pickerRef" v-model="date" />

    <Button @click="pickerRef && (pickerRef.open = true)">打开面板</Button>
    <Button @click="pickerRef && (pickerRef.open = false)">关闭面板</Button>
</template>

API 参考

DatePicker

DatePicker — 属性

名称	类型	默认值	说明
open	boolean | undefined	undefined 运行时回退:为 undefined 时使用组件内部开关状态，初始为关闭。	受控的面板开关状态，通过 v-model:open 接收组件发出的开关请求。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 运行时回退 为 undefined 时使用组件内部开关状态，初始为关闭。 组件在说明的运行条件下采用此回退值。 来源 DatePicker.vue:19 packages/ui/src/components/date-picker/DatePicker.vue
size	"default" | "lg" | "sm" | undefined	"default"	控制日期触发按钮的高度、内边距及图标尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 "default" 来源 DatePicker.vue:20 packages/ui/src/components/date-picker/DatePicker.vue
variant	"default" | "error" | "success" | undefined	"default"	控制日期触发按钮的视觉状态，提供常规、错误和成功配色。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 "default" 来源 DatePicker.vue:21 packages/ui/src/components/date-picker/DatePicker.vue
modelValue 可空	Date | null | undefined	null	当前选中的单个日期，通过 v-model 绑定；null 表示尚未选择或已清除。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 null 来源 types.ts:26 packages/ui/src/components/date-picker/types.ts
placeholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.placeholder，简体中文文案为“请选择日期”。	没有可显示日期时呈现在触发按钮中的占位文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.placeholder，简体中文文案为“请选择日期”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:27 packages/ui/src/components/date-picker/types.ts
shortcuts	DatePickerShortcut[] | undefined	[] 按实例调用工厂函数	日期面板中的快捷选项；每项提供显示标签和 Date 值或返回 Date 的函数，选择后仍需遵守日期上下界。
详情 声明类型 DatePickerShortcut[] | undefined 关联类型 DatePickerShortcut 类型定义 — DatePickerShortcut export interface DatePickerShortcut { label: string value: Date | (() => Date) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 [] 来源 types.ts:28 packages/ui/src/components/date-picker/types.ts
displayFormat	string | undefined	"YYYY-MM-DD"	格式化触发器中显示的日期文本，支持 YYYY、YY、MM、DD、HH、mm、ss 和 WW；不改变绑定值的 Date 类型。WW 使用 ISO 周数，仅含周数而不含月日时，年份使用 ISO 周所属年份。
详情 声明类型 string | undefined 默认值详情 声明 'YYYY-MM-DD' 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 "YYYY-MM-DD" 来源 types.ts:6 packages/ui/src/components/date-picker/types.ts
minDate	Date | undefined	undefined	传给日历的最早可选日期；单日期快捷项按本地年月日比较，早于该日的快捷值会被忽略。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 来源 types.ts:7 packages/ui/src/components/date-picker/types.ts
maxDate	Date | undefined	undefined	传给日历的最晚可选日期；单日期快捷项按本地年月日比较，晚于该日的快捷值会被忽略。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 来源 types.ts:8 packages/ui/src/components/date-picker/types.ts
disabled	boolean | undefined	false	禁用触发按钮并隐藏触发器清除按钮；具有隐藏表单字段的选择器也会禁用该字段。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 false 来源 types.ts:9 packages/ui/src/components/date-picker/types.ts
readonly	boolean | undefined	false	阻止组件内部打开面板，并隐藏触发器清除按钮，保留当前日期的显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/date-picker/types.ts
clearable	boolean | undefined	false	显示面板底部的清除和确认操作；有值且未禁用、未只读时，也显示触发器清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 false 来源 types.ts:11 packages/ui/src/components/date-picker/types.ts
name	string | undefined	undefined	原生表单字段名。提供后创建隐藏字段，以 YYYY-MM-DD 提交日期；空值提交空字符串，禁用时不提交。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 来源 types.ts:14 packages/ui/src/components/date-picker/types.ts
id	string | undefined	undefined	传递给日期触发按钮的 HTML ID，可供 label 或辅助技术引用。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/date-picker/types.ts
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.placeholder，简体中文文案为“请选择日期”。	日期触发按钮和日期面板的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.placeholder，简体中文文案为“请选择日期”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:16 packages/ui/src/components/date-picker/types.ts
class	string | undefined	undefined	合并到日期触发按钮上的补充 CSS 类名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePicker.vue 解析值 undefined 来源 types.ts:17 packages/ui/src/components/date-picker/types.ts

DatePicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	面板选择、确认或清除日期时触发，用于更新 v-model；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 DatePicker.vue packages/ui/src/components/date-picker/DatePicker.vue
@open	[]	面板开关状态变为打开时触发，面板显示值同时从当前 modelValue 重新初始化。
详情 声明类型 [] 来源 DatePicker.vue packages/ui/src/components/date-picker/DatePicker.vue
@close	[]	面板开关状态变为关闭时触发。
详情 声明类型 [] 来源 DatePicker.vue packages/ui/src/components/date-picker/DatePicker.vue
@update:open	[value: boolean]	组件请求设置面板开关时触发，用于 v-model:open；受控模式下需由父组件更新 open 才会改变显示状态。
详情 声明类型 [value: boolean] 字面量 false true 来源 DatePicker.vue packages/ui/src/components/date-picker/DatePicker.vue
@change	[value: Date | null]	确认或清除时立即触发；其他关闭场景中，仅当面板显示值与当时 modelValue 的时间戳不同才触发。
详情 声明类型 [value: Date | null] 字面量 null 来源 DatePicker.vue packages/ui/src/components/date-picker/DatePicker.vue

DatePicker — 暴露成员

名称	签名或类型	说明
open	Ref<boolean, boolean>	可读写的面板开关引用；通过组件实例赋值可请求打开或关闭，readonly 会阻止打开请求。受控模式下写入会触发 update:open，仍需父组件更新 open。
详情 声明类型 Ref<boolean, boolean> 字面量 false true 来源 DatePicker.vue packages/ui/src/components/date-picker/DatePicker.vue

DatePickerPanel

DatePickerPanel — 属性

名称	类型	默认值	说明
modelValue 可空	Date | null | undefined	null	独立日期面板中的当前选中日期，通过 v-model 与调用方同步。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/DatePickerPanel.vue 解析值 null 来源 DatePickerPanel.vue:31 packages/ui/src/components/date-picker/DatePickerPanel.vue
minDate	Date | undefined	undefined	传给日历的最早可选日期；单日期快捷项按本地年月日比较，早于该日的快捷值会被忽略。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerPanel.vue 解析值 undefined 来源 DatePickerPanel.vue:32 packages/ui/src/components/date-picker/DatePickerPanel.vue
maxDate	Date | undefined	undefined	传给日历的最晚可选日期；单日期快捷项按本地年月日比较，晚于该日的快捷值会被忽略。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerPanel.vue 解析值 undefined 来源 DatePickerPanel.vue:33 packages/ui/src/components/date-picker/DatePickerPanel.vue
shortcuts	DatePickerShortcut[] | undefined	[] 按实例调用工厂函数	面板侧栏中的带标签日期快捷项，可提供 Date 或返回 Date 的函数；越过日期上下界的快捷值会被忽略。
详情 声明类型 DatePickerShortcut[] | undefined 关联类型 DatePickerShortcut 类型定义 — DatePickerShortcut export interface DatePickerShortcut { label: string value: Date | (() => Date) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/DatePickerPanel.vue 解析值 [] 来源 DatePickerPanel.vue:34 packages/ui/src/components/date-picker/DatePickerPanel.vue
clearable	boolean | undefined	true	显示包含清除和确认按钮的面板页脚；关闭时两个按钮一并隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/date-picker/DatePickerPanel.vue 解析值 true 来源 DatePickerPanel.vue:35 packages/ui/src/components/date-picker/DatePickerPanel.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.placeholder，简体中文文案为“请选择日期”。	日期面板 dialog 的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerPanel.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.placeholder，简体中文文案为“请选择日期”。 组件在说明的运行条件下采用此回退值。 来源 DatePickerPanel.vue:36 packages/ui/src/components/date-picker/DatePickerPanel.vue

DatePickerPanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	面板选中的日期变化时触发；清除操作会传入 null，父组件需接收更新以同步选中状态。
详情 声明类型 [value: Date | null] 字面量 null 来源 DatePickerPanel.vue packages/ui/src/components/date-picker/DatePickerPanel.vue
@clear	[]	点击面板清除按钮时触发，随后发出 update:modelValue(null)。
详情 声明类型 [] 来源 DatePickerPanel.vue packages/ui/src/components/date-picker/DatePickerPanel.vue
@confirm	[value: Date | null]	点击面板确认按钮时触发，携带当前 modelValue，包括未选择时的 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 DatePickerPanel.vue packages/ui/src/components/date-picker/DatePickerPanel.vue

DatePickerPanelFooter

DatePickerPanelFooter — 属性

名称	类型	默认值	说明
clearLabel	string | undefined	undefined 运行时回退:为 undefined、null 或空字符串时读取 datePicker.clear，简体中文文案为“清除”。	面板页脚清除按钮的文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerPanelFooter.vue 解析值 undefined 运行时回退 为 undefined、null 或空字符串时读取 datePicker.clear，简体中文文案为“清除”。 组件在说明的运行条件下采用此回退值。 来源 DatePickerPanelFooter.vue:9 packages/ui/src/components/date-picker/DatePickerPanelFooter.vue
confirmLabel	string | undefined	undefined 运行时回退:为 undefined、null 或空字符串时读取 datePicker.confirm，简体中文文案为“确认”。	面板页脚确认按钮的文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerPanelFooter.vue 解析值 undefined 运行时回退 为 undefined、null 或空字符串时读取 datePicker.confirm，简体中文文案为“确认”。 组件在说明的运行条件下采用此回退值。 来源 DatePickerPanelFooter.vue:10 packages/ui/src/components/date-picker/DatePickerPanelFooter.vue
disabled	boolean | undefined	false	同时禁用清除和确认按钮，可在异步处理期间阻止用户重复提交。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePickerPanelFooter.vue 解析值 false 来源 DatePickerPanelFooter.vue:12 packages/ui/src/components/date-picker/DatePickerPanelFooter.vue

DatePickerPanelFooter — 事件

名称	签名或类型	说明
@clear	[]	启用状态下点击清除按钮时触发，具体清除行为由调用方处理。
详情 声明类型 [] 来源 DatePickerPanelFooter.vue packages/ui/src/components/date-picker/DatePickerPanelFooter.vue
@confirm	[]	启用状态下点击确认按钮时触发，具体确认行为由调用方处理。
详情 声明类型 [] 来源 DatePickerPanelFooter.vue packages/ui/src/components/date-picker/DatePickerPanelFooter.vue

DatePickerRange

DatePickerRange — 属性

名称	类型	默认值	说明
size	"default" | "lg" | "sm" | undefined	"default"	控制日期触发按钮的高度、内边距及图标尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 "default" 来源 DatePickerRange.vue:18 packages/ui/src/components/date-picker/DatePickerRange.vue
variant	"default" | "error" | "success" | undefined	"default"	控制日期触发按钮的视觉状态，提供常规、错误和成功配色。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 "default" 来源 DatePickerRange.vue:19 packages/ui/src/components/date-picker/DatePickerRange.vue
modelValue 可空	DateRange | null | undefined	null	当前起止日期组成的只读元组，通过 v-model 绑定；null 表示空范围。
详情 声明类型 DateRange | null | undefined 字面量 null 关联类型 DateRange 类型定义 — DateRange export type DateRange = readonly [Date, Date] 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 null 来源 types.ts:48 packages/ui/src/components/date-picker/types.ts
startPlaceholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.startPlaceholder，简体中文文案为“开始日期”。	尚无完整日期范围时，在触发器起始日期位置显示的文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.startPlaceholder，简体中文文案为“开始日期”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:49 packages/ui/src/components/date-picker/types.ts
endPlaceholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.endPlaceholder，简体中文文案为“结束日期”。	尚无完整日期范围时，在触发器结束日期位置显示的文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.endPlaceholder，简体中文文案为“结束日期”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:50 packages/ui/src/components/date-picker/types.ts
separator	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.separator，简体中文文案为“至”。	显示在起止日期或对应占位文本之间的分隔文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.separator，简体中文文案为“至”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:51 packages/ui/src/components/date-picker/types.ts
shortcuts	DatePickerRangeShortcut[] | undefined	[] 按实例调用工厂函数	日期范围快捷项，包含标签和起止日期元组或返回该元组的函数；选中后直接更新范围。
详情 声明类型 DatePickerRangeShortcut[] | undefined 关联类型 DatePickerRangeShortcut 类型定义 — DatePickerRangeShortcut export interface DatePickerRangeShortcut { label: string value: DateRange | (() => DateRange) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 [] 来源 types.ts:52 packages/ui/src/components/date-picker/types.ts
displayFormat	string | undefined	"YYYY-MM-DD"	分别格式化起始和结束日期，支持 YYYY、YY、MM、DD、HH、mm、ss 和 WW；不改变 DateRange 绑定值。WW 遵循 ISO 周数与周所属年份规则。
详情 声明类型 string | undefined 默认值详情 声明 'YYYY-MM-DD' 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 "YYYY-MM-DD" 来源 types.ts:6 packages/ui/src/components/date-picker/types.ts
minDate	Date | undefined	undefined	传给范围日历的最早可选日期；快捷范围直接作为更新值发出，需由调用方保证快捷项符合边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 来源 types.ts:7 packages/ui/src/components/date-picker/types.ts
maxDate	Date | undefined	undefined	传给范围日历的最晚可选日期；快捷范围直接作为更新值发出，需由调用方保证快捷项符合边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 来源 types.ts:8 packages/ui/src/components/date-picker/types.ts
disabled	boolean | undefined	false	禁用范围选择触发按钮并隐藏触发器清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 false 来源 types.ts:9 packages/ui/src/components/date-picker/types.ts
readonly	boolean | undefined	false	阻止组件内部打开面板，并隐藏触发器清除按钮，保留当前日期的显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/date-picker/types.ts
clearable	boolean | undefined	false	显示面板底部的清除和确认操作；有值且未禁用、未只读时，也显示触发器清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 false 来源 types.ts:11 packages/ui/src/components/date-picker/types.ts
name	string | undefined	undefined	传给范围触发按钮的原生 name 属性；此组件不创建用于提交日期范围的隐藏字段。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 来源 types.ts:14 packages/ui/src/components/date-picker/types.ts
id	string | undefined	undefined	传递给日期触发按钮的 HTML ID，可供 label 或辅助技术引用。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/date-picker/types.ts
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.rangeLabel，简体中文文案为“日期范围”。	范围触发按钮和范围面板的无障碍名称，与占位文本独立配置。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.rangeLabel，简体中文文案为“日期范围”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:16 packages/ui/src/components/date-picker/types.ts
class	string | undefined	undefined	合并到日期触发按钮上的补充 CSS 类名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRange.vue 解析值 undefined 来源 types.ts:17 packages/ui/src/components/date-picker/types.ts

DatePickerRange — 事件

名称	签名或类型	说明
@update:modelValue	[value: DateRange | null]	日历选择、拖动范围、快捷选择、确认或清除时触发，用于更新 v-model；参数为起止日期元组或 null。
详情 声明类型 [value: DateRange | null] 字面量 null 关联类型 DateRange 类型定义 — DateRange export type DateRange = readonly [Date, Date] 来源 DatePickerRange.vue packages/ui/src/components/date-picker/DatePickerRange.vue
@open	[]	面板开关状态变为打开时触发，面板显示值同时从当前 modelValue 重新初始化。
详情 声明类型 [] 来源 DatePickerRange.vue packages/ui/src/components/date-picker/DatePickerRange.vue
@close	[]	面板开关状态变为关闭时触发。
详情 声明类型 [] 来源 DatePickerRange.vue packages/ui/src/components/date-picker/DatePickerRange.vue
@change	[value: DateRange | null]	确认或清除范围时立即触发；其他关闭场景中，仅当面板起始或结束日期与当时 modelValue 的时间戳不同才触发。
详情 声明类型 [value: DateRange | null] 字面量 null 关联类型 DateRange 类型定义 — DateRange export type DateRange = readonly [Date, Date] 来源 DatePickerRange.vue packages/ui/src/components/date-picker/DatePickerRange.vue

DatePickerRangePanel

DatePickerRangePanel — 属性

名称	类型	默认值	说明
modelValue 可空	DateRange | null | undefined	null	独立范围面板中的起止日期只读元组，通过 v-model 同步；null 表示空范围。
详情 声明类型 DateRange | null | undefined 字面量 null 关联类型 DateRange 类型定义 — DateRange export type DateRange = readonly [Date, Date] 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/DatePickerRangePanel.vue 解析值 null 来源 DatePickerRangePanel.vue:31 packages/ui/src/components/date-picker/DatePickerRangePanel.vue
minDate	Date | undefined	undefined	传给范围日历的最早可选日期；快捷范围直接作为更新值发出，需由调用方保证快捷项符合边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRangePanel.vue 解析值 undefined 来源 DatePickerRangePanel.vue:32 packages/ui/src/components/date-picker/DatePickerRangePanel.vue
maxDate	Date | undefined	undefined	传给范围日历的最晚可选日期；快捷范围直接作为更新值发出，需由调用方保证快捷项符合边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRangePanel.vue 解析值 undefined 来源 DatePickerRangePanel.vue:33 packages/ui/src/components/date-picker/DatePickerRangePanel.vue
shortcuts	DatePickerRangeShortcut[] | undefined	[] 按实例调用工厂函数	侧栏中的范围快捷项。函数值会用于解析显示状态，并在选择时重新求值，选中高亮与该次更新的范围保持一致。
详情 声明类型 DatePickerRangeShortcut[] | undefined 关联类型 DatePickerRangeShortcut 类型定义 — DatePickerRangeShortcut export interface DatePickerRangeShortcut { label: string value: DateRange | (() => DateRange) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/DatePickerRangePanel.vue 解析值 [] 来源 DatePickerRangePanel.vue:34 packages/ui/src/components/date-picker/DatePickerRangePanel.vue
clearable	boolean | undefined	true	显示包含清除和确认按钮的面板页脚；关闭时两个按钮一并隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/date-picker/DatePickerRangePanel.vue 解析值 true 来源 DatePickerRangePanel.vue:35 packages/ui/src/components/date-picker/DatePickerRangePanel.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.rangeLabel，简体中文文案为“日期范围”。	日期范围面板 dialog 的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DatePickerRangePanel.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.rangeLabel，简体中文文案为“日期范围”。 组件在说明的运行条件下采用此回退值。 来源 DatePickerRangePanel.vue:36 packages/ui/src/components/date-picker/DatePickerRangePanel.vue

DatePickerRangePanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: DateRange | null]	日历范围更新、拖动选区或选择快捷项时触发，携带起止日期元组；清除时传入 null。
详情 声明类型 [value: DateRange | null] 字面量 null 关联类型 DateRange 类型定义 — DateRange export type DateRange = readonly [Date, Date] 来源 DatePickerRangePanel.vue packages/ui/src/components/date-picker/DatePickerRangePanel.vue
@clear	[]	点击面板清除按钮时触发，随后发出 update:modelValue(null)。
详情 声明类型 [] 来源 DatePickerRangePanel.vue packages/ui/src/components/date-picker/DatePickerRangePanel.vue
@confirm	[value: DateRange | null]	点击确认时触发，携带当前起止日期元组；尚无范围时传入 null。
详情 声明类型 [value: DateRange | null] 字面量 null 关联类型 DateRange 类型定义 — DateRange export type DateRange = readonly [Date, Date] 来源 DatePickerRangePanel.vue packages/ui/src/components/date-picker/DatePickerRangePanel.vue

DateTimePicker

DateTimePicker — 属性

名称	类型	默认值	说明
open	boolean | undefined	undefined 运行时回退:为 undefined 时使用组件内部开关状态，初始为关闭。	受控的面板开关状态，通过 v-model:open 接收组件发出的开关请求。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 运行时回退 为 undefined 时使用组件内部开关状态，初始为关闭。 组件在说明的运行条件下采用此回退值。 来源 DateTimePicker.vue:19 packages/ui/src/components/date-picker/DateTimePicker.vue
size	"default" | "lg" | "sm" | undefined	"default"	控制日期触发按钮的高度、内边距及图标尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 "default" 来源 DateTimePicker.vue:20 packages/ui/src/components/date-picker/DateTimePicker.vue
variant	"default" | "error" | "success" | undefined	"default"	控制日期触发按钮的视觉状态，提供常规、错误和成功配色。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 "default" 来源 DateTimePicker.vue:21 packages/ui/src/components/date-picker/DateTimePicker.vue
modelValue 可空	Date | null | undefined	null	当前选中的日期和时间，通过 v-model 绑定；更换日期时会保留已有值的时分秒。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 null 来源 types.ts:65 packages/ui/src/components/date-picker/types.ts
showSeconds	boolean | undefined	false	显示秒选择器，同时决定默认显示格式和隐藏表单字段是否包含秒；关闭后仍保留 Date 中已有的秒值。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 false 来源 types.ts:66 packages/ui/src/components/date-picker/types.ts
timeStep	{ hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined	{ "hour": 1, "minute": 1, "second": 1 } 按实例调用工厂函数 运行时回退:缺失、非有限数或取整后小于 1 的分量使用步长 1。	分别设置小时、分钟和秒的选项步长。步长向下取整，小时最多为 24，分钟和秒最多为 60；当前值不在步进序列中时，仍会作为选项保留。
详情 声明类型 { hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined 默认值详情 声明 () => ({ hour: 1, minute: 1, second: 1 }) 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 { "hour": 1, "minute": 1, "second": 1 } 运行时回退 缺失、非有限数或取整后小于 1 的分量使用步长 1。 组件在说明的运行条件下采用此回退值。 来源 types.ts:67 packages/ui/src/components/date-picker/types.ts
placeholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.dateTimePlaceholder，简体中文文案为“选择日期时间”。	没有可显示日期时间时呈现在触发按钮中的占位文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.dateTimePlaceholder，简体中文文案为“选择日期时间”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:68 packages/ui/src/components/date-picker/types.ts
shortcuts	DatePickerShortcut[] | undefined	[] 按实例调用工厂函数	日期时间面板的日期快捷项；已有选中值时保留其时分秒，否则使用快捷值的时间，并将更新结果按日期时间边界收敛。
详情 声明类型 DatePickerShortcut[] | undefined 关联类型 DatePickerShortcut 类型定义 — DatePickerShortcut export interface DatePickerShortcut { label: string value: Date | (() => Date) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 [] 来源 types.ts:69 packages/ui/src/components/date-picker/types.ts
displayFormat	string | undefined	undefined 运行时回退:为 undefined 或 null 时，showSeconds 为真使用 YYYY-MM-DD HH:mm:ss，否则使用 YYYY-MM-DD HH:mm。	格式化触发器中显示的日期文本，支持 YYYY、YY、MM、DD、HH、mm、ss 和 WW；不改变绑定值的 Date 类型。WW 使用 ISO 周数，仅含周数而不含月日时，年份使用 ISO 周所属年份。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时，showSeconds 为真使用 YYYY-MM-DD HH:mm:ss，否则使用 YYYY-MM-DD HH:mm。 组件在说明的运行条件下采用此回退值。 来源 types.ts:6 packages/ui/src/components/date-picker/types.ts
minDate	Date | undefined	undefined	日历选择下界，同时限制日期、时间和快捷项更新后的完整时间；早于下界的更新值会收敛到该 Date。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 来源 types.ts:7 packages/ui/src/components/date-picker/types.ts
maxDate	Date | undefined	undefined	日历选择上界，同时限制日期、时间和快捷项更新后的完整时间；当边界的时、分、秒均为零时，允许该边界日内的其他时间。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 来源 types.ts:8 packages/ui/src/components/date-picker/types.ts
disabled	boolean | undefined	false	禁用触发按钮并隐藏触发器清除按钮；具有隐藏表单字段的选择器也会禁用该字段。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 false 来源 types.ts:9 packages/ui/src/components/date-picker/types.ts
readonly	boolean | undefined	false	阻止组件内部打开面板，并隐藏触发器清除按钮，保留当前日期的显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/date-picker/types.ts
clearable	boolean | undefined	false	显示面板清除按钮；有值且未禁用、未只读时也显示触发器清除按钮。面板确认按钮始终显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 false 来源 types.ts:11 packages/ui/src/components/date-picker/types.ts
name	string | undefined	undefined	原生隐藏表单字段名；按 showSeconds 提交 YYYY-MM-DD HH:mm 或 YYYY-MM-DD HH:mm:ss，与 displayFormat 独立。空值提交空字符串，禁用时不提交。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 来源 types.ts:14 packages/ui/src/components/date-picker/types.ts
id	string | undefined	undefined	传递给日期触发按钮的 HTML ID，可供 label 或辅助技术引用。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/date-picker/types.ts
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.dateTimePlaceholder，简体中文文案为“选择日期时间”。	日期时间触发按钮及弹出日期时间面板的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.dateTimePlaceholder，简体中文文案为“选择日期时间”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:16 packages/ui/src/components/date-picker/types.ts
class	string | undefined	undefined	合并到日期触发按钮上的补充 CSS 类名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePicker.vue 解析值 undefined 来源 types.ts:17 packages/ui/src/components/date-picker/types.ts

DateTimePicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	面板选择、确认或清除日期时触发，用于更新 v-model；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 DateTimePicker.vue packages/ui/src/components/date-picker/DateTimePicker.vue
@open	[]	面板开关状态变为打开时触发，面板显示值同时从当前 modelValue 重新初始化。
详情 声明类型 [] 来源 DateTimePicker.vue packages/ui/src/components/date-picker/DateTimePicker.vue
@close	[]	面板开关状态变为关闭时触发。
详情 声明类型 [] 来源 DateTimePicker.vue packages/ui/src/components/date-picker/DateTimePicker.vue
@update:open	[value: boolean]	组件请求设置面板开关时触发，用于 v-model:open；受控模式下需由父组件更新 open 才会改变显示状态。
详情 声明类型 [value: boolean] 字面量 false true 来源 DateTimePicker.vue packages/ui/src/components/date-picker/DateTimePicker.vue
@change	[value: Date | null]	确认或清除时立即触发；其他关闭场景中，仅当面板显示值与当时 modelValue 的时间戳不同才触发。
详情 声明类型 [value: Date | null] 字面量 null 来源 DateTimePicker.vue packages/ui/src/components/date-picker/DateTimePicker.vue

DateTimePicker — 暴露成员

名称	签名或类型	说明
open	Ref<boolean, boolean>	可读写的面板开关引用；通过组件实例赋值可请求打开或关闭，readonly 会阻止打开请求。受控模式下写入会触发 update:open，仍需父组件更新 open。
详情 声明类型 Ref<boolean, boolean> 字面量 false true 来源 DateTimePicker.vue packages/ui/src/components/date-picker/DateTimePicker.vue

DateTimePickerPanel

DateTimePickerPanel — 属性

名称	类型	默认值	说明
modelValue 可空	Date | null | undefined	null	独立日期时间面板的当前值，同时驱动日历和时间选择器，通过 v-model 同步。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 null 来源 DateTimePickerPanel.vue:32 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
minDate	Date | undefined	undefined	日历选择下界，同时限制日期、时间和快捷项更新后的完整时间；早于下界的更新值会收敛到该 Date。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 undefined 来源 DateTimePickerPanel.vue:33 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
maxDate	Date | undefined	undefined	日历选择上界，同时限制日期、时间和快捷项更新后的完整时间；当边界的时、分、秒均为零时，允许该边界日内的其他时间。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 undefined 来源 DateTimePickerPanel.vue:34 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
shortcuts	DatePickerShortcut[] | undefined	[] 按实例调用工厂函数	带标签的日期快捷项；已有值时合并其时分秒，否则保留快捷值的时间，更新结果按日期时间边界收敛。
详情 声明类型 DatePickerShortcut[] | undefined 关联类型 DatePickerShortcut 类型定义 — DatePickerShortcut export interface DatePickerShortcut { label: string value: Date | (() => Date) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 [] 来源 DateTimePickerPanel.vue:35 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
clearable	boolean | undefined	true	控制面板清除按钮的显示，确认按钮始终显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 true 来源 DateTimePickerPanel.vue:36 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
showSeconds	boolean | undefined	false	在内嵌时间选择器中显示秒选择项，隐藏时保留已有 Date 中的秒值。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 false 来源 DateTimePickerPanel.vue:37 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
timeStep	{ hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined	{ "hour": 1, "minute": 1, "second": 1 } 按实例调用工厂函数 运行时回退:缺失、非有限数或取整后小于 1 的分量使用步长 1。	分别设置小时、分钟和秒的选项步长。步长向下取整，小时最多为 24，分钟和秒最多为 60；当前值不在步进序列中时，仍会作为选项保留。
详情 声明类型 { hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined 默认值详情 声明 () => ({ hour: 1, minute: 1, second: 1 }) 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 { "hour": 1, "minute": 1, "second": 1 } 运行时回退 缺失、非有限数或取整后小于 1 的分量使用步长 1。 组件在说明的运行条件下采用此回退值。 来源 DateTimePickerPanel.vue:38 packages/ui/src/components/date-picker/DateTimePickerPanel.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.dateTimePlaceholder，简体中文文案为“选择日期时间”。	日期时间面板 dialog 的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/DateTimePickerPanel.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.dateTimePlaceholder，简体中文文案为“选择日期时间”。 组件在说明的运行条件下采用此回退值。 来源 DateTimePickerPanel.vue:39 packages/ui/src/components/date-picker/DateTimePickerPanel.vue

DateTimePickerPanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	日期、时间或快捷选择变化时，合并并按日期时间边界处理后触发；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 DateTimePickerPanel.vue packages/ui/src/components/date-picker/DateTimePickerPanel.vue
@clear	[]	点击面板清除按钮时触发，随后发出 update:modelValue(null)。
详情 声明类型 [] 来源 DateTimePickerPanel.vue packages/ui/src/components/date-picker/DateTimePickerPanel.vue
@confirm	[value: Date | null]	点击面板确认按钮时触发，携带当前 modelValue，包括未选择时的 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 DateTimePickerPanel.vue packages/ui/src/components/date-picker/DateTimePickerPanel.vue

MonthPicker

MonthPicker — 属性

名称	类型	默认值	说明
open	boolean | undefined	undefined 运行时回退:为 undefined 时使用组件内部开关状态，初始为关闭。	受控的面板开关状态，通过 v-model:open 接收组件发出的开关请求。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 运行时回退 为 undefined 时使用组件内部开关状态，初始为关闭。 组件在说明的运行条件下采用此回退值。 来源 MonthPicker.vue:19 packages/ui/src/components/date-picker/MonthPicker.vue
size	"default" | "lg" | "sm" | undefined	"default"	控制日期触发按钮的高度、内边距及图标尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 "default" 来源 MonthPicker.vue:20 packages/ui/src/components/date-picker/MonthPicker.vue
variant	"default" | "error" | "success" | undefined	"default"	控制日期触发按钮的视觉状态，提供常规、错误和成功配色。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 "default" 来源 MonthPicker.vue:21 packages/ui/src/components/date-picker/MonthPicker.vue
modelValue 可空	Date | null | undefined	null	用 Date 表示的当前月份，通过 v-model 绑定；选月时从该月第一日生成日期，再按上下界收敛。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 null 来源 types.ts:98 packages/ui/src/components/date-picker/types.ts
placeholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.monthPlaceholder，简体中文文案为“选择月份”。	没有可显示月份时呈现在触发按钮中的占位文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.monthPlaceholder，简体中文文案为“选择月份”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:99 packages/ui/src/components/date-picker/types.ts
displayFormat	string | undefined	"YYYY-MM"	格式化触发器中显示的日期文本，支持 YYYY、YY、MM、DD、HH、mm、ss 和 WW；不改变绑定值的 Date 类型。WW 使用 ISO 周数，仅含周数而不含月日时，年份使用 ISO 周所属年份。
详情 声明类型 string | undefined 默认值详情 声明 'YYYY-MM' 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 "YYYY-MM" 来源 types.ts:6 packages/ui/src/components/date-picker/types.ts
minDate	Date | undefined	undefined	月份选择下界；月末日期早于该值的月份不可选，选择或跨年确认得到的月初值会收敛到此下界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 来源 types.ts:7 packages/ui/src/components/date-picker/types.ts
maxDate	Date | undefined	undefined	月份选择上界；月初晚于该值的月份不可选，选择或跨年确认得到的值会收敛到此上界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 来源 types.ts:8 packages/ui/src/components/date-picker/types.ts
disabled	boolean | undefined	false	禁用触发按钮并隐藏触发器清除按钮；具有隐藏表单字段的选择器也会禁用该字段。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 false 来源 types.ts:9 packages/ui/src/components/date-picker/types.ts
readonly	boolean | undefined	false	阻止组件内部打开面板，并隐藏触发器清除按钮，保留当前日期的显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/date-picker/types.ts
clearable	boolean | undefined	false	显示面板底部的清除和确认操作；有值且未禁用、未只读时，也显示触发器清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 false 来源 types.ts:11 packages/ui/src/components/date-picker/types.ts
name	string | undefined	undefined	原生隐藏表单字段名，以 YYYY-MM 提交月份，与 displayFormat 独立；空值提交空字符串，禁用时不提交。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 来源 types.ts:14 packages/ui/src/components/date-picker/types.ts
id	string | undefined	undefined	传递给日期触发按钮的 HTML ID，可供 label 或辅助技术引用。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/date-picker/types.ts
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.monthPlaceholder，简体中文文案为“选择月份”。	月份触发按钮和月份面板的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.monthPlaceholder，简体中文文案为“选择月份”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:16 packages/ui/src/components/date-picker/types.ts
class	string | undefined	undefined	合并到日期触发按钮上的补充 CSS 类名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPicker.vue 解析值 undefined 来源 types.ts:17 packages/ui/src/components/date-picker/types.ts

MonthPicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	面板选择、确认或清除日期时触发，用于更新 v-model；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 MonthPicker.vue packages/ui/src/components/date-picker/MonthPicker.vue
@open	[]	面板开关状态变为打开时触发，面板显示值同时从当前 modelValue 重新初始化。
详情 声明类型 [] 来源 MonthPicker.vue packages/ui/src/components/date-picker/MonthPicker.vue
@close	[]	面板开关状态变为关闭时触发。
详情 声明类型 [] 来源 MonthPicker.vue packages/ui/src/components/date-picker/MonthPicker.vue
@update:open	[value: boolean]	组件请求设置面板开关时触发，用于 v-model:open；受控模式下需由父组件更新 open 才会改变显示状态。
详情 声明类型 [value: boolean] 字面量 false true 来源 MonthPicker.vue packages/ui/src/components/date-picker/MonthPicker.vue
@change	[value: Date | null]	确认或清除时立即触发；其他关闭场景中，仅当面板显示值与当时 modelValue 的时间戳不同才触发。
详情 声明类型 [value: Date | null] 字面量 null 来源 MonthPicker.vue packages/ui/src/components/date-picker/MonthPicker.vue

MonthPicker — 暴露成员

名称	签名或类型	说明
open	Ref<boolean, boolean>	可读写的面板开关引用；通过组件实例赋值可请求打开或关闭，readonly 会阻止打开请求。受控模式下写入会触发 update:open，仍需父组件更新 open。
详情 声明类型 Ref<boolean, boolean> 字面量 false true 来源 MonthPicker.vue packages/ui/src/components/date-picker/MonthPicker.vue

MonthPickerPanel

MonthPickerPanel — 属性

名称	类型	默认值	说明
modelValue 可空	Date | null | undefined	null	面板当前月份对应的 Date，并用其年份初始化显示视图；空值初始显示当前年份。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/MonthPickerPanel.vue 解析值 null 来源 MonthPickerPanel.vue:12 packages/ui/src/components/date-picker/MonthPickerPanel.vue
minDate	Date | undefined	undefined	月份选择下界；月末日期早于该值的月份不可选，选择或跨年确认得到的月初值会收敛到此下界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPickerPanel.vue 解析值 undefined 来源 MonthPickerPanel.vue:13 packages/ui/src/components/date-picker/MonthPickerPanel.vue
maxDate	Date | undefined	undefined	月份选择上界；月初晚于该值的月份不可选，选择或跨年确认得到的值会收敛到此上界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPickerPanel.vue 解析值 undefined 来源 MonthPickerPanel.vue:14 packages/ui/src/components/date-picker/MonthPickerPanel.vue
clearable	boolean | undefined	true	显示包含清除和确认按钮的面板页脚；关闭时两个按钮一并隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/date-picker/MonthPickerPanel.vue 解析值 true 来源 MonthPickerPanel.vue:15 packages/ui/src/components/date-picker/MonthPickerPanel.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.monthPlaceholder，简体中文文案为“选择月份”。	月份面板 dialog 的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/MonthPickerPanel.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.monthPlaceholder，简体中文文案为“选择月份”。 组件在说明的运行条件下采用此回退值。 来源 MonthPickerPanel.vue:16 packages/ui/src/components/date-picker/MonthPickerPanel.vue

MonthPickerPanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	选择可用月份时触发，值从该月第一日生成并按上下界收敛；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 MonthPickerPanel.vue packages/ui/src/components/date-picker/MonthPickerPanel.vue
@clear	[]	点击面板清除按钮时触发，随后发出 update:modelValue(null)。
详情 声明类型 [] 来源 MonthPickerPanel.vue packages/ui/src/components/date-picker/MonthPickerPanel.vue
@confirm	[value: Date | null]	确认当前月份；若仅翻年而未重新选月，则以视图年份和已有月份生成日期并按上下界收敛。没有选中值时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 MonthPickerPanel.vue packages/ui/src/components/date-picker/MonthPickerPanel.vue

TimePicker

TimePicker — 属性

名称	类型	默认值	说明
modelValue 可空	Date | null | undefined	null	承载时分秒的 Date，通过 v-model 绑定。更改某个时间分量时保留日期及其他分量；空值显示零，首次选择以本地当天零点为基准。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/TimePicker.vue 解析值 null 来源 TimePicker.vue:12 packages/ui/src/components/date-picker/TimePicker.vue
showSeconds	boolean | undefined	false	显示秒选择器；隐藏秒选择器不会清零 Date 中已有的秒值。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/TimePicker.vue 解析值 false 来源 TimePicker.vue:13 packages/ui/src/components/date-picker/TimePicker.vue
timeStep	{ hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined	{ "hour": 1, "minute": 1, "second": 1 } 按实例调用工厂函数 运行时回退:缺失、非有限数或取整后小于 1 的分量使用步长 1。	分别设置小时、分钟和秒的选项步长。步长向下取整，小时最多为 24，分钟和秒最多为 60；当前值不在步进序列中时，仍会作为选项保留。
详情 声明类型 { hour?: number | undefined; minute?: number | undefined; second?: number | undefined; } | undefined 默认值详情 声明 () => ({ hour: 1, minute: 1, second: 1 }) 来源: packages/ui/src/components/date-picker/TimePicker.vue 解析值 { "hour": 1, "minute": 1, "second": 1 } 运行时回退 缺失、非有限数或取整后小于 1 的分量使用步长 1。 组件在说明的运行条件下采用此回退值。 来源 TimePicker.vue:14 packages/ui/src/components/date-picker/TimePicker.vue
disabled	boolean | undefined	false	禁用全部时间下拉框，并阻止小时、分钟和秒的选择回调更新值。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/TimePicker.vue 解析值 false 来源 TimePicker.vue:15 packages/ui/src/components/date-picker/TimePicker.vue
embedded	boolean | undefined	false	启用用于嵌入日期时间面板的布局和边框样式。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/TimePicker.vue 解析值 false 来源 TimePicker.vue:16 packages/ui/src/components/date-picker/TimePicker.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.timePlaceholder，简体中文文案为“选择时间”。	包裹时分秒选择器的 group 元素的无障碍名称，各时间下拉框保留对应的国际化标签。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/TimePicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.timePlaceholder，简体中文文案为“选择时间”。 组件在说明的运行条件下采用此回退值。 来源 TimePicker.vue:17 packages/ui/src/components/date-picker/TimePicker.vue

TimePicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	选择小时、分钟或秒时立即触发，携带更新后的 Date，用于 v-model 同步。
详情 声明类型 [value: Date | null] 字面量 null 来源 TimePicker.vue packages/ui/src/components/date-picker/TimePicker.vue

WeekPicker

WeekPicker — 属性

名称	类型	默认值	说明
open	boolean | undefined	undefined 运行时回退:为 undefined 时使用组件内部开关状态，初始为关闭。	受控的面板开关状态，通过 v-model:open 接收组件发出的开关请求。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 运行时回退 为 undefined 时使用组件内部开关状态，初始为关闭。 组件在说明的运行条件下采用此回退值。 来源 WeekPicker.vue:19 packages/ui/src/components/date-picker/WeekPicker.vue
size	"default" | "lg" | "sm" | undefined	"default"	控制日期触发按钮的高度、内边距及图标尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 "default" 来源 WeekPicker.vue:20 packages/ui/src/components/date-picker/WeekPicker.vue
variant	"default" | "error" | "success" | undefined	"default"	控制日期触发按钮的视觉状态，提供常规、错误和成功配色。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 "default" 来源 WeekPicker.vue:21 packages/ui/src/components/date-picker/WeekPicker.vue
modelValue 可空	Date | null | undefined	null	表示当前周的 Date，通过 v-model 绑定；从面板选择日期或快捷项后，返回 weekStartsOn 指定的周起始日零点。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 null 来源 types.ts:82 packages/ui/src/components/date-picker/types.ts
weekStartsOn	0 | 1 | undefined	1	设置周起始日，0 为周日、1 为周一，同时决定日历首列、整周高亮和选中值的周起始日期；不会从当前语言自动推导。
详情 声明类型 0 | 1 | undefined 字面量 0 1 默认值详情 声明 1 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 1 来源 types.ts:83 packages/ui/src/components/date-picker/types.ts
placeholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.weekPlaceholder，简体中文文案为“选择周”。	没有可显示周次时呈现在触发按钮中的占位文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.weekPlaceholder，简体中文文案为“选择周”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:84 packages/ui/src/components/date-picker/types.ts
shortcuts	DatePickerShortcut[] | undefined	[] 按实例调用工厂函数	周选择快捷项，值可为 Date 或返回 Date 的函数；选中时转换为 weekStartsOn 指定的周起始日。
详情 声明类型 DatePickerShortcut[] | undefined 关联类型 DatePickerShortcut 类型定义 — DatePickerShortcut export interface DatePickerShortcut { label: string value: Date | (() => Date) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 [] 来源 types.ts:85 packages/ui/src/components/date-picker/types.ts
displayFormat	string | undefined	"YYYY-WW"	格式化触发器中显示的日期文本，支持 YYYY、YY、MM、DD、HH、mm、ss 和 WW；不改变绑定值的 Date 类型。WW 使用 ISO 周数，仅含周数而不含月日时，年份使用 ISO 周所属年份。
详情 声明类型 string | undefined 默认值详情 声明 'YYYY-WW' 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 "YYYY-WW" 来源 types.ts:6 packages/ui/src/components/date-picker/types.ts
minDate	Date | undefined	undefined	传给周选择日历的最早可选日期。选中后转换为周起始日，结果可能早于该边界；快捷项也直接转换为周起始日。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 来源 types.ts:7 packages/ui/src/components/date-picker/types.ts
maxDate	Date | undefined	undefined	传给周选择日历的最晚可选日期。该限制针对日历中的选日，不要求整周位于边界内；快捷项需由调用方保证范围有效。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 来源 types.ts:8 packages/ui/src/components/date-picker/types.ts
disabled	boolean | undefined	false	禁用触发按钮并隐藏触发器清除按钮；具有隐藏表单字段的选择器也会禁用该字段。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 false 来源 types.ts:9 packages/ui/src/components/date-picker/types.ts
readonly	boolean | undefined	false	阻止组件内部打开面板，并隐藏触发器清除按钮，保留当前日期的显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/date-picker/types.ts
clearable	boolean | undefined	false	显示面板底部的清除和确认操作；有值且未禁用、未只读时，也显示触发器清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 false 来源 types.ts:11 packages/ui/src/components/date-picker/types.ts
name	string | undefined	undefined	原生隐藏表单字段名，以 YYYY-MM-DD 提交当前 Date，与周次显示格式独立；空值提交空字符串，禁用时不提交。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 来源 types.ts:14 packages/ui/src/components/date-picker/types.ts
id	string | undefined	undefined	传递给日期触发按钮的 HTML ID，可供 label 或辅助技术引用。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/date-picker/types.ts
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.weekPlaceholder，简体中文文案为“选择周”。	周选择触发按钮和周选择面板的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.weekPlaceholder，简体中文文案为“选择周”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:16 packages/ui/src/components/date-picker/types.ts
class	string | undefined	undefined	合并到日期触发按钮上的补充 CSS 类名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPicker.vue 解析值 undefined 来源 types.ts:17 packages/ui/src/components/date-picker/types.ts

WeekPicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	面板选择、确认或清除日期时触发，用于更新 v-model；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 WeekPicker.vue packages/ui/src/components/date-picker/WeekPicker.vue
@open	[]	面板开关状态变为打开时触发，面板显示值同时从当前 modelValue 重新初始化。
详情 声明类型 [] 来源 WeekPicker.vue packages/ui/src/components/date-picker/WeekPicker.vue
@close	[]	面板开关状态变为关闭时触发。
详情 声明类型 [] 来源 WeekPicker.vue packages/ui/src/components/date-picker/WeekPicker.vue
@update:open	[value: boolean]	组件请求设置面板开关时触发，用于 v-model:open；受控模式下需由父组件更新 open 才会改变显示状态。
详情 声明类型 [value: boolean] 字面量 false true 来源 WeekPicker.vue packages/ui/src/components/date-picker/WeekPicker.vue
@change	[value: Date | null]	确认或清除时立即触发；其他关闭场景中，仅当面板显示值与当时 modelValue 的时间戳不同才触发。
详情 声明类型 [value: Date | null] 字面量 null 来源 WeekPicker.vue packages/ui/src/components/date-picker/WeekPicker.vue

WeekPicker — 暴露成员

名称	签名或类型	说明
open	Ref<boolean, boolean>	可读写的面板开关引用；通过组件实例赋值可请求打开或关闭，readonly 会阻止打开请求。受控模式下写入会触发 update:open，仍需父组件更新 open。
详情 声明类型 Ref<boolean, boolean> 字面量 false true 来源 WeekPicker.vue packages/ui/src/components/date-picker/WeekPicker.vue

WeekPickerPanel

WeekPickerPanel — 属性

名称	类型	默认值	说明
modelValue 可空	Date | null | undefined	null	面板当前周对应的日期，按其所在周绘制整周高亮；选择更新时返回周起始日。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 null 来源 WeekPickerPanel.vue:32 packages/ui/src/components/date-picker/WeekPickerPanel.vue
weekStartsOn	0 | 1 | undefined	1	设置周起始日，0 为周日、1 为周一，同时决定日历首列、整周高亮和选中值的周起始日期；不会从当前语言自动推导。
详情 声明类型 0 | 1 | undefined 字面量 0 1 默认值详情 声明 1 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 1 来源 WeekPickerPanel.vue:33 packages/ui/src/components/date-picker/WeekPickerPanel.vue
minDate	Date | undefined	undefined	传给周选择日历的最早可选日期。选中后转换为周起始日，结果可能早于该边界；快捷项也直接转换为周起始日。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 undefined 来源 WeekPickerPanel.vue:34 packages/ui/src/components/date-picker/WeekPickerPanel.vue
maxDate	Date | undefined	undefined	传给周选择日历的最晚可选日期。该限制针对日历中的选日，不要求整周位于边界内；快捷项需由调用方保证范围有效。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 undefined 来源 WeekPickerPanel.vue:35 packages/ui/src/components/date-picker/WeekPickerPanel.vue
shortcuts	DatePickerShortcut[] | undefined	[] 按实例调用工厂函数	侧栏中的带标签日期快捷项，选中和高亮比较都使用对应的周起始日。
详情 声明类型 DatePickerShortcut[] | undefined 关联类型 DatePickerShortcut 类型定义 — DatePickerShortcut export interface DatePickerShortcut { label: string value: Date | (() => Date) } 默认值详情 声明 () => [] 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 [] 来源 WeekPickerPanel.vue:36 packages/ui/src/components/date-picker/WeekPickerPanel.vue
clearable	boolean | undefined	true	显示包含清除和确认按钮的面板页脚；关闭时两个按钮一并隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 true 来源 WeekPickerPanel.vue:37 packages/ui/src/components/date-picker/WeekPickerPanel.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.weekPlaceholder，简体中文文案为“选择周”。	周选择面板 dialog 的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/WeekPickerPanel.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.weekPlaceholder，简体中文文案为“选择周”。 组件在说明的运行条件下采用此回退值。 来源 WeekPickerPanel.vue:38 packages/ui/src/components/date-picker/WeekPickerPanel.vue

WeekPickerPanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	选择日历日期或快捷项时触发，携带按 weekStartsOn 对齐的本地周起始日零点；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 WeekPickerPanel.vue packages/ui/src/components/date-picker/WeekPickerPanel.vue
@clear	[]	点击面板清除按钮时触发，随后发出 update:modelValue(null)。
详情 声明类型 [] 来源 WeekPickerPanel.vue packages/ui/src/components/date-picker/WeekPickerPanel.vue
@confirm	[value: Date | null]	点击面板确认按钮时触发，携带当前 modelValue，包括未选择时的 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 WeekPickerPanel.vue packages/ui/src/components/date-picker/WeekPickerPanel.vue

YearPicker

YearPicker — 属性

名称	类型	默认值	说明
open	boolean | undefined	undefined 运行时回退:为 undefined 时使用组件内部开关状态，初始为关闭。	受控的面板开关状态，通过 v-model:open 接收组件发出的开关请求。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 运行时回退 为 undefined 时使用组件内部开关状态，初始为关闭。 组件在说明的运行条件下采用此回退值。 来源 YearPicker.vue:19 packages/ui/src/components/date-picker/YearPicker.vue
size	"default" | "lg" | "sm" | undefined	"default"	控制日期触发按钮的高度、内边距及图标尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 "default" 来源 YearPicker.vue:20 packages/ui/src/components/date-picker/YearPicker.vue
variant	"default" | "error" | "success" | undefined	"default"	控制日期触发按钮的视觉状态，提供常规、错误和成功配色。
详情 声明类型 NonNullable<"default" | "success" | "error" | null | undefined> | undefined 字面量 "default" "error" "success" 默认值详情 声明 'default' 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 "default" 来源 YearPicker.vue:21 packages/ui/src/components/date-picker/YearPicker.vue
modelValue 可空	Date | null | undefined	null	用 Date 表示的当前年份，通过 v-model 绑定；选择年份时保留已有值的月日，空值以当天月日为基准，闰日会收敛至有效日期。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 null 来源 types.ts:112 packages/ui/src/components/date-picker/types.ts
placeholder	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.yearPlaceholder，简体中文文案为“选择年”。	没有可显示年份时呈现在触发按钮中的占位文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.yearPlaceholder，简体中文文案为“选择年”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:113 packages/ui/src/components/date-picker/types.ts
displayFormat	string | undefined	"YYYY"	格式化触发器中显示的日期文本，支持 YYYY、YY、MM、DD、HH、mm、ss 和 WW；不改变绑定值的 Date 类型。WW 使用 ISO 周数，仅含周数而不含月日时，年份使用 ISO 周所属年份。
详情 声明类型 string | undefined 默认值详情 声明 'YYYY' 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 "YYYY" 来源 types.ts:6 packages/ui/src/components/date-picker/types.ts
minDate	Date | undefined	undefined	用于禁用年份按钮的下界；某年 12 月 31 日早于该值时，该年不可选。选择仍保留基准日期的月日，不会按完整日期收敛到边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 来源 types.ts:7 packages/ui/src/components/date-picker/types.ts
maxDate	Date | undefined	undefined	用于禁用年份按钮的上界；某年 1 月 1 日晚于该值时，该年不可选。选择仍保留基准日期的月日，不会按完整日期收敛到边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 来源 types.ts:8 packages/ui/src/components/date-picker/types.ts
disabled	boolean | undefined	false	禁用触发按钮并隐藏触发器清除按钮；具有隐藏表单字段的选择器也会禁用该字段。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 false 来源 types.ts:9 packages/ui/src/components/date-picker/types.ts
readonly	boolean | undefined	false	阻止组件内部打开面板，并隐藏触发器清除按钮，保留当前日期的显示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/date-picker/types.ts
clearable	boolean | undefined	false	显示面板底部的清除和确认操作；有值且未禁用、未只读时，也显示触发器清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 false 来源 types.ts:11 packages/ui/src/components/date-picker/types.ts
name	string | undefined	undefined	原生隐藏表单字段名，以 YYYY 提交年份，与 displayFormat 独立；空值提交空字符串，禁用时不提交。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 来源 types.ts:14 packages/ui/src/components/date-picker/types.ts
id	string | undefined	undefined	传递给日期触发按钮的 HTML ID，可供 label 或辅助技术引用。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 来源 types.ts:15 packages/ui/src/components/date-picker/types.ts
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.yearPlaceholder，简体中文文案为“选择年”。	年份触发按钮和年份面板的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.yearPlaceholder，简体中文文案为“选择年”。 组件在说明的运行条件下采用此回退值。 来源 types.ts:16 packages/ui/src/components/date-picker/types.ts
class	string | undefined	undefined	合并到日期触发按钮上的补充 CSS 类名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPicker.vue 解析值 undefined 来源 types.ts:17 packages/ui/src/components/date-picker/types.ts

YearPicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	面板选择、确认或清除日期时触发，用于更新 v-model；清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 YearPicker.vue packages/ui/src/components/date-picker/YearPicker.vue
@open	[]	面板开关状态变为打开时触发，面板显示值同时从当前 modelValue 重新初始化。
详情 声明类型 [] 来源 YearPicker.vue packages/ui/src/components/date-picker/YearPicker.vue
@close	[]	面板开关状态变为关闭时触发。
详情 声明类型 [] 来源 YearPicker.vue packages/ui/src/components/date-picker/YearPicker.vue
@update:open	[value: boolean]	组件请求设置面板开关时触发，用于 v-model:open；受控模式下需由父组件更新 open 才会改变显示状态。
详情 声明类型 [value: boolean] 字面量 false true 来源 YearPicker.vue packages/ui/src/components/date-picker/YearPicker.vue
@change	[value: Date | null]	确认或清除时立即触发；其他关闭场景中，仅当面板显示值与当时 modelValue 的时间戳不同才触发。
详情 声明类型 [value: Date | null] 字面量 null 来源 YearPicker.vue packages/ui/src/components/date-picker/YearPicker.vue

YearPicker — 暴露成员

名称	签名或类型	说明
open	Ref<boolean, boolean>	可读写的面板开关引用；通过组件实例赋值可请求打开或关闭，readonly 会阻止打开请求。受控模式下写入会触发 update:open，仍需父组件更新 open。
详情 声明类型 Ref<boolean, boolean> 字面量 false true 来源 YearPicker.vue packages/ui/src/components/date-picker/YearPicker.vue

YearPickerPanel

YearPickerPanel — 属性

名称	类型	默认值	说明
modelValue 可空	Date | null | undefined	null	面板当前年份对应的 Date，用于初始化所处年代；清空后视图回到当前年份所在年代。
详情 声明类型 Date | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/date-picker/YearPickerPanel.vue 解析值 null 来源 YearPickerPanel.vue:14 packages/ui/src/components/date-picker/YearPickerPanel.vue
minDate	Date | undefined	undefined	用于禁用年份按钮的下界；某年 12 月 31 日早于该值时，该年不可选。选择仍保留基准日期的月日，不会按完整日期收敛到边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPickerPanel.vue 解析值 undefined 来源 YearPickerPanel.vue:15 packages/ui/src/components/date-picker/YearPickerPanel.vue
maxDate	Date | undefined	undefined	用于禁用年份按钮的上界；某年 1 月 1 日晚于该值时，该年不可选。选择仍保留基准日期的月日，不会按完整日期收敛到边界。
详情 声明类型 Date | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPickerPanel.vue 解析值 undefined 来源 YearPickerPanel.vue:16 packages/ui/src/components/date-picker/YearPickerPanel.vue
clearable	boolean | undefined	true	显示包含清除和确认按钮的面板页脚；关闭时两个按钮一并隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/date-picker/YearPickerPanel.vue 解析值 true 来源 YearPickerPanel.vue:17 packages/ui/src/components/date-picker/YearPickerPanel.vue
yearRange	number | undefined	12 运行时回退:向下取整后不是有限数或小于 1 时，使用 DEFAULT_YEAR_RANGE。	每页展示的连续年份数量，同时作为前后翻页步幅；初始视图起点仍为所选年份或当前年份所在年代的起始年。
详情 声明类型 number | undefined 默认值详情 声明 DEFAULT_YEAR_RANGE 来源: packages/ui/src/components/date-picker/YearPickerPanel.vue 解析值 12 运行时回退 向下取整后不是有限数或小于 1 时，使用 DEFAULT_YEAR_RANGE。 组件在说明的运行条件下采用此回退值。 来源 YearPickerPanel.vue:18 packages/ui/src/components/date-picker/YearPickerPanel.vue
ariaLabel	string | undefined	undefined 运行时回退:为 undefined 或 null 时读取 datePicker.yearPlaceholder，简体中文文案为“选择年”。	年份面板 dialog 的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/date-picker/YearPickerPanel.vue 解析值 undefined 运行时回退 为 undefined 或 null 时读取 datePicker.yearPlaceholder，简体中文文案为“选择年”。 组件在说明的运行条件下采用此回退值。 来源 YearPickerPanel.vue:19 packages/ui/src/components/date-picker/YearPickerPanel.vue

YearPickerPanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: Date | null]	选择可用年份时触发，以已有日期或当天的月日生成本地零点日期；2 月 29 日切换到平年时收敛为 2 月 28 日。清除时传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 YearPickerPanel.vue packages/ui/src/components/date-picker/YearPickerPanel.vue
@clear	[]	点击面板清除按钮时触发，随后发出 update:modelValue(null)。
详情 声明类型 [] 来源 YearPickerPanel.vue packages/ui/src/components/date-picker/YearPickerPanel.vue
@confirm	[value: Date | null]	确认当前年份。若已有值不在当前页面的年份范围中，则改用该页起始年份并保留月日，闰日会收敛至有效日期；空值传入 null。
详情 声明类型 [value: Date | null] 字面量 null 来源 YearPickerPanel.vue packages/ui/src/components/date-picker/YearPickerPanel.vue

可访问性

键盘导航

按键	操作
Enter / Space	打开面板
Escape	关闭面板
Tab	在输入框和面板间切换

常见问题

Q: 安装后组件报错找不到 v-calendar 模块？

A: DatePicker 组件依赖 v-calendar，属于额外依赖，需要手动安装：pnpm add v-calendar。安装后重启开发服务器即可正常运行。

Q: DatePickerRange 为什么没有 open 属性？

A: DatePickerRange 和 TimePicker 未暴露 open 响应式引用，不支持通过 v-model:open 双向绑定控制面板状态。如果需要程序化控制面板开关，请使用 DatePicker、DateTimePicker、WeekPicker、MonthPicker 或 YearPicker。

Q: WeekPicker 选中日期后，为什么显示的周起始日与预期不符？

A: WeekPicker 的 weekStartsOn 属性控制周起始日：0 表示周日起始，1 表示周一起始（默认）。选中任意日期后，modelValue 会自动对齐到当周的起始日。如果显示结果与预期不符，请检查 weekStartsOn 的设置是否符合业务需求。