Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
DatePicker 日期选择器
在面板上选年份、月份、日期、日期时间,或者选一段日期范围,也可以直接在输入框里按格式输入。
引入
import { NsDatePicker } from '@ns/ui'
基础用法
用 v-model 绑定。不传 valueFormat 时发出的是 Date,没有值时是 null。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker } from '@ns/ui'
const value = ref<Date | null>(null)
</script>
<template>
<NsDatePicker v-model="value" style="width: 240px" />
<p style="margin-top: 12px">绑定值:{{ value ? value.toLocaleString() : 'null' }}</p>
</template>
选择器类型
type 决定面板的样子和发出的值:
| type | 面板 | 发出的值 |
|---|---|---|
year | 年份 | 那年 1 月 1 日 0 点 |
month | 月份 | 那个月 1 日 0 点 |
date | 日期(默认) | 当天 0 点 |
datetime | 日期加时分秒 | 带时分秒的 Date |
daterange | 左右两个月 | [开始, 结束],都是 0 点 |
datetimerange | 两个月加时分秒 | [开始, 结束],各自带时分秒 |
下面每一行是一种类型,右边显示选完以后发出的值:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const year = ref<Date | null>(null)
const month = ref<Date | null>(null)
const date = ref<Date | null>(null)
const datetime = ref<Date | null>(null)
const daterange = ref<[Date, Date] | null>(null)
const datetimerange = ref<[Date, Date] | null>(null)
// Date 按本地时间显示,范围用 ~ 连起来
const show = (value: Date | [Date, Date] | null) => {
if (!value) return 'null'
const text = (date: Date) => date.toLocaleString()
return Array.isArray(value) ? value.map(text).join(' ~ ') : text(value)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">year</span>
<NsDatePicker v-model="year" type="year" style="width: 240px" />
<span class="row-value">{{ show(year) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">month</span>
<NsDatePicker v-model="month" type="month" style="width: 240px" />
<span class="row-value">{{ show(month) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">date</span>
<NsDatePicker v-model="date" type="date" style="width: 240px" />
<span class="row-value">{{ show(date) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">datetime</span>
<NsDatePicker v-model="datetime" type="datetime" style="width: 240px" />
<span class="row-value">{{ show(datetime) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">daterange</span>
<NsDatePicker v-model="daterange" type="daterange" style="width: 300px" />
<span class="row-value">{{ show(daterange) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">datetimerange</span>
<NsDatePicker v-model="datetimerange" type="datetimerange" style="width: 400px" />
<span class="row-value">{{ show(datetimerange) }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 104px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.row-value {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
日期范围
type="daterange" 时在面板上点两次选出范围,先点哪头都行,点完第二个日期后按先后排好再发出。只点了一个日期就关掉面板的,这次选择不算。点了第一个日期以后,鼠标停在别的日期上(或者用方向键移到别的日期上)会预览将要选中的范围。
范围只有一个输入框,占位文字是“开始 分隔符 结束”:startPlaceholder 不传时是“开始日期”,endPlaceholder 不传时是“结束日期”,rangeSeparator 默认是 '至'。只传 placeholder 时整段用它。
左右两个面板默认显示相邻两个月,一起翻页。加上 unlinkPanels 后两个面板各自翻页。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const range1 = ref<[Date, Date] | null>(null)
const range2 = ref<[Date, Date] | null>(null)
const range3 = ref<[Date, Date] | null>(null)
const range4 = ref<[Date, Date] | null>(null)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">默认</span>
<NsDatePicker v-model="range1" type="daterange" style="width: 300px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">开始、结束、分隔符</span>
<NsDatePicker
v-model="range2"
type="daterange"
start-placeholder="入住"
end-placeholder="离店"
range-separator="到"
style="width: 300px"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">只传 placeholder</span>
<NsDatePicker
v-model="range3"
type="daterange"
placeholder="请选择统计周期"
style="width: 300px"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">unlink-panels</span>
<NsDatePicker v-model="range4" type="daterange" unlink-panels style="width: 300px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 120px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
日期时间
datetime、datetimerange 选了日期以后面板不关,下面的时、分、秒输入框改完立即生效。超出范围的数字收回到 0-23 / 0-59,删空后恢复原值。还没选日期时先改时间,选日期时会用上。同一天的范围,开始时间不会晚于结束时间。
底部按钮在 datetime 类型是“此刻”,在 date 类型是“今天”(发当天 0 点),范围类型不显示。
defaultTime 是选日期时用的时分秒。datetime 传一个 Date,只取它的时分秒;datetimerange 传两个,常配成开始 0 点、结束 23:59:59:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(null)
const range = ref<[Date, Date] | null>(null)
// 只用时分秒,年月日随便写
const nineOClock = new Date(2000, 0, 1, 9, 0, 0)
const defaultTime: [Date, Date] = [
new Date(2000, 0, 1, 0, 0, 0),
new Date(2000, 0, 1, 23, 59, 59)
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">默认 09:00:00</span>
<NsDatePicker
v-model="value"
type="datetime"
:default-time="nineOClock"
style="width: 240px"
/>
<span class="row-value">{{ value ? value.toLocaleString() : 'null' }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">开始 0 点、结束 23:59:59</span>
<NsDatePicker
v-model="range"
type="datetimerange"
:default-time="defaultTime"
style="width: 400px"
/>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 160px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.row-value {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
格式
format只管输入框里怎么显示,以及手动输入时按什么格式解析。不传时按类型取默认值:YYYY、YYYY-MM、YYYY-MM-DD、YYYY-MM-DD HH:mm:ss。valueFormat不传时发Date;传了发字符串,绑定值也按它解析。
| 单位 | 含义 | 单位 | 含义 |
|---|---|---|---|
YYYY | 四位年份 | HH | 两位小时,24 时制 |
YY | 两位年份 | H | 小时,不补零 |
MM | 两位月份 | mm | 两位分钟 |
M | 月份,不补零 | m | 分钟,不补零 |
DD | 两位日期 | ss | 两位秒 |
D | 日期,不补零 | s | 秒,不补零 |
方括号里的内容原样输出,例如 YYYY[年]M[月]D[日]。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker } from '@ns/ui'
const value = ref('2024-01-15')
</script>
<template>
<NsDatePicker
v-model="value"
format="YYYY[年]M[月]D[日]"
value-format="YYYY-MM-DD"
style="width: 240px"
/>
</template>
显示格式
下面几个选择器绑定的是同一个值,只是 format 不同。在任意一个里改了日期,其他几个跟着变。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(new Date(2024, 0, 5, 9, 8, 7))
const range = ref<[Date, Date] | null>([new Date(2024, 0, 5), new Date(2024, 0, 12)])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">YYYY/MM/DD</span>
<NsDatePicker v-model="value" format="YYYY/MM/DD" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYY[年]M[月]D[日]</span>
<NsDatePicker v-model="value" format="YYYY[年]M[月]D[日]" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">DD.MM.YY</span>
<NsDatePicker v-model="value" format="DD.MM.YY" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYY-MM-DD HH:mm</span>
<NsDatePicker
v-model="value"
type="datetime"
format="YYYY-MM-DD HH:mm"
style="width: 240px"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">YY-M-D H:m</span>
<NsDatePicker v-model="value" type="datetime" format="YY-M-D H:m" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYY[年]MM[月]</span>
<NsDatePicker v-model="value" type="month" format="YYYY[年]MM[月]" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYY[年度]</span>
<NsDatePicker v-model="value" type="year" format="YYYY[年度]" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">范围 YYYY/M/D</span>
<NsDatePicker v-model="range" type="daterange" format="YYYY/M/D" style="width: 300px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 144px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
月份、年份类型选完会把日期改成那个月(那年)的 1 日 0 点,所以在这两个里选了以后,上面几个的日、时间也会变。
绑定值格式
valueFormat 决定 v-model 拿到的是什么。右边是当前的绑定值:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const asDate = ref<Date | null>(new Date(2024, 0, 15))
const asString = ref('2024-01-15')
const compact = ref('20240115')
const withTime = ref('2024/01/15 09:30:00')
const range = ref<[string, string] | null>(['2024-01-15', '2024-01-20'])
const show = (value: unknown) => {
if (value instanceof Date) return `Date:${value.toLocaleString()}`
return JSON.stringify(value)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">不传</span>
<NsDatePicker v-model="asDate" style="width: 240px" />
<span class="row-value">{{ show(asDate) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYY-MM-DD</span>
<NsDatePicker v-model="asString" value-format="YYYY-MM-DD" style="width: 240px" />
<span class="row-value">{{ show(asString) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYYMMDD</span>
<NsDatePicker v-model="compact" value-format="YYYYMMDD" style="width: 240px" />
<span class="row-value">{{ show(compact) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">YYYY/MM/DD HH:mm:ss</span>
<NsDatePicker
v-model="withTime"
type="datetime"
value-format="YYYY/MM/DD HH:mm:ss"
style="width: 240px"
/>
<span class="row-value">{{ show(withTime) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">范围 YYYY-MM-DD</span>
<NsDatePicker
v-model="range"
type="daterange"
value-format="YYYY-MM-DD"
style="width: 300px"
/>
<span class="row-value">{{ show(range) }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 144px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.row-value {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用日期和面板选项
pickerOptions 里:
disabledDate(date)返回true的日期不能选,手动输入这样的日期也会恢复原值。月份、年份格子要整月、整年都禁用时才禁用。cellClassName(date)返回的类名加在日期格子上。firstDayOfWeek取 1 到 7,7 是周日,默认 7。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker } from '@ns/ui'
import type { PickerOptions } from '@ns/ui'
const value = ref<Date | null>(null)
const pickerOptions: PickerOptions = {
disabledDate: (date) => date.getTime() < new Date().setHours(0, 0, 0, 0),
firstDayOfWeek: 1
}
</script>
<template>
<NsDatePicker v-model="value" :picker-options="pickerOptions" style="width: 240px" />
</template>
禁用日期
disabledDate 收到的是格子那天的 0 点。各种类型都能用:日期类型禁用单个格子;范围类型两头都不能落在禁用的日期上;月份、年份类型只有整月、整年都被禁用时格子才变灰(下面的“month”行,本月还有能选的日子,所以本月能选,下个月起不能选)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
import type { PickerOptions } from '@ns/ui'
const today = new Date()
today.setHours(0, 0, 0, 0)
const DAY = 24 * 3600 * 1000
const beforeToday: PickerOptions = {
disabledDate: (date) => date.getTime() < today.getTime()
}
const weekend: PickerOptions = {
disabledDate: (date) => date.getDay() === 0 || date.getDay() === 6
}
const last30Days: PickerOptions = {
disabledDate: (date) =>
date.getTime() > today.getTime() || date.getTime() < today.getTime() - 29 * DAY
}
const afterToday: PickerOptions = {
disabledDate: (date) => date.getTime() > today.getTime()
}
const before2020: PickerOptions = {
disabledDate: (date) => date.getFullYear() < 2020
}
const value1 = ref<Date | null>(null)
const value2 = ref<Date | null>(null)
const value3 = ref<[Date, Date] | null>(null)
const value4 = ref<Date | null>(null)
const value5 = ref<Date | null>(null)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">今天以前不能选</span>
<NsDatePicker v-model="value1" :picker-options="beforeToday" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">周末不能选</span>
<NsDatePicker v-model="value2" :picker-options="weekend" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">只能选最近 30 天</span>
<NsDatePicker
v-model="value3"
type="daterange"
:picker-options="last30Days"
style="width: 300px"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">month:今天以后</span>
<NsDatePicker
v-model="value4"
type="month"
:picker-options="afterToday"
style="width: 240px"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">year:2020 年以前</span>
<NsDatePicker
v-model="value5"
type="year"
:picker-options="before2020"
style="width: 240px"
/>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 120px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
在第一行的输入框里输入一个过去的日期再按回车,输入框会恢复原来的值。
每周第一天
firstDayOfWeek 决定日期面板的星期从哪天排起:1 到 6 是周一到周六,7 是周日(默认)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(null)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">周一(1)</span>
<NsDatePicker v-model="value" :picker-options="{ firstDayOfWeek: 1 }" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">周六(6)</span>
<NsDatePicker v-model="value" :picker-options="{ firstDayOfWeek: 6 }" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">周日(7,默认)</span>
<NsDatePicker v-model="value" style="width: 240px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 104px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
单元格类名和面板类名
cellClassName 给日期格子加类名,popperClass 给整个下拉面板加类名。面板挂在 body 下,组件里的 <style scoped> 管不到,样式要写在不带 scoped 的样式里,并用 popperClass 限定范围,免得影响页面上别的日期选择器。下面把周末标成红色,每月 1 日、15 日下面加一个圆点:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker } from '@ns/ui'
import type { PickerOptions } from '@ns/ui'
const value = ref<Date | null>(null)
const pickerOptions: PickerOptions = {
cellClassName: (date) => {
const classes: string[] = []
if (date.getDay() === 0 || date.getDay() === 6) classes.push('is-weekend')
if (date.getDate() === 1 || date.getDate() === 15) classes.push('is-marked')
return classes.join(' ')
}
}
</script>
<template>
<NsDatePicker
v-model="value"
:picker-options="pickerOptions"
popper-class="demo-marked-panel"
style="width: 240px"
/>
</template>
<style>
/* 只改本月的日期,选中的日期保持白字 */
.demo-marked-panel
.ns-date-picker-panel__cell--normal.is-weekend:not(.ns-date-picker-panel__cell--selected) {
color: var(--ns-color-danger);
}
.demo-marked-panel .ns-date-picker-panel__cell.is-marked {
position: relative;
}
.demo-marked-panel .ns-date-picker-panel__cell.is-marked::after {
content: '';
position: absolute;
bottom: 3px;
left: 50%;
width: 4px;
height: 4px;
margin-left: -2px;
border-radius: 50%;
background-color: var(--ns-color-warning);
}
</style>
快捷选项
pickerOptions.shortcuts 显示在面板旁边,有两种写法:
{ text, value }:点了直接选value。范围类型的value要是[Date, Date]。{ text, onClick(picker) }:点了调onClick,picker是选择器实例,在里面调picker.pick(...)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker } from '@ns/ui'
import type { PickerOptions } from '@ns/ui'
const value = ref<Date | null>(null)
const pickerOptions: PickerOptions = {
// 类型是 PickerShortcut[] | PickerOption[],同一个数组里不能混用两种写法
shortcuts: [
{ text: '今天', onClick: (picker) => picker.pick(new Date()) },
{
text: '一周前',
onClick: (picker) => picker.pick(new Date(Date.now() - 7 * 24 * 3600 * 1000))
}
]
}
</script>
<template>
<NsDatePicker v-model="value" :picker-options="pickerOptions" style="width: 240px" />
</template>
{ text, value } 写法,日期类型和范围类型各一个。value 在定义时就算好了,适合固定的日期;要按点击时的时间计算(比如页面开了一整天),用上面的 onClick 写法。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
import type { PickerOptions } from '@ns/ui'
const DAY = 24 * 3600 * 1000
const today = new Date()
today.setHours(0, 0, 0, 0)
const date = ref<Date | null>(null)
const range = ref<[Date, Date] | null>(null)
const dateOptions: PickerOptions = {
shortcuts: [
{ text: '昨天', value: new Date(today.getTime() - DAY) },
{ text: '本月 1 日', value: new Date(today.getFullYear(), today.getMonth(), 1) },
{ text: '今年元旦', value: new Date(today.getFullYear(), 0, 1) }
]
}
const rangeOptions: PickerOptions = {
shortcuts: [
{ text: '最近一周', value: [new Date(today.getTime() - 6 * DAY), today] },
{ text: '最近一个月', value: [new Date(today.getTime() - 29 * DAY), today] },
{ text: '最近三个月', value: [new Date(today.getTime() - 89 * DAY), today] }
]
}
</script>
<template>
<NsSpace wrap>
<NsDatePicker v-model="date" :picker-options="dateOptions" style="width: 240px" />
<NsDatePicker
v-model="range"
type="daterange"
:picker-options="rangeOptions"
style="width: 300px"
/>
</NsSpace>
</template>
默认月份
没有值时面板显示当前月份。defaultValue 可以换成别的月份,范围类型可以传两个,分别给左右面板(两个月不相邻时加上 unlinkPanels,否则右边固定是左边的下个月)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(null)
const range = ref<[Date, Date] | null>(null)
const rangeDefault: [Date, Date] = [new Date(2020, 0, 1), new Date(2020, 5, 1)]
</script>
<template>
<NsSpace wrap>
<NsDatePicker v-model="value" :default-value="new Date(2020, 5, 1)" style="width: 240px" />
<NsDatePicker
v-model="range"
type="daterange"
:default-value="rangeDefault"
unlink-panels
style="width: 300px"
/>
</NsSpace>
</template>
可清空
clearable 后,有值时在右边显示清除按钮(禁用、只读时不显示)。点了依次发 update:modelValue(null)、clear、change(null)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(new Date())
const range = ref<[Date, Date] | null>([new Date(), new Date(Date.now() + 7 * 24 * 3600 * 1000)])
const clearCount = ref(0)
</script>
<template>
<NsSpace wrap>
<NsDatePicker v-model="value" clearable style="width: 240px" @clear="clearCount++" />
<NsDatePicker
v-model="range"
type="daterange"
clearable
style="width: 300px"
@clear="clearCount++"
/>
</NsSpace>
<p style="margin-top: 12px">已清空 {{ clearCount }} 次</p>
</template>
手动输入
默认可以在输入框里输入,按回车或失焦时生效。先按 format 解析,再认 2024-1-5、2024/1/5 这类常见写法。认不出来、是禁用日期时恢复原值。生效后面板翻到那个月。
editable 设成 false 后不能输入,点输入区打开面板,聚焦后按空格开关面板。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(null)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">可以输入(默认)</span>
<NsDatePicker v-model="value" placeholder="试试输入 2024/1/5" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">editable=false</span>
<NsDatePicker v-model="value" :editable="false" style="width: 240px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 120px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
尺寸
size 可选 large、default、small,输入框和同尺寸的 Input、Button 一致:高度 40 / 32 / 24px,字号 16 / 14 / 12px,圆角 8 / 6 / 4px,日历、清空、箭头图标 18 / 16 / 14px。各种 type 都一样,范围选择的两个日期和中间的分隔符也跟着变。日期面板不随尺寸变化。不写时依次跟随所在的 NsForm / NsFormItem、外层 NsConfigProvider 的 size,都没有时是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(new Date())
const range = ref<[Date, Date] | null>([new Date(), new Date(Date.now() + 7 * 24 * 3600 * 1000)])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsDatePicker v-model="value" size="large" clearable style="width: 220px" />
<NsDatePicker v-model="range" type="daterange" size="large" style="width: 320px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsDatePicker v-model="value" clearable style="width: 220px" />
<NsDatePicker v-model="range" type="daterange" style="width: 320px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsDatePicker v-model="value" size="small" clearable style="width: 220px" />
<NsDatePicker v-model="range" type="daterange" size="small" style="width: 320px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用和只读
disabled 和 readonly 都不能打开面板、不能输入,键盘也不响应。禁用时用禁用色和禁用底色显示;只读时颜色不变,只是鼠标指针是普通箭头、悬停时边框不变色。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(new Date())
const range = ref<[Date, Date] | null>([new Date(), new Date(Date.now() + 7 * 24 * 3600 * 1000)])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsDatePicker v-model="value" disabled style="width: 240px" />
<NsDatePicker v-model="range" type="daterange" disabled style="width: 300px" />
<NsDatePicker type="date" disabled placeholder="没有值" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsDatePicker v-model="value" readonly style="width: 240px" />
<NsDatePicker v-model="range" type="daterange" readonly style="width: 300px" />
<NsDatePicker type="date" readonly placeholder="没有值" style="width: 240px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
自定义图标
prefixIcon 默认是 'calendar',传空字符串不显示前缀图标。suffixIcon 默认不显示,显示在下拉箭头前面。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker, NsSpace } from '@ns/ui'
const value = ref<Date | null>(null)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">默认</span>
<NsDatePicker v-model="value" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">不要前缀</span>
<NsDatePicker v-model="value" prefix-icon="" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">换前缀</span>
<NsDatePicker v-model="value" type="datetime" prefix-icon="clock" style="width: 240px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">只要后缀</span>
<NsDatePicker v-model="value" prefix-icon="" suffix-icon="calendar" style="width: 240px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
事件
操作下面的选择器,最近触发的事件按时间倒序列在下面:选日期、改时间触发 change,打开、关闭面板触发 visibleChange,翻页、选年月触发 panelChange,点清除按钮触发 clear。模板里写成 @visible-change、@panel-change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDatePicker } from '@ns/ui'
import type { DatePickerValue } from '@ns/ui'
const value = ref<Date | null>(null)
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (val: DatePickerValue) => {
log(`change:${val instanceof Date ? val.toLocaleString() : String(val)}`)
}
const onVisibleChange = (visible: boolean) => log(`visibleChange:${visible}`)
const onPanelChange = (date: Date, mode: string, view: string) => {
log(
`panelChange:${date.getFullYear()} 年 ${date.getMonth() + 1} 月,mode=${mode},view=${view}`
)
}
</script>
<template>
<NsDatePicker
v-model="value"
type="datetime"
clearable
style="width: 240px"
@change="onChange"
@focus="log('focus')"
@blur="log('blur')"
@clear="log('clear')"
@visible-change="onVisibleChange"
@panel-change="onPanelChange"
/>
<div class="event-log">
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
<div v-if="!logs.length">还没有触发事件</div>
</div>
</template>
<style scoped>
.event-log {
margin-top: 12px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
line-height: 1.8;
}
</style>
方法
通过 ref 调用 focus、blur、handleOpen、handleClose、pick。pick 和点了日期一样发出 update:modelValue、change,不带时间的类型选完会关闭面板。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDatePicker, NsSpace } from '@ns/ui'
import type { DatePickerInstance } from '@ns/ui'
const pickerRef = ref<DatePickerInstance>()
const value = ref<Date | null>(null)
// 打开面板,3 秒后自动关闭
const openForAWhile = () => {
pickerRef.value?.handleOpen()
setTimeout(() => pickerRef.value?.handleClose(), 3000)
}
const pickNewYear = () => {
pickerRef.value?.pick(new Date(new Date().getFullYear() + 1, 0, 1))
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsDatePicker ref="pickerRef" v-model="value" style="width: 240px" />
<NsSpace wrap>
<NsButton @click="pickerRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="openForAWhile">打开 3 秒(handleOpen / handleClose)</NsButton>
<NsButton @click="pickNewYear">选中明年元旦(pick)</NsButton>
</NsSpace>
</NsSpace>
</template>
键盘操作
焦点在输入框上时:
| 按键 | 作用 |
|---|---|
Enter | 打开、关闭面板。输入框里改过文字时,让输入生效并关闭 |
↓ | 面板没打开时打开;已经打开时焦点进入面板,落在选中的日期上(没有值时是今天) |
Esc | 关闭面板 |
Tab | 关闭面板,焦点照常移到页面上的下一个元素 |
空格 | editable 为 false 时打开、关闭面板 |
焦点在面板里时:
| 按键 | 作用 |
|---|---|
← → | 日期格子里移一天,月份、年份格子里移一格 |
↑ ↓ | 日期格子里移一周,月份、年份格子里移一行(4 格) |
Enter、空格 | 选中焦点所在的格子,或者按下焦点所在的按钮(翻页箭头、年月标题、今天、快捷选项) |
Esc | 关闭面板,焦点回到输入框 |
Tab | 在翻页箭头、年月标题、格子区域、时间输入框、“今天”、快捷选项之间移动。从最后一个(Shift+Tab 时是第一个)移出时关闭面板,焦点回到输入框 |
- 方向键只移动焦点,不改值,按
Enter才选中。日期格子移到别的月份时面板跟着翻页,月份、年份格子在当前这一页里移动(跳过禁用的格子),翻页用顶部的按钮。 - 每个格子区域只占一个
Tab位置,Tab进来时落在上次移到的格子、选中的格子或今天(本月、本年)。 - 禁用的日期也能移过去,按
Enter没有反应;整月、整年都禁用的月份、年份格子跳过。 - 选完面板关闭时焦点回到输入框。带时间的类型、范围类型选第一个日期时面板不关,焦点留在选中的格子上。
- 范围类型选了开始日期以后,用方向键移到别的日期时也会预览将要选中的范围。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | Date | string | [Date | string, Date | string] | null | null | 绑定值,支持 v-model |
| type | 'year' | 'month' | 'date' | 'datetime' | 'daterange' | 'datetimerange' | 'date' | 选择器类型 |
| size | 'large' | 'default' | 'small' | — | 尺寸。不写时依次取表单、NsConfigProvider 的 size,都没有时是 'default' |
| placeholder | string | — | 占位文字。不传时按类型:选择年份 / 选择月份 / 选择日期 / 选择日期时间 |
| startPlaceholder | string | — | 范围类型开始一侧的占位文字,不传时是“开始日期”(datetimerange 是“开始时间”) |
| endPlaceholder | string | — | 范围类型结束一侧的占位文字,不传时是“结束日期”(datetimerange 是“结束时间”) |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读 |
| editable | boolean | true | 输入框能不能手动输入 |
| clearable | boolean | false | 是否显示清除按钮 |
| format | string | — | 显示格式,也用来解析手动输入。不传时按类型取默认格式 |
| valueFormat | string | — | 绑定值格式。不传时发 Date,传了发字符串 |
| pickerOptions | PickerOptions | — | 禁用日期、快捷选项、单元格类名、每周第一天 |
| popperClass | string | — | 加在下拉面板上的类名 |
| rangeSeparator | string | '至' | 范围类型的分隔符 |
| defaultValue | Date | [Date, Date] | — | 没有值时面板默认显示的月份 |
| defaultTime | Date | [Date, Date] | — | 带时间的类型选中日期时用的时分秒,范围类型传两个 |
| unlinkPanels | boolean | false | 范围类型左右面板各自翻页 |
| prefixIcon | string | 'calendar' | 前缀图标名,传空字符串不显示 |
| suffixIcon | string | — | 后缀图标名 |
PickerOptions
| 属性 | 类型 | 说明 |
|---|---|---|
| disabledDate | (date: Date) => boolean | 返回 true 的日期不能选,对手动输入也生效 |
| shortcuts | PickerShortcut[] | PickerOption[] | 快捷选项,写法见上文“快捷选项” |
| cellClassName | (date: Date) => string | 给日期格子加类名 |
| firstDayOfWeek | number | 每周第一天,1 到 7,7 是周日,默认 7 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: DatePickerValue) | 点日期、改时间、手动输入生效、点快捷选项、清空时触发,v-model 用的就是它 |
| change | (value: DatePickerValue) | 和 update:modelValue 同时触发 |
| focus | (event: FocusEvent) | 输入框获得焦点 |
| blur | (event: FocusEvent) | 输入框失去焦点。焦点进入面板(按 ↓ 进入格子、点时间输入框)时也会触发,这时表单的失焦校验等面板关闭后再做 |
| clear | — | 点清除按钮后触发 |
| visibleChange | (visible: boolean) | 面板真的打开或关闭时触发,状态没变不触发 |
| panelChange | (value: Date, mode: 'year' | 'month', view: 'year' | 'month' | 'date') | 翻页、选年、选月后触发。value 是面板显示月份的 1 日,mode 是变的是年还是月,view 是面板当前的视图 |
Slots
没有插槽。
Methods
| 方法 | 签名 | 说明 |
|---|---|---|
| focus | () => void | 让输入框获得焦点 |
| blur | () => void | 让输入框失去焦点 |
| handleOpen | () => void | 打开面板,禁用、只读时不打开 |
| handleClose | () => void | 关闭面板 |
| pick | (value: Date | [Date, Date]) => void | 直接选中一个值。范围类型必须传数组,类型不符时不处理;不带时间的类型选完会关闭面板 |
类型
import type {
DatePickerType,
DatePickerValue,
PickerOptions,
PickerShortcut,
PickerOption,
DatePickerInstance
} from '@ns/ui'
type DatePickerType = 'year' | 'month' | 'date' | 'datetime' | 'daterange' | 'datetimerange'
type DatePickerValue = Date | string | [Date | string, Date | string] | null
interface PickerOptions {
disabledDate?: (date: Date) => boolean
shortcuts?: PickerShortcut[] | PickerOption[]
cellClassName?: (date: Date) => string
firstDayOfWeek?: number
}
interface PickerShortcut {
text: string
value: Date | [Date, Date]
}
interface PickerOption {
text: string
onClick: (picker: DatePickerInstance) => void
}
interface DatePickerInstance {
focus: () => void
blur: () => void
handleOpen: () => void
handleClose: () => void
pick: (date: Date | [Date, Date]) => void
}
注意事项
- 字符串绑定值不带时区时按本地时间解析,
'2024-01-15'是本地 0 点,不是 UTC 0 点。 - 空值、解析不出来的值、不存在的日期(如 2 月 30 日)、范围缺一头的,都按没有值显示。
valueFormat里没有时分秒单位时,datetime类型的时间传回来会丢。- 没绑定
v-model时组件自己记着选中的值;绑定值是Date时按时间值比较,父组件每次传新对象不会重置面板。 - 面板 Teleport 到 body 下,第一次打开时才渲染,改面板样式用
popperClass。面板的z-index写在行内样式上,取外层NsConfigProvider的zIndex,默认 2000;要调层级用NsConfigProvider(行内样式会盖过popperClass里写的z-index)。 - 面板不能翻到公元 100 年以前。
- 输入框里把文字删空后失焦,会恢复原来的值,不会清空。要清空用
clearable。 - 点已经选中的日期也会触发
update:modelValue和change。 - 外部调用
pick()在禁用、只读时仍然生效。
优化点
- [ ] 支持多日期选择
- [ ] 支持周选择
- [ ] 支持自定义面板内容
- [ ] 范围类型拆成开始、结束两个输入框