代码演示
如何引入
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
基本使用
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<DatePicker @change="(_date, dateString) => console.log(dateString)" />
</template>小尺寸
使用 density 可以控制日期面板的尺寸,compact 为小尺寸,default 为默认尺寸。
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<DatePicker density="compact" type="dateTime" />
<br />
<br />
<DatePicker density="compact" :style="{ width: '260px' }" type="dateRange" />
</div>
</template>多个日期选择
将 multiple 设为 true,可以多选日期
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<DatePicker multiple :style="{ width: '240px' }" />
</template>日期与时间选择
将 type 设定为 dateTime,可以选择日期时间。
版本V2.22.0开始,我们将 TimePicker 内的 ScrollItem 的默认模式从 wheel 变更为了 normal, 若想应用回无限滚动的效果,可以通过 timePickerOpts 传入特定配置开启。
默认日期与时间选择
开启时间列表无限循环
代码
<script setup lang="ts">
import { DatePicker, type DatePickerTimePickerOpts } from '@fibrous/semi-ui-vue';
const timePickerOpts: DatePickerTimePickerOpts = { scrollItemProps: { mode: 'wheel', cycled: true } };
</script>
<template>
<h4>默认日期与时间选择</h4>
<DatePicker type="dateTime" />
<br />
<br />
<h4>开启时间列表无限循环</h4>
<DatePicker :timePickerOpts="timePickerOpts" type="dateTime" />
</template>日期范围选择
将 type 设定为 dateRange,可以选择日期范围
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<DatePicker :style="{ width: '260px' }" type="dateRange" @change="console.log" />
</template>日期范围时间选择
将 type 设定为 dateTimeRange, 可以选择日期时间范围
当未传入初始值或受控值时,底部面板默认时间为当前时间。如果你有特殊需求(如指定默认时分秒),可以通过 defaultPickerValue 指定
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const defaultPickerValue = [new Date('2022-08-08 00:00'), new Date('2022-08-09 12:00')];
</script>
<template>
<DatePicker :style="{ width: '400px', marginBottom: '8px' }" type="dateTimeRange" @change="console.log" />
<DatePicker :defaultPickerValue="defaultPickerValue" :style="{ width: '400px' }" type="dateTimeRange" @change="console.log" />
</template>内嵌输入框
使用 insetInput 可以控制日期面板是否展示内嵌输入框,默认为 false。v2.7.0 后支持。内嵌输入框适用于以下场景:
- 日期时间选择,可以直接通过内嵌输入框单独修改时间,无须通过滚轮选择时间
- 自定义触发器时 + 范围选择,使用内嵌输入框可以单独对开始和结束日期进行修改
insetInput 开启后包括以下功能:
- 点击触发器后,面板默认在原有位置弹出。你可以通过 position 自定义弹出位置
- 点击内嵌日期输入框,面板切换到日期选择;点击内嵌时间输入框,面板切换到时间选择
- 和外部的输入框一致,如果输入了非法日期,面板关闭后日期会回到之前的合法日期
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<DatePicker insetInput type="date" />
<br />
<br />
<DatePicker insetInput type="dateTime" />
<br />
<br />
<DatePicker insetInput :style="{ width: '260px' }" type="dateRange" />
<br />
<br />
<DatePicker insetInput :style="{ width: '400px' }" type="dateTimeRange" />
<br />
<br />
<DatePicker insetInput placeholder="请选择年月" :style="{ width: '140px' }" type="month" />
<br />
<br />
<DatePicker insetInput placeholder="请选择年月范围" :style="{ width: '200px' }" type="monthRange" />
<br />
<br />
<DatePicker insetInput position="bottomLeft" type="date" />
<br />
<br />
<DatePicker format="yyyy-MM-dd HH:mm" insetInput type="dateTime" />
</div>
</template>同步切换双面板月份
在范围选择的场景中, 开启 syncSwitchMonth 则允许双面板同步切换。默认为 false。
Note:点击年份按钮也会同步切换两个面板,从滚轮里面切换年月不会同步切换面板,这保证了用户选择非固定间隔月份的能力。
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<DatePicker :style="{ width: '400px' }" syncSwitchMonth type="dateTimeRange" />
</template>切换面板日期的回调
panelChange 事件会在面板的月份或年份切换改变时触发。
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const onPanelChange = (date: Date | Date[], dateString: string | string[]) => console.log(date, dateString);
</script>
<template>
<DatePicker :style="{ width: '400px' }" syncSwitchMonth type="dateTimeRange" @panelChange="onPanelChange" />
</template>周选择
dateRange 搭配 startDateOffset 和 endDateOffset 可以进行单击范围选择,如周选择、双周选择。
选择自然周
选择双周
选择当前日和后6日
代码
<script setup lang="ts">
import * as dateFns from 'date-fns';
import { DatePicker } from '@fibrous/semi-ui-vue';
function handleChange(date: Date | Date[] | undefined) {
console.log('date changed', date);
}
const startOfWeek = (date: Date) => dateFns.startOfWeek(date, { weekStartsOn: 1 });
const endOfWeek = (date: Date) => dateFns.endOfWeek(date, { weekStartsOn: 1 });
const endOfNextWeek = (date: Date) => dateFns.add(endOfWeek(date), { days: 7 });
const sixDaysLater = (date: Date) => dateFns.add(date, { days: 6 });
</script>
<template>
<div>
<h4>选择自然周</h4>
<DatePicker :endDateOffset="endOfWeek" :startDateOffset="startOfWeek" :style="{ width: '260px' }" type="dateRange" :weekStartsOn="1" @change="handleChange" />
<br />
<br />
<h4>选择双周</h4>
<DatePicker :endDateOffset="endOfNextWeek" :startDateOffset="startOfWeek" :style="{ width: '260px' }" type="dateRange" :weekStartsOn="1" @change="handleChange" />
<br />
<br />
<h4>选择当前日和后6日</h4>
<DatePicker :endDateOffset="sixDaysLater" :style="{ width: '260px' }" type="dateRange" :weekStartsOn="1" @change="handleChange" />
<br />
<br />
</div>
</template>年月选择
将 type 设定为 month,可以进行年月选择。
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const defaultValue = new Date(2024, 4, 6, 10, 30, 0);
</script>
<template>
<DatePicker :defaultValue="defaultValue" :style="{ width: '140px' }" type="month" />
</template>年月范围选择
版本: >= 2.32.0
将 type 设定为 monthRange,可以进行年月范围选择。暂不支持小尺寸与快捷面板。
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
</script>
<template>
<DatePicker :style="{ width: '200px' }" type="monthRange" />
</template>年份选择
将 type 设定为 year,可以进行年份选择。面板只有一列年份,选中的值为该年 1 月 1 日,默认格式为 yyyy。disabledDate 以每年的 1 月 1 日判断该年是否可选。
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const defaultValue = new Date(2024, 4, 6, 10, 30, 0);
</script>
<template>
<DatePicker :defaultValue="defaultValue" :style="{ width: '140px' }" type="year" />
</template>确认日期时间选择
对于“日期时间”(type="dateTime")或“日期时间范围”(type="dateTimeRange")的选择,可以进行确认后才将值写入输入框内,你可以通过传递 needConfirm=true 来开启这种行为。
同时支持 “确认”(confirm 事件) 和 “取消”(cancel 事件) 两个按钮的点击事件。
下面这个例子监听了 change、confirm、cancel 三个事件,你可以打开控制台查看打印信息的区别。
注意:开启确认选择时,需要点击取消按钮关闭面板,点击空白区域不再关闭面板(v2.2.0)
代码
<script setup lang="ts">
import { DatePicker, type DatePickerEmits } from '@fibrous/semi-ui-vue';
const onConfirm = (...args: DatePickerEmits['confirm']) => {
console.log('Confirmed: ', ...args);
};
const onCancel = (...args: DatePickerEmits['cancel']) => {
console.log('Canceled: ', ...args);
};
const onChange = (...args: DatePickerEmits['change']) => {
console.log('Changed: ', ...args);
};
</script>
<template>
<DatePicker needConfirm type="dateTime" @cancel="onCancel" @change="onChange" @confirm="onConfirm" />
</template>带有快捷方式的日期时间选择
通过 presets 设定快捷日期选择
代码
<script setup lang="ts">
import { DatePicker, type DatePickerPresetsType } from '@fibrous/semi-ui-vue';
const presets: DatePickerPresetsType = [
{
text: 'Today',
start: () => new Date(),
end: () => new Date(),
},
() => ({
text: 'Tomorrow',
start: new Date(new Date().valueOf() + 1000 * 3600 * 24),
end: new Date(new Date().valueOf() + 1000 * 3600 * 24),
}),
];
</script>
<template>
<DatePicker presetPosition="left" :presets="presets" type="dateTime" />
</template>渲染顶部/底部额外区域
通过 #topSlot 和 #bottomSlot 插槽可以自定义渲染顶部和底部额外区域
通过 #leftSlot 和 #rightSlot 插槽可以自定义渲染左侧和右侧额外区域
代码
<script setup lang="ts">
import { computed, ref } from 'vue';
import { IconBulb } from '@fibrous/semi-icons-vue';
import { DatePicker, Space, TabPane, Tabs, Typography, type DatePickerValueType } from '@fibrous/semi-ui-vue';
const { Text } = Typography;
const uedDisabledDate = (currentDate?: Date) => !!currentDate && currentDate.getDate() > 10 && currentDate.getDate() < 15;
const testDisabledDate = (currentDate?: Date) => !!currentDate && currentDate.getDate() > 15 && currentDate.getDate() < 25;
const activeTab = ref('1');
const date = ref<DatePickerValueType>();
const disabledDate = computed(() => (activeTab.value === '1' ? uedDisabledDate : testDisabledDate));
</script>
<template>
<div>
<DatePicker v-model="date" :disabledDate="disabledDate" dropdownClassName="components-datepicker-demo-slot" placeholder="请选择排期">
<template #topSlot>
<Tabs v-model:activeKey="activeTab" size="small" :style="{ padding: '12px 20px 0' }" @change="date = undefined">
<TabPane itemKey="1">
<template #tab>UED 排期</template>
</TabPane>
<TabPane itemKey="2">
<template #tab>测试排期</template>
</TabPane>
</Tabs>
</template>
</DatePicker>
<br />
<br />
<DatePicker placeholder="请选择发版时间">
<template #bottomSlot>
<Space :style="{ padding: '12px 20px' }">
<IconBulb :style="{ color: 'var(--semi-amber-5)' }" />
<Text strong :style="{ color: 'var(--semi-color-text-2)' }">定版前请阅读</Text>
<Text :link="{ href: 'https://semi.design/', target: '_blank' }">发版须知</Text>
</Space>
</template>
</DatePicker>
<br />
<br />
<DatePicker placeholder="请选择年月" type="month">
<template #bottomSlot>
<Space :style="{ padding: '12px 20px' }">
<IconBulb :style="{ color: 'var(--semi-amber-5)' }" />
<Text strong :style="{ color: 'var(--semi-color-text-2)' }">请阅读</Text>
<Text :link="{ href: 'https://semi.design/', target: '_blank' }">须知</Text>
</Space>
</template>
</DatePicker>
<br />
<br />
<DatePicker density="compact" dropdownClassName="components-datepicker-demo-slot" placeholder="小尺寸">
<template #topSlot>
<Tabs v-model:activeKey="activeTab" size="small" :style="{ padding: '8px 12px 0' }" @change="date = undefined">
<TabPane itemKey="1">
<template #tab>UED 排期</template>
</TabPane>
<TabPane itemKey="2">
<template #tab>测试排期</template>
</TabPane>
</Tabs>
</template>
<template #bottomSlot>
<Space :style="{ padding: '8px 12px' }">
<IconBulb :style="{ color: 'var(--semi-amber-5)' }" />
<Text strong :style="{ color: 'var(--semi-color-text-2)' }">定版前请阅读</Text>
<Text :link="{ href: 'https://semi.design/', target: '_blank' }">发版须知</Text>
</Space>
</template>
</DatePicker>
<br />
<br />
<DatePicker placeholder="请选择时间范围" :style="{ width: '400px' }" type="dateTimeRange">
<template #bottomSlot>
<Space :style="{ padding: '12px 20px' }">
<IconBulb :style="{ color: 'var(--semi-amber-5)' }" />
<Text strong :style="{ color: 'var(--semi-color-text-2)' }">定版前请阅读</Text>
<Text :link="{ href: 'https://semi.design/', target: '_blank' }">发版须知</Text>
</Space>
</template>
</DatePicker>
<br />
<br />
</div>
</template>.components-datepicker-demo-slot {
.semi-tabs-content {
padding: 0;
}
.semi-tabs-bar-line.semi-tabs-bar-top {
border-bottom: none;
}
}
禁用日期选择
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const defaultValue = new Date(2024, 4, 6, 10, 30, 0);
</script>
<template>
<DatePicker :defaultValue="defaultValue" disabled type="dateTime" />
</template>禁用部分日期或时间
传入 disabledDate 可以禁用指定日期,传入 disabledTime 可以禁用指定时间,配合 defaultPickerValue 可以指定面板打开时所处的年月。
disabledDate 和 disabledTime,接受的入参都为当前日期,前者返回一个 boolean 值,后者返回一个对象,将会透传给 TimePicker 组件。
禁用时间:禁用今天下午5-6点
禁用时间:两个面板禁用不同时间
禁用日期:禁用下个月28号之前的所有日期
代码
<script setup lang="ts">
import * as dateFns from 'date-fns';
import { range } from 'es-toolkit';
import { DatePicker, type DatePickerDisabledDateType, type DatePickerDisabledTimeType } from '@fibrous/semi-ui-vue';
const nextValidMonth = new Date();
nextValidMonth.setMonth((nextValidMonth.getMonth() + 1) % 12);
const disabledTime: DatePickerDisabledTimeType = (date) =>
// With type dateTime, date is a single Date
dateFns.isToday(date as Date)
? {
disabledHours: () => [17, 18],
disabledMinutes: (hour) => (19 === hour ? range(0, 10, 1) : []),
disabledSeconds: (hour, minute) => (hour === 20 && minute === 20 ? range(0, 20, 1) : []),
}
: {};
const disabledTime2: DatePickerDisabledTimeType = (_date, panelType) => (panelType === 'left' ? { disabledHours: () => [17, 18] } : { disabledHours: () => [12, 13, 14, 15, 16, 17, 18] });
const disabledDate: DatePickerDisabledDateType = (date) => {
const deadDate = new Date();
const month = deadDate.getMonth();
deadDate.setDate(28);
deadDate.setMonth((month + 1) % 12);
return !!date && date.getTime() < deadDate.getTime();
};
</script>
<template>
<div>
<div>
<h4>禁用时间:禁用今天下午5-6点</h4>
<DatePicker :disabledTime="disabledTime" :hideDisabledOptions="false" type="dateTime" />
</div>
<div>
<h4>禁用时间:两个面板禁用不同时间</h4>
<DatePicker :disabledTime="disabledTime2" :hideDisabledOptions="false" :style="{ width: '400px' }" type="dateTimeRange" />
</div>
<div>
<h4>禁用日期:禁用下个月28号之前的所有日期</h4>
<DatePicker :defaultPickerValue="nextValidMonth" :disabledDate="disabledDate" :style="{ width: '400px' }" type="dateTimeRange" />
</div>
</div>
</template>在 type 包含 range 时,可以根据当前选择动态禁止日期。options 参数 1.9.0 后支持。
动态禁用日期:禁止选择之前的日期
代码
<script setup lang="ts">
import * as dateFns from 'date-fns';
import { DatePicker, type DatePickerDisabledDateType } from '@fibrous/semi-ui-vue';
const disabledDate: DatePickerDisabledDateType = (date, options) => {
if (!date || !options?.rangeStart) {
return false;
}
return dateFns.isBefore(date, dateFns.parseISO(options.rangeStart));
};
</script>
<template>
<div>
<h4>动态禁用日期:禁止选择之前的日期</h4>
<DatePicker :disabledDate="disabledDate" :style="{ width: '260px' }" type="dateRange" />
</div>
</template>范围选择时,可以根据 focus 状态禁用日期。focus 状态通过 options 中的 rangeInputFocus 参数传递。
开始日期禁用今天前2日和后2日,结束日期禁用今天前3天和后3天
代码
<script setup lang="ts">
import * as dateFns from 'date-fns';
import { DatePicker, type DatePickerDisabledDateType } from '@fibrous/semi-ui-vue';
const today = new Date();
const disabledDate: DatePickerDisabledDateType = (date, options) => {
if (!date) {
return false;
}
const rangeInputFocus = options?.rangeInputFocus;
const baseDate = dateFns.set(today, { hours: 0, minutes: 0, seconds: 0, milliseconds: 0 });
if (rangeInputFocus === 'rangeStart') {
return dateFns.subDays(baseDate, 2) <= date && date <= dateFns.addDays(baseDate, 2);
} else if (rangeInputFocus === 'rangeEnd') {
return dateFns.subDays(baseDate, 3) <= date && date <= dateFns.addDays(baseDate, 3);
}
return false;
};
</script>
<template>
<div>
<h4>开始日期禁用今天前2日和后2日,结束日期禁用今天前3天和后3天</h4>
<DatePicker :defaultPickerValue="today" :disabledDate="disabledDate" :motion="false" type="dateRange" />
</div>
</template>自定义显示格式
可以通过 format 自定义显示格式
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const defaultValue = new Date(2024, 4, 6, 10, 30, 0);
</script>
<template>
<DatePicker :defaultValue="defaultValue" format="yyyy年MM月dd日 HH:mm" type="dateTime" />
</template>自定义触发器
默认情况下我们使用 Input 组件作为 DatePicker 组件的触发器,通过 #trigger 作用域插槽你可以自定义这个触发器。
自定义触发器是对触发器的完全自定义,默认的清除按钮将不生效,如果你需要清除功能,请自定义一个清除按钮,点击时调用插槽参数中的 onClear。
插槽参数提供 value、inputValue、placeholder、disabled、size、inputReadOnly、rangeInputFocus、type、format、multiple、autofocus、componentProps,以及 onChange(更新输入文本,与键入相同)、onEnterPress(提交输入文本)、onClear(报告清除按钮的点击)。用户键入之前 inputValue 为 null,此时显示格式化后的 value。插槽参数不含 aria-* 属性,自定义内容需要自行设置可访问名称。
代码
<script setup lang="ts">
import { ref } from 'vue';
import * as dateFns from 'date-fns';
import { IconChevronDown, IconClose } from '@fibrous/semi-icons-vue';
import { Button, ButtonGroup, DatePicker, type DatePickerValueType } from '@fibrous/semi-ui-vue';
const formatToken = 'yyyy-MM-dd';
const date = ref<DatePickerValueType | null | undefined>(new Date(2024, 4, 6, 10, 30, 0));
</script>
<template>
<DatePicker v-model="date" :format="formatToken">
<template #trigger="{ value, placeholder }">
<!-- The clear button is a sibling of the trigger button: buttons cannot nest -->
<ButtonGroup theme="light">
<Button iconPosition="right">
<template #icon>
<IconChevronDown />
</template>
{{ value.length ? dateFns.format(value[0], formatToken) : placeholder }}
</Button>
<Button v-if="date" aria-label="清除" @click.stop="date = null">
<template #icon>
<IconClose />
</template>
</Button>
</ButtonGroup>
</template>
</DatePicker>
</template>代码
<script setup lang="ts">
import { ref } from 'vue';
import * as dateFns from 'date-fns';
import { IconChevronDown, IconClose } from '@fibrous/semi-icons-vue';
import { Button, ButtonGroup, DatePicker, type DatePickerValueType } from '@fibrous/semi-ui-vue';
const formatToken = 'yyyy-MM-dd HH:mm:ss';
const date = ref<DatePickerValueType>();
function onChange(value: Date | Date[] | undefined) {
console.log(value);
}
</script>
<template>
<DatePicker v-model="date" type="dateTimeRange" @change="onChange">
<template #trigger="{ value }">
<!-- The clear button is a sibling of the trigger button: buttons cannot nest -->
<ButtonGroup theme="light">
<Button iconPosition="right">
<template #icon>
<IconChevronDown />
</template>
{{ value.length ? `${dateFns.format(value[0], formatToken)} ~ ${dateFns.format(value[1], formatToken)}` : '请选择日期时间范围' }}
</Button>
<Button v-if="value.length" aria-label="清除" @click.stop="date = undefined">
<template #icon>
<IconClose />
</template>
</Button>
</ButtonGroup>
</template>
</DatePicker>
</template>自定义日期显示内容
#date="{ dayNumber, fullDate }" 作用域插槽,自定义日期内容。
dayNumber:当前日。如13。fullDate:当前日的完整日期。如2020-08-13。
代码
<script setup lang="ts">
import { DatePicker, Tooltip } from '@fibrous/semi-ui-vue';
const dateStyle = {
width: '100%',
height: '100%',
border: '1px solid var(--semi-color-primary)',
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
};
</script>
<template>
<DatePicker>
<template #date="{ dayNumber }">
<Tooltip v-if="dayNumber === 1">
<div :style="dateStyle">{{ dayNumber }}</div>
<template #content>Always Day 1</template>
</Tooltip>
<template v-else>{{ dayNumber }}</template>
</template>
</DatePicker>
</template>自定义日期格子渲染
#fullDate="{ dayNumber, fullDate, dayStatus }" 作用域插槽,自定义整个日期格子的渲染内容,日期格只保留基础类名和 active 类名。
dayStatus 表示当前格子的状态,包括的 key 有:
type DayStatusType = { isToday?: boolean; // 当前日 isSelected?: boolean; // 被选中 isDisabled?: boolean; // 被禁用 isSelectedStart?: boolean; // 选中开始 isSelectedEnd?: boolean; // 选中结束 isInRange?: boolean; // 范围选中日期内 isHover?: boolean; // 日期在选择项和hover日期之间 isOffsetRangeStart?: boolean; // 周选择开始 isOffsetRangeEnd?: boolean; // 周选择结束 isHoverInOffsetRange?: boolean; // hover在周选择内 };
代码
<script setup lang="ts">
import { DatePicker } from '@fibrous/semi-ui-vue';
const prefix = 'components-datepicker-demo';
const dayStyle = {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
width: '80%',
height: '80%',
borderRadius: 'var(--semi-border-radius-circle)',
};
</script>
<template>
<DatePicker :style="{ width: '260px' }" type="dateRange">
<template #fullDate="{ dayNumber, dayStatus }">
<div
:class="{
[`${prefix}-day-inrange`]: dayStatus.isInRange,
[`${prefix}-day-hover`]: dayStatus.isHover,
[`${prefix}-day-selected`]: dayStatus.isSelected,
[`${prefix}-day-selected-start`]: dayStatus.isSelectedStart,
[`${prefix}-day-selected-end`]: dayStatus.isSelectedEnd,
}"
:style="dayStyle"
>
{{ dayNumber }}
</div>
</template>
</DatePicker>
</template>.components-datepicker-demo-day-inrange,
.components-datepicker-demo-day-hover {
background: var(--semi-color-primary-light-hover);
}
.components-datepicker-demo-day-selected,
.components-datepicker-demo-day-selected-start,
.components-datepicker-demo-day-selected-end {
color: var(--semi-color-bg-2);
background: var(--semi-color-primary);
}
API 参考
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| modelValue | 绑定值,可以是 Date、时间戳或符合 format 的字符串,范围与多选为数组。null 表示受控的空值,undefined 为非受控。 | ValueType | null | undefined |
| defaultValue | 非受控时的初始值。 | ValueType | semiGlobalDefault("DatePicker", "defaultValue") |
| open | 面板显示或隐藏的受控属性,配合 v-model:open 使用。 | boolean | undefined |
| defaultOpen | 面板默认显示或隐藏。 | boolean | semiDefault("DatePicker", "defaultOpen", false) |
| type | 类型,可选 date、dateRange、dateTime、dateTimeRange、month、monthRange、year。 | Type | semiDefault("DatePicker", "type", "date") |
| format | 输入框内展示的日期串格式,默认值与 type 对应。不含时间 token 时,dateTime 按 date、dateTimeRange 按 dateRange 处理。 | string | semiGlobalDefault("DatePicker", "format") |
| defaultPickerValue | 没有值时面板显示的日期,dateTime 类型下也是底部时间的默认值。按内容比较,内容变化时面板回到该日期;每次渲染都传 new Date() 会被视为变化。 | ValueType | semiGlobalDefault("DatePicker", "defaultPickerValue") |
| multiple | 是否可以选择多个日期,仅 type 为 date 时有效。 | boolean | semiDefault("DatePicker", "multiple", false) |
| max | multiple 为 true 时可选的日期个数,不传则不限制。 | number | semiGlobalDefault("DatePicker", "max") |
| needConfirm | 是否需要点击确认才写入值,仅 dateTime 与 dateTimeRange 类型有效。 | boolean | semiDefault("DatePicker", "needConfirm", false) |
| disabled | 是否禁用。 | boolean | semiDefault("DatePicker", "disabled", false) |
| disabledDate | 日期禁止判断方法,返回 true 时禁止该日期。第二个参数提供 rangeStart、rangeEnd 和 rangeInputFocus。type 为 year 时以每年的 1 月 1 日调用,返回 true 时禁止该年。 | DisabledDateType | undefined |
| disabledTime | 时间禁止配置,返回 disabledHours、disabledMinutes、disabledSeconds,参数为当前日期和面板位置。 | DisabledTimeType | undefined |
| disabledTimePicker | 是否禁止时间选择,仅 dateTime 与 dateTimeRange 类型有效。 | boolean | semiDefault("DatePicker", "disabledTimePicker", false) |
| hideDisabledOptions | 隐藏被禁止选择的时间。 | boolean | semiDefault("DatePicker", "hideDisabledOptions", false) |
| startDateOffset | type 为 dateRange 时,单击选择范围的开始日期。 | DateOffsetType | undefined |
| endDateOffset | type 为 dateRange 时,单击选择范围的结束日期。 | DateOffsetType | undefined |
| placeholder | 输入框提示文字,范围类型传数组。默认取语言包中 type 对应的文案。 | string | string[] | semiGlobalDefault("DatePicker", "placeholder") |
| rangeSeparator | 范围类型输入框中的日期分隔符,同时用于解析输入。只改变展示时用 rangeSeparator 插槽。 | string | TypesemiDefault("DatePicker", "rangeSeparator", strings.DEFAULT_SEPARATOR_RANGE) |
| size | 输入框尺寸,可选 small、default、large。 | Size | semiDefault("DatePicker", "size", "default") |
| density | 面板的尺寸,可选 default 或 compact。 | DensityType | semiDefault("DatePicker", "density", "default") |
| borderless | 无边框模式。 | boolean | semiDefault("DatePicker", "borderless", false) |
| showClear | 是否显示清除按钮。 | boolean | semiDefault("DatePicker", "showClear", true) |
| inputReadOnly | 输入框是否只读。 | boolean | semiDefault("DatePicker", "inputReadOnly", false) |
| inputStyle | 输入框根元素的样式。 | StyleValue | semiGlobalDefault("DatePicker", "inputStyle") |
| insetInput | 把输入框嵌入面板,可传对象设置各输入框的占位文字。 | boolean | InsetInputProps | semiDefault("DatePicker", "insetInput", false) |
| insetLabelId | 内嵌标签元素的 id。 | string | undefined |
| validateStatus | 校验状态,可选 default、error、warning,仅影响样式。 | "default" | "error" | "warning" | "success" | semiGlobalDefault("DatePicker", "validateStatus") |
| autofocus | 挂载时聚焦输入框,同时打开面板。 | boolean | semiDefault("DatePicker", "autofocus", false) |
| preventScroll | 聚焦时是否阻止浏览器滚动到输入框。 | boolean | semiGlobalDefault("DatePicker", "preventScroll") |
| weekStartsOn | 每周的第一天,0 为周日,1 为周一,以此类推。 | WeekStartNumber | semiDefault("DatePicker", "weekStartsOn", numbers.WEEK_START_ON) |
| startYear | 年份滚轮的开始年,默认为当前年前 100 年。 | number | semiGlobalDefault("DatePicker", "startYear") |
| endYear | 年份滚轮的结束年,需要大于开始年,默认为当前年后 100 年。 | number | semiGlobalDefault("DatePicker", "endYear") |
| autoSwitchDate | 通过面板上方左右按钮、下拉菜单更改年月时,自动切换日期。仅对 date 类型生效。 | boolean | semiDefault("DatePicker", "autoSwitchDate", true) |
| syncSwitchMonth | 范围选择时,同步切换双面板的月份。 | boolean | semiDefault("DatePicker", "syncSwitchMonth", false) |
| presets | 日期时间快捷方式。数组项以及 start、end 可以是函数,在面板渲染和点击时调用。 | PresetsType | semiGlobalDefault("DatePicker", "presets") |
| presetPosition | 快捷方式面板的位置,可选 left、right、top、bottom。 | "top" | "bottom" | "left" | "right" | semiDefault("DatePicker", "presetPosition", "bottom") |
| timePickerOpts | 传给时间面板的参数:use12Hours、hourStep、minuteStep、secondStep、defaultIsAM、scrollItemProps。格式、值和禁用时间由面板设置。 | TypePartial<Pick<ComboboxProps, "use12Hours" | "hourStep" | "minuteStep" | "secondStep" | "scrollItemProps" | "defaultIsAM">> | semiGlobalDefault("DatePicker", "timePickerOpts") |
| yearAndMonthOpts | 传给年月滚动列的参数:cycled、mode、motion、transform。列表和选中项由面板设置。 | TypePartial<Pick<ScrollItemProps<Item>, "motion" | "mode" | "cycled" | "transform">> | semiGlobalDefault("DatePicker", "yearAndMonthOpts") |
| timeZone | 时区,数字为 UTC 偏移的小时数。未设置时依次取 ConfigProvider 的 timeZone、全局默认值。 | string | number | undefined |
| motion | 是否开启面板展开的动画。 | boolean | semiDefault("DatePicker", "motion", true) |
| autoAdjustOverflow | 浮层被遮挡时是否自动调整方向。 | boolean | semiDefault("DatePicker", "autoAdjustOverflow", true) |
| position | 浮层位置。默认 bottomLeft(RTL 下为 bottomRight),开启 insetInput 时为 leftTopOver。 | Type"top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "leftTop" | "leftBottom" | "rightTop" | "rightBottom" | "bottomLeft" | "bottomRight" | "leftTopOver" | "rightTopOver" | "leftBottomOver" | "rightBottomOver" | semiGlobalDefault("DatePicker", "position") |
| spacing | 浮层与触发器的距离。开启 insetInput 且面板覆盖触发器时为 1,否则为 Popover 的默认间距。 | number | semiGlobalDefault("DatePicker", "spacing") |
| stopPropagation | 是否阻止浮层上的点击事件冒泡。 | string | boolean | semiDefault("DatePicker", "stopPropagation", true) |
| dropdownClassName | 浮层的类名。 | string | semiGlobalDefault("DatePicker", "dropdownClassName") |
| dropdownStyle | 浮层的内联样式。 | StyleValue | semiGlobalDefault("DatePicker", "dropdownStyle") |
Events
| 事件 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 值变化时触发,用于 v-model。清空时单选为 undefined,范围与多选为 []。 | [value: Date | Date[] | undefined] |
| change | 值变化时触发,参数为日期和日期字符串,范围与多选时两者都是数组。范围类型在起止日期都选好后才触发。遮住根元素上冒泡的原生 change。 | [date: Date | Date[] | undefined, dateString: string | string[]] |
| update:open | 面板打开或关闭时触发,用于 v-model:open。 | [open: boolean] |
| openChange | 面板打开或关闭时触发,与 update:open 同时发出。 | [open: boolean] |
| focus | 输入框获得焦点,或点击、按键使范围起始输入框获得焦点时触发;rangeType 只在范围输入框聚焦时有值,范围内两个输入框之间移动不再触发。遮住原生 focus。 | Type[event: MouseEvent | FocusEvent | KeyboardEvent, rangeType?: RangeInput | undefined] |
| blur | 面板关闭时触发。点击外部关闭时参数为那次 mousedown,确认、选中日期、Esc 等其他关闭方式不带参数。遮住原生 blur。 | [event?: MouseEvent | undefined] |
| clear | 点击清除按钮时触发。 | [event: MouseEvent] |
| cancel | 取消选择时触发,参数为上次确认的值,仅 needConfirm 时有效。 | [date: Date | Date[], dateString: string | string[]] |
| confirm | 确认选择时触发,参数为当前选择的值,仅 needConfirm 时有效。 | [date: Date | Date[], dateString: string | string[]] |
| panelChange | 面板的年份或月份切换时触发。 | [date: Date | Date[], dateString: string | string[]] |
| presetClick | 点击快捷方式按钮时触发,第二个参数是原生 MouseEvent。 | [item: PresetType, event: MouseEvent] |
| clickOutSide | 面板打开时点击浮层和触发器之外的区域触发,参数为原生 mousedown 事件。 | [event: MouseEvent] |
Slots
| 插槽 | 说明 | 作用域参数 |
|---|---|---|
| trigger | 完全自定义触发器,参数含 value、inputValue、placeholder、disabled、size、inputReadOnly、rangeInputFocus、type、format、multiple、autofocus、componentProps,以及 onChange(更新输入文本)、onEnterPress(提交输入文本)、onClear。默认的清除按钮不再生效。 | DatePickerTriggerSlotProps |
| date | 自定义日期格子的内容,参数为 dayNumber 和 fullDate(yyyy-MM-dd)。 | DatePickerDateSlotProps |
| fullDate | 自定义整个日期格子,参数为 dayNumber、fullDate 和 dayStatus。日期格只保留基础类名和 active 类名。 | DatePickerFullDateSlotProps |
| topSlot | 面板顶部的额外区域。 | any |
| bottomSlot | 面板底部的额外区域。 | any |
| leftSlot | 面板左侧的额外区域。 | any |
| rightSlot | 面板右侧的额外区域。 | any |
| prefix | 输入框的前缀内容。 | any |
| insetLabel | 输入框的内嵌标签。 | any |
| clearIcon | 自定义清除图标,showClear 为 true 时有效。 | any |
| rangeSeparator | 自定义范围输入框分隔符的展示,不影响解析。 | any |
Exposes
| 名称 | 说明 | 类型 |
|---|---|---|
| close | 关闭面板;受控的 open 优先。 | Type() => void |
| focus | 聚焦输入框,范围类型默认聚焦开始框,传 rangeEnd 聚焦结束框。开启 insetInput 时聚焦面板内的输入框。 | Type(focusType?: RangeInput | undefined) => void |
| blur | 输入框失焦。 | Type() => void |
modelValue 配合 update:modelValue 即 v-model,open 配合 update:open 即 v-model:open。autofocus 是小写,triggerRender、renderDate、renderFullDate、rangeSeparatorNode 及各 ReactNode 属性改为插槽。
class、style 与 id、title、data-*、aria-label 等未声明的属性落在根元素上,带 aria-label 的根元素为 role="group"。aria-labelledby、aria-describedby、aria-errormessage、aria-invalid、aria-required 的落点:
- 单输入框:都落在输入框上
- 范围类型:根元素为
role="group",aria-labelledby落在根元素上,其余四项落在两个输入框上 #trigger的内容没有可聚焦元素:aria-labelledby、aria-describedby、aria-errormessage、aria-invalid落在 role 为button的外层,aria-required不转发#trigger的内容自带可聚焦元素:都不转发,在插槽内容上自行设置
change、focus、blur 遮住根元素上冒泡的同名原生事件。放在 <KeepAlive> 中失活时面板关闭,只触发 update:open 与 openChange。
Methods
通过模板 ref 暴露 open()、close()、focus(rangeEnd?) 和 blur():focus 聚焦输入框,范围类型默认聚焦开始框,传 rangeEnd 聚焦结束框,开启 insetInput 时聚焦面板内的输入框;blur 使输入框失焦。受控的 open 优先,受控时 open()、close() 不改变面板可见性。
代码
<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { Button, DatePicker, Space, type DatePickerHandle } from '@fibrous/semi-ui-vue';
const picker = useTemplateRef<DatePickerHandle>('picker');
const handleClickOutside = () => {
console.log('click outside');
};
</script>
<template>
<Space align="start" vertical>
<Space>
<Button @click="picker?.open()">open</Button>
<Button @click="picker?.close()">close</Button>
<Button @click="picker?.focus()">focus</Button>
<Button @click="picker?.blur()">blur</Button>
</Space>
<div>
<DatePicker ref="picker" type="dateTime" @clickOutSide="handleClickOutside" />
</div>
</Space>
</template>类型定义
type DatePickerBaseValueType = string | number | Date;
type DatePickerValueType = DatePickerBaseValueType | DatePickerBaseValueType[];
type DatePickerType = 'date' | 'dateRange' | 'dateTime' | 'dateTimeRange' | 'month' | 'monthRange' | 'year';
type DatePickerRangeInput = 'rangeStart' | 'rangeEnd';
type DatePickerTriggerSlotProps = {
value: Date[];
inputValue: string | null;
placeholder: string | string[];
disabled: boolean;
size: InputSize;
inputReadOnly: boolean;
rangeInputFocus: DatePickerRangeInput | false | undefined;
type: DatePickerType;
format?: string;
multiple: boolean;
autofocus: boolean;
componentProps: DatePickerProps;
onChange: (inputValue: string) => void;
onEnterPress: (inputValue: string) => void;
onClear: (event: MouseEvent) => void;
};
Accessibility
ARIA
- 输入框的 role 为
combobox,带aria-haspopup="dialog"、随面板开关变化的aria-expanded,aria-controls指向面板;范围选择的两个输入框都是如此 - 单输入框未选中日期时
aria-label为Choose date,选中日期时为Change date(传入aria-labelledby时以它为准) - 自定义触发器(React 的
triggerRender,Vue 的#trigger插槽)渲染的内容没有可聚焦元素时,外层是 role 为button的焦点目标,名称同上 - 日期面板中月的 role 为
grid,以面板顶部的年月标题命名,周的 role 设置为row,日期格子设置为gridcell - 年、月滚动列是 role 为
listbox的列表,名称为「年」「月」 - 日期和时间禁用时对应选项的
aria-disabled为 true - 多选或范围选择时,月的
aria-multiselectable为 true,选中时日期格子的aria-selected为 true - 面板中一些装饰作用的 icon,它们的
aria-hidden为 true
键盘和焦点
- 输入框聚焦时按
下箭头打开面板;面板打开后再按下箭头,焦点移入面板 - 日期网格是一个 Tab 停靠点,
方向键、Home、End、PageUp、PageDown(加Shift按年)移动当前日期,Enter或空格选中 - dateTime 面板底部的日期、时间切换是按钮,
Enter或空格切换 - 范围选择有值时,Tab 可以到达结束输入框之后的清除按钮,
Enter或空格清空 - 按
Esc关闭面板;焦点在面板内时回到输入框,使用自定义触发器时回到该触发器 - 自定义触发器渲染的内容没有可聚焦元素时,外层可以用 Tab 到达,
Enter、空格或下箭头打开面板
文案规范
- 日期选择器建议搭配标签使用
- 使用简洁的标签来表明日期选择所指的内容
- 日期选择器中日期格式请参考日期与时间的规范
设计变量
| Sass 变量 | 值 | 用法 |
|---|---|---|
| $width-datepicker_day | 36px | 日期格子及星期标题尺寸 |
| $width-datepicker_day_main | 32px | 日期格子内容尺寸 |
| $width-datepicker_month | $width-datepicker_day * 7 | 日期视图单月面板宽度 |
| $width-datepicker_nav | 32px | 顶部导航栏高度 |
| $height-datepicker_switch | 54px | 日期时间切换高度 |
| $height-datepicker_timeType_yam | calc(100% - 54px) | 时间面板高度 |
| $height-datepicker_timeType_tpk | calc(100% - 54px) | 时间面板高度 |
| $height-datepicker_panel_yam_scrolllist | 266px | 年月选择列表滚动区域高度 |
| $width-datepicker_monthPanel_max | 284px | 年月选择器最大宽度 |
| $width-datepicker_monthRangePanel_max | 384px | 年月选择器最大宽度 |
| $height-datepicker_timepicker_header_min | 24px | 年月选择面板顶部导航栏最小高度 |
| $width-datepicker_navigation_button_min | 32px | 顶部导航栏按钮最小宽度 |
| $height-datepicker_yamShowing_min | 378px | 日期时间选择器菜单最小高度 |
| $width-datepicker_yamShowing_min | 284px | 选择器菜单最小宽度 |
| $height-datepicker_dateType_yamShowing_min | 325px | 日期选择器菜单最小高度 |
| $width-datepicker_panel_yam_scrolllist_li_min | 64px | 年月、时间滚动菜单项最小高度 |
| $width-datepicker_presetPanel_left_and_right | 200px | 左右方位快捷选择面板宽度 |
| $height-datepicker_presetPanel_top_and_bottom_max | 100px | 上下方位快捷选择面板最大高度 |
| $width-datepicker_presetPanel_scroll_bar | 15px | 快捷选择面板scrollbar宽度 |
| $width-datepicker-border | $border-thickness-control | 年月选择面板顶部导航栏底部分割线宽度 |
| $width-datepicker_yam_header-borderRadius | var(--semi-border-radius-medium) | 年月选择面板顶部导航栏圆角 |
| $width-datepicker_day_main-borderRadius | var(--semi-border-radius-small) | 日期格子圆角 |
| $width-datepicker_slot-border | 1px | 日期星期分割线宽度 |
| $width-datepicker_range_input-border | $border-thickness-control-focus | |
| $width-datepicker_day_main-border | 1px | |
| $height-datepicker_timeType_insetInput_yam | 100% | 时间面板高度 - 内嵌输入框 |
| $height-datepicker_timeType_insetInput_tpk | 100% | 时间面板高度 - 内嵌输入框 |
| $width-datepicker_insetInput_date_type_wrapper | 284px | 日期类型内嵌输入框宽度 |
| $width-datepicker_insetInput_date_range_type_wrapper | $width-datepicker_insetInput_date_type_wrapper * 2 | 范围选择内嵌输入框宽度 |
| $width-datepicker_insetInput_month_type_wrapper | 165px | 月份类型内嵌输入框宽度 |
| $width-datepicker_insetInput_month_range_type_wrapper | 331px | 年月范围类型内嵌输入框宽度 |
| $height-datepicker_insetInput_separator | 32px | |
| $height-datepicker_month_grid_yearType_insetInput | 317px | |
| $height-datepicker_month_grid_timeType_insetInput | 317px | |
| $width-datepicker_range_trigger-border | 0px | 触发器边框宽度 |
| $spacing-datepicker_day-marginX | ($width-datepicker_day - $width-datepicker_day_main) * 0.5 | 日期格子水平外边距 |
| $spacing-datepicker_yam_header-paddingX | $spacing-base | 年月选择面板顶部导航栏水平内边距 |
| $spacing-datepicker_yam_header-paddingY | $spacing-base-tight | 年月选择面板顶部导航栏垂直内边距 |
| $spacing-datepicker_scrolllist_header-padding | $spacing-base | 时间选择 header 内边距 |
| $spacing-datepicker_scrolllist_body-padding | 0 | 时间选择滚动菜单内边距 |
| $spacing-datepicker_footer-paddingTop | 10px | 确认选择 footer 顶部内边距 |
| $spacing-datepicker_footer-paddingBottom | 10px | 确认选择 footer 底部内边距 |
| $spacing-datepicker_footer-paddingRight | 8px | 确认选择 footer 右侧内边距 |
| $spacing-datepicker_footer_cancel_button-marginRight | 12px | 确认选择 footer 取消按钮右外边距 |
| $spacing-datepicker_footer_confirm_button-marginRight | 8px | 确认选择 footer 确认按钮右外边距 |
| $spacing-datepicker_navigation-paddingY | $spacing-base-tight | 年月切换 header 垂直内边距 |
| $spacing-datepicker_navigation-paddingX | $spacing-base | 年月切换 header 水平内边距 |
| $spacing-datepicker_month-padding | $spacing-base | |
| $spacing-datepicker_switch_datetime-paddingTop | $spacing-base | 日期时间切换顶部内边距 |
| $spacing-datepicker_switch_datetime-paddingBottom | $spacing-base | 日期时间切换底部内边距 |
| $spacing-datepicker_switch_text-paddingLeft | $spacing-tight | 日期时间切换左侧内边距 |
| $spacing-datepicker_quick_control_header-paddingTop | 18px | 快捷预设面板标题区域上内边距 |
| $spacing-datepicker_quick_control_top_and_bottom_content-paddingX | $spacing-base-loose | 上下方位快捷操作面板, 左右内边距,默认20px |
| $spacing-datepicker_quick_control_content-paddingX | 12px | 快捷面板内容,左右内边距 |
| $spacing-datepicker_quick_control_content-marginTop | 14px | 快捷面板内容,上边距 |
| $spacing-datepicker_quick_control_item-margin | $spacing-tight | 快捷操作面板按钮间距 |
| $spacing-datepicker_range_input-paddingX | 8px | |
| $spacing-datepicker_range_input_inputWrapper_input-paddingY | 2px | |
| $spacing-datepicker_range_input_inputWrapper_input-paddingX | 4px | |
| $spacing-datepicker_range_input_prefix-paddingLeft | 12px | |
| $spacing-datepicker_range_input_prefix-paddingRight | 8px | |
| $spacing-datepicker_range_input_suffix-paddingLeft | 8px | |
| $spacing-datepicker_range_input_suffix-paddingRight | 12px | |
| $spacing-datepicker_range_input_clearbtn-paddingLeft | 8px | |
| $spacing-datepicker_range_input_clearbtn-paddingRight | 12px | |
| $spacing-datepicker_navigation_insetInput-paddingY | 8px | 年月切换 header 垂直内边距 - 内嵌输入框 |
| $spacing-datepicker_insetInput_wrapper-margin | 8px | |
| $spacing-datepicker_insetInput_wrapper-paddingY | 12px | |
| $spacing-datepicker_insetInput_wrapper-paddingX | 16px | |
| $spacing-datepicker_insetInput_wrapper-paddingBottom | 0 | |
| $spacing-datepicker_insetInput_separator-paddingY | 0 | |
| $spacing-datepicker_insetInput_separator-paddingX | 4px | |
| $color-datepicker_header-bg-default | var(--semi-color-bg-3) | 日期选择器 header 背景颜色 |
| $color-datepicker_list-bg-default | var(--semi-color-bg-3) | 日期选择器滚动列表背景颜色 |
| $color-datepicker_border-bg-default | var(--semi-color-border) | 日期选择器描边颜色 |
| $color-datepicker_footer-bg-default | var(--semi-color-fill-0) | 日期选择器确认选择 footer 背景颜色 |
| $color-datepicker_quick-bg-default | transparent | 日期选择器快捷操作背景颜色 |
| $color-datepicker_quick_button-text-default | var(--semi-color-primary) | 日期选择器快捷操作按钮文字颜色 |
| $color-datepicker_day-text-default | var(--semi-color-text-2) | 星期标题及日期时间切换按钮文字颜色 - 默认 |
| $color-datepicker_day-text-active | var(--semi-color-text-0) | 日期时间切换文字颜色 - 选中 |
| $color-datepicker_date-text-default | var(--semi-color-text-0) | 日期格子文字颜色 - 默认 |
| $color-datepicker_date-bg-default | var(--semi-color-fill-0) | 日期格子背景颜色 - 默认 |
| $color-datepicker_date-bg-hover | var(--semi-color-fill-0) | 日期格子背景颜色 - 悬浮 |
| $color-datepicker_date-bg-active | var(--semi-color-fill-1) | 日期格子背景颜色 - 按下 |
| $color-datepicker_date_selected-text-default | var(--semi-color-white) | 日期格子文字颜色 - 选中 |
| $color-datepicker_date_selected-bg-default | var(--semi-color-primary) | 日期格子背景颜色 - 选中 |
| $color-datepicker_date_disabled-text-default | var(--semi-color-disabled-text) | 禁用日期格子文字颜色 |
| $color-datepicker_date_disabled-bg-default | var(--semi-color-disabled-fill) | 禁用日期格子背景颜色 |
| $color-datepicker_date_today-text-default | var(--semi-color-primary) | 今日文字颜色 |
| $color-datepicker_date_today_disabled-text-default | var(--semi-color-primary-disabled) | 今日文字颜色 - 禁用 |
| $color-datepicker_date_inHover-bg-default | var(--semi-color-primary-light-default) | 范围选择日期格子颜色 |
| $color-datepicker_date_inRangeHover-bg-default | var(--semi-color-fill-0) | 范围选择时悬停路径内的日期背景色 |
| $color-datepicker_date_hoverDay-bg-default | var(--semi-color-fill-1) | 范围选择时日期格子背景色 - 悬停 |
| $color-datepicker_date_selectedRange-bg-hover | var(--semi-color-primary-light-hover) | 范围选择日期格子颜色 - 悬浮 |
| $color-datepicker_date_hoverday_range-bg-default | var(--semi-color-primary-light-active) | |
| $color-datepicker_date_hoverday_around_single_selected-bg-default | var(--semi-color-primary-light-active) | |
| $color-datepicker_nav_monthIcon-text-default | var(--semi-color-text-0) | 顶部导航栏年月文字颜色 - 默认 |
| $color-datepicker_navIcon-text-default | var(--semi-color-text-2) | 日期选择器 header 左右箭头颜色 |
| $color-datepicker_input_primary-text-default | var(--semi-color-primary) | |
| $color-datepicker_range_input-text-default | var(--semi-color-text-2) | |
| $color-datepicker_range_input-bg-default | var(--semi-color-fill-0) | |
| $color-datepicker_range_input-bg-hover | var(--semi-color-fill-1) | |
| $color-datepicker_range_input-border-default | transparent | |
| $color-datepicker_range_input-border-active | var(--semi-color-focus-border) | |
| $color-datepicker_range_input_warning-border-active | var(--semi-color-warning) | |
| $color-datepicker_range_input_warning-bg-active | var(--semi-color-warning-light-hover) | |
| $color-datepicker_range_input_warning-bg-default | var(--semi-color-warning-light-default) | |
| $color-datepicker_range_input_warning-bg-hover | var(--semi-color-warning-light-hover) | |
| $color-datepicker_range_input_warning-border-default | var(--semi-color-warning-light-default) | |
| $color-datepicker_range_input_error-border-default | var(--semi-color-danger-light-default) | |
| $color-datepicker_range_input_error-bg-hover | var(--semi-color-danger-light-hover) | |
| $color-datepicker_range_input_error-border-active | var(--semi-color-danger) | |
| $color-datepicker_range_input_error-bg-active | var(--semi-color-danger-light-hover) | |
| $color-datepicker_range_input_disabled-text-default | var(--semi-color-disabled-text) | |
| $color-datepicker_range_input_disabled-bg-default | var(--semi-color-disabled-fill) | |
| $color-datepicker_range_input_disabled-bg-hover | var(--semi-color-disabled-fill) | |
| $color-datepicker_range_input_clearbtn-icon-hover | var(--semi-color-primary-hover) | |
| $color-datepicker_range_input_inputWrapper-border-default | transparent | |
| $color-datepicker_range_input_inputWrapper-bg-default | transparent | |
| $color-datepicker_range_input_inputWrapper-bg-focus | var(--semi-color-fill-1) | |
| $color-datepicker_range_input_separator-text-active | var(--semi-color-text-0) | |
| $color-datepicker_day_main-border | var(--semi-color-primary-active) | |
| $color-datepicker_insetInput_separator | var(--semi-color-text-3) | |
| $color-datepicker_range_trigger-border | transparent | 范围日期选择模式触发器边框颜色 |
| $color-datepicker_range_trigger-border-hover | transparent | 范围日期选择模式触发器边框颜色 - 悬浮 |
| $color-datepicker_range_trigger-border-active | transparent | 范围日期选择模式触发器边框颜色 - 激活 |
| $color-datepicker_range_trigger-border-focus | transparent | 范围日期选择模式触发器边框颜色 - 聚焦 |
| $font-datepicker_range_input_prefix_suffix_clearbtn-fontWeight | 600 | |
| $font-datepicker_preset_header-fontWeight | 600 | |
| $font-datepicker_range_input_prefix_suffix_clearbtn-fontSize | 14px | |
| $font-datepicker_range_input_prefix_suffix_clearbtn-lineHeight | 20px | |
| $font-datepicker_range_input_large-fontSize | 16px | |
| $spacing-datepicker_month_compact-padding | 10px | |
| $width-datepicker_day_compact | 28px | |
| $width-datepicker_day_main_compact | 24px | |
| $width-datepicker_day_compact-borderRadius | 4px | |
| $width-datepicker_month_compact | $width-datepicker_day_compact * 7 + $spacing-datepicker_month_compact-padding * 2 | |
| $width-datepicker_nav_compact | 24px | |
| $width-datepicker_panel_compact | 216px | |
| $height-datepicker_switch_compact | 32px | |
| $height-datepicker_tpk_compact | 256px | |
| $height-datepicker_yam_panel_compact | 256px | |
| $height-datepicker_yam_li_compact | 32px | |
| $height-datepicker_yam_panel_header_compact | 48px | |
| $radius-datepicker_range_input_inputWrapper | var(--semi-border-radius-small) | |
| $height-datepicker_range_input-default | 32px | |
| $height-datepicker_range_input-small | 24px | |
| $height-datepicker_range_input-large | 40px | |
| $width-datepicker_insetInput_date_type_wrapper_compact | 216px | |
| $width-datepicker_insetInput_date_range_type_wrapper_compact | $width-datepicker_insetInput_date_type_wrapper_compact * 2 | |
| $width-datepicker_insetInput_month_type_wrapper_compact | 195px | |
| $height-datepicker_insetInput_tpk_compact | 100% | |
| $height-datepicker_timeType_insetInput_yam_compact | 100% | |
| $height-datepicker_insetInput_wrapper_compact | 28px | |
| $lineHeight-datepicker_compact | 20px | |
| $lineHeight-datepicker_weekday_item_compact | 28px | |
| $height-datepicker_insetInput_compact | 26px | |
| $fontSize-datepicker_insetInput_compact-fontSize | 12px | |
| $spacing-datepicker_switch_compact-padding | 6px | |
| $spacing-datepicker_day_compact-margin | ($width-datepicker_day_compact - $width-datepicker_day_main_compact) * 0.5 | |
| $spacing-datepicker_weeks_compact-padding | 10px | |
| $spacing-datepicker_weeks_compact-paddingTop | $spacing-tight - 2px | |
| $spacing-datepicker_weekday_compact-paddingLeft | 10px | |
| $spacing-datepicker_weekday_compact-paddingRight | 10px | |
| $spacing-datepicker_weekday_compact-paddingBottom | $spacing-tight | |
| $spacing-datepicker_nav_compact-padding | 12px | |
| $spacing-datepicker_yam_panel_header_compact-padding | 12px | |
| $spacing-datepicker_footer_compact-paddintTop | 10px | |
| $spacing-datepicker_footer_compact-paddintBottom | 10px | |
| $spacing-datepicker_footer_compact-paddintRight | 8px | |
| $spacing-datepicker_scrolllist_shade_pre_compact-marginTop | -17px | |
| $spacing-datepicker_scrolllist_shade_post_compact-marginTop | 17px | |
| $spacing-datepicker_insetInput_wrapper_compact-margin | 4px | |
| $spacing-datepicker_insetInput_wrapper_compact-paddingY | 8px | |
| $spacing-datepicker_insetInput_wrapper_compact-paddingX | 8px | |
| $spacing-datepicker_insetInput_wrapper_compact-paddingBottom | 0 | |
| $spacing-datepicker_insetInput_wrapper_rangeType_compact-paddingTop | 0 | |
| $spacing-datepicker_quick_control_header_compact-paddingTop | 16px | compact, 快捷面板标题,上内边距 |
| $spacing-datepicker_quick_control_content_compact-marginTop | 12px | compact, 快捷面板内容,上边距 |
| $spacing-datepicker_quick_control_left_and_right_content_compact-paddingX | 12px | compact,左右方位,快捷面板内容,左右内边距 |
| $spacing-datepicker_quick_control_top_and_bottom_content_compact-paddingX | 10px | compact,上下方位,快捷面板内容,左右内边距 |
| $radius-datepicker_range_input | var(--semi-border-radius-small) | |
| $transition-datepicker_range_input | background-color 0.16s ease-in-out | |
| $width-datepicker_presetPanel_left_and_right_content | $width-datepicker_presetPanel_left_and_right - $spacing-datepicker_quick_control_content-paddingX * 2 | 左右方位快捷选择面板,内容宽度 |
| $width-datepicker_presetPanel_top_and_bottom_content_date | $width-datepicker_day * 7 + $spacing-datepicker_month-padding * 2 - $spacing-datepicker_quick_control_top_and_bottom_content-paddingX * 2 | date/dateTime下, 上下方位快捷选择面板内容宽度, 默认(284 - 40)px |
| $width-datepicker_presetPanel_top_and_bottom_content_range | ($width-datepicker_day * 7 + $spacing-datepicker_month-padding * 2) * 2 - $spacing-datepicker_quick_control_top_and_bottom_content-paddingX * 2 | dateRange/dateTimeRange下, 上下方位快捷选择内容面板宽度,默认528px |
| $width-datepicker_presetPanel_top_and_bottom_content_month | 165px - $spacing-datepicker_quick_control_top_and_bottom_content-paddingX * 2 | month下,上下方位快捷选择内容面板宽度, 默认154px |
| $height-datepicker_month_max | $width-datepicker_day * 7 + 1px | 年月面板最大高度, 最多6 + 1行,再加上一个border宽度, 默认253px |
| $height-datepicker_month_max_compact | $width-datepicker_day_compact * 7 + $spacing-datepicker_weeks_compact-paddingTop + $spacing-datepicker_weeks_compact-padding + $spacing-datepicker_weekday_compact-paddingBottom | 年月面板最大高度, 最多6 + 1行,再加上padding,默认220px |
| $height-datepicker_date_panel | $height-datepicker_month_max + $spacing-datepicker_month-padding + $width-datepicker_nav + $spacing-datepicker_navigation-paddingY * 2 | date/dateRange,面板渲染最大高度,默认325px |
| $height-datepicker_date_time_panel | $height-datepicker_date_panel + $height-datepicker_switch - 1px | dateTime/dateTImeRange 面板渲染最大高度. 默认378px |
| $height-datepicker_presetPanel_left_and_right_except_content | 20px + $spacing-datepicker_quick_control_header-paddingTop + $spacing-datepicker_quick_control_content-marginTop | 除去content以外的高度,默认52px |
| $width-datepicker_presetPanel_top_and_bottom_content_date_compact | $width-datepicker_day_compact * 7 + $spacing-datepicker_weeks_compact-padding * 2 - $spacing-datepicker_quick_control_top_and_bottom_content_compact-paddingX * 2 | date/dateTime下, 上下方位快捷选择面板内容宽度, 默认(216 - 20)px |
| $width-datepicker_presetPanel_top_and_bottom_content_range_compact | ($width-datepicker_day_compact * 7 + $spacing-datepicker_weeks_compact-padding * 2) * 2 - $spacing-datepicker_quick_control_top_and_bottom_content_compact-paddingX * 2 | dateRange/dateTimeRange下, 上下方位快捷选择内容面板宽度,默认412px |
| $width-datepicker_presetPanel_top_and_bottom_content_month_compact | 165px - $spacing-datepicker_quick_control_top_and_bottom_content_compact-paddingX * 2 | month下,上下方位快捷选择内容面板宽度, 默认174px |
| $height-datepicker_date_panel_compact | $height-datepicker_month_max_compact + $width-datepicker_nav_compact + $spacing-datepicker_nav_compact-padding | compact,date/dateRange,面板渲染最大高度,默认256px |
| $height-datepicker_date_time_panel_compact | $height-datepicker_date_panel_compact + $height-datepicker_switch_compact | compact,dateTime/dateTImeRange,面板渲染最大高度,默认288px |
| $height-datepicker_presetPanel_left_and_right_except_content_compact | 20px + $spacing-datepicker_quick_control_header_compact-paddingTop + $spacing-datepicker_quick_control_content_compact-marginTop | compact,除去content以外的高度,默认48px |
| $width-datepicker_presetPanel_left_and_right_two_col_button | ($width-datepicker_presetPanel_left_and_right_content - $spacing-datepicker_quick_control_item-margin) * 0.5 | 左右方位快捷选择面板,固定两列,按钮宽度 |
| $width-datepicker_presetPanel_top_and_bottom_three_col_button | ($width-datepicker_presetPanel_top_and_bottom_content_date - $spacing-datepicker_quick_control_item-margin * 2) * 0.333 | 上下方位快捷选择面板,固定三列,按钮宽度 |
| $width-datepicker_presetPanel_top_and_bottom_five_col_button | ($width-datepicker_presetPanel_top_and_bottom_content_range - $spacing-datepicker_quick_control_item-margin * 4) * 0.2 | 上下方位快捷选择面板,固定五列,按钮宽度 |
| $width-datepicker_presetPanel_top_and_bottom_two_col_button | ($width-datepicker_presetPanel_top_and_bottom_content_month - $spacing-datepicker_quick_control_item-margin) * 0.5 | 上下方位快捷选择面板,固定两列,按钮宽度 |
| $width-datepicker_presetPanel_top_and_bottom_three_col_button_compact | ($width-datepicker_presetPanel_top_and_bottom_content_date_compact - $spacing-datepicker_quick_control_item-margin * 2) * 0.333 | 上下方位快捷选择面板,固定三列,按钮宽度 |
| $width-datepicker_presetPanel_top_and_bottom_five_col_button_compact | ($width-datepicker_presetPanel_top_and_bottom_content_range_compact - $spacing-datepicker_quick_control_item-margin * 4) * 0.2 | 上下方位快捷选择面板,固定五列,按钮宽度 |
| $width-datepicker_presetPanel_top_and_bottom_two_col_button_compact | ($width-datepicker_presetPanel_top_and_bottom_content_month_compact - $spacing-datepicker_quick_control_item-margin) * 0.5 | 上下方位快捷选择面板,固定两列,按钮宽度 |
| $height-datepicker_inset_input | 32px + $spacing-datepicker_insetInput_wrapper-paddingY | 默认尺寸,insetInput高度 |
| $height-datepicker_preset_panel_inset_input | $height-datepicker_month_max + $spacing-datepicker_month-padding + $width-datepicker_nav + $spacing-datepicker_navigation_insetInput-paddingY * 2 + $height-datepicker_inset_input | inset_input下,非month面板渲染最大高度,默认361px |
| $height-datepicker_inset_input_compact | 28px + $spacing-datepicker_insetInput_wrapper_compact-paddingY | compact,insetInput高度, 默认36px |
| $height-datepicker_preset_panel_inset_input_compact | $height-datepicker_month_max_compact + $width-datepicker_nav_compact + $spacing-datepicker_insetInput_wrapper_compact-paddingY * 2 + $height-datepicker_inset_input_compact | inset_input下,非month面板渲染最大高度,默认296px |
日期时间格式
semi-ui 组件库中采用 date-fns v4 作为日期时间引擎,格式化 token 含义如下:
"y":年"M":月"d":日"H":小时"m":分钟"s":秒
下面以 new Date('2023-12-09 08:08:00') 和 [new Date('2023-12-09 08:08:00'), new Date('2023-12-10 10:08:00')] 为例说明不同 format 值对展示值的影响:
| 类型 | format | 展示值 |
|---|---|---|
| date | yyyy-MM-dd | 2023-12-09 |
| dateTime | yyyy-MM-dd HH:mm:ss | 2023-12-09 08:08:00 |
| month | yyyy-MM | 2023-12 |
| year | yyyy | 2023 |
| dateRange | yyyy-MM-dd | 2023-12-09 ~ 2023-12-10 |
| dateTimeRange | yyyy-MM-dd HH:mm:ss | 2023-12-09 08:08 ~ 2023-12-10 10:08 |
多个日期或时间默认使用 "," (英文逗号)分隔。
更多 token 可以查阅 date-fns 官网
FAQ
-
日期时间选择器,时分秒选择时想要无限滚动效果如何实现?
版本V2.22.0开始,我们将 TimePicker 内的 ScrollItem 的默认模式从 wheel 变更为了 normal, 若想应用回无限滚动的效果,可以通过 timePickerOpts 中的特定开关控制该行为。即
:timePickerOpts="{ scrollItemProps: { mode: 'wheel', cycled: true } }"。 -
如何设置面板打开时默认显示的时间?
可通过 defaultPickerValue 属性。 -
日期时间选择、范围日期选择,输入部分日期后,面板没有回显日期?
输入框需要输入完整后才会回显到面板上。比如,日期时间选择,完整要求日期和时间都已输入。范围日期选择,完整要求开始日期和结束日期都已输入。
-
日期时间选择面板底部的展示的时间是什么?
未选择时间时,它为 defaultPickerValue 中时间的值,如果没有设置则是面板打开时的时间。选择时间后,它为已选择的时间。
由于设计上它有隐含两层含义,可能会导致歧义,建议使用内嵌样式,通过
insetInput打开。使用前推荐阅读相关 文档。