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.
TimePicker 时间选择器
选择一天里的某个时间(时、分、秒)。点输入框展开面板,在面板里选好后点“确定”生效,也可以直接在输入框里输入。
引入
import { NsTimePicker } from '@ns/ui'
基础用法
用 v-model 绑定。默认绑定值是 HH:mm:ss 格式的字符串,没有值时是 undefined。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTimePicker } from '@ns/ui'
const time = ref<string>()
</script>
<template>
<NsTimePicker v-model="time" placeholder="选择时间" style="width: 240px" />
<p style="margin-top: 12px">绑定值:{{ time ?? 'undefined' }}</p>
</template>
组件默认宽度是 100%,需要固定宽度时自己设 style 或 class。placeholder 不传时是“请选择时间”。
显示格式
format 决定输入框里怎么显示,也决定面板里有哪几列。格式里没有写的单位,面板里不出现对应的列。
| 单位 | 含义 | 说明 |
|---|---|---|
HH / H | 小时(24 小时制) | HH 补零到 2 位,H 不补零 |
mm / m | 分钟 | 同上 |
ss / s | 秒 | 同上 |
其他字符原样显示。要显示的文字里含有 H、h、m、s 这几个字母时,用方括号括起来,如 HH:mm [hours]。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimePicker } from '@ns/ui'
const time = ref('08:30:00')
</script>
<template>
<NsSpace direction="vertical" fill>
<!-- 只选时、分,显示 08:30 -->
<NsTimePicker v-model="time" format="HH:mm" />
<!-- 显示 08时30分00秒 -->
<NsTimePicker v-model="time" format="HH时mm分ss秒" />
</NsSpace>
</template>
下面几个选择器绑定同一个值,只是 format 不同,打开面板可以看到列数跟着格式变。为了让几种格式发出的值一致,都写了 value-format="HH:mm:ss"(原因见下一节)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimePicker } from '@ns/ui'
const time = ref('08:05:09')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">HH:mm:ss(默认)</span>
<NsTimePicker v-model="time" value-format="HH:mm:ss" style="width: 200px" />
<span class="row-value">时、分、秒三列</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">HH:mm</span>
<NsTimePicker v-model="time" format="HH:mm" value-format="HH:mm:ss" style="width: 200px" />
<span class="row-value">时、分两列</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">mm:ss</span>
<NsTimePicker v-model="time" format="mm:ss" value-format="HH:mm:ss" style="width: 200px" />
<span class="row-value">分、秒两列,适合时长</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">HH</span>
<NsTimePicker v-model="time" format="HH[ 点]" value-format="HH:mm:ss" style="width: 200px" />
<span class="row-value">只有时一列,格式写成 HH[ 点]</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">H:m:s</span>
<NsTimePicker v-model="time" format="H:m:s" value-format="HH:mm:ss" style="width: 200px" />
<span class="row-value">不补零,显示 8:5:9</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">HH时mm分ss秒</span>
<NsTimePicker
v-model="time"
format="HH时mm分ss秒"
value-format="HH:mm:ss"
style="width: 200px"
/>
<span class="row-value">中文单位</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">HH [h] mm [min]</span>
<NsTimePicker
v-model="time"
format="HH [h] mm [min]"
value-format="HH:mm:ss"
style="width: 200px"
/>
<span class="row-value">含 h、m 的文字放进方括号</span>
</NsSpace>
</NsSpace>
<p style="margin-top: 12px">绑定值:{{ time }}</p>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 120px;
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>
绑定值的格式
valueFormat 决定 v-model 拿到的值是什么样的,和显示格式互不影响。
valueFormat | 绑定值 |
|---|---|
| 不传 | 字符串,按 format 里出现的列用冒号拼接:format="HH:mm:ss" 时是 12:30:00,format="HH:mm" 或 format="HH时mm分" 时是 12:30。绑定的初始值是 Date 时,发出的也是 Date |
格式字符串,如 HH:mm:ss、HH-mm | 这个格式的字符串,单位写法和 format 相同 |
Date | Date 对象 |
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimePicker } from '@ns/ui'
// 只显示时、分,但提交给后端的值带秒
const time = ref('08:30:00')
// 绑定 Date
const date = ref<Date>()
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTimePicker v-model="time" format="HH:mm" value-format="HH:mm:ss" />
<NsTimePicker v-model="date" value-format="Date" />
</NsSpace>
</template>
绑定值是 Date 时只改它的时、分、秒,年月日保持不变;原来没有值时用当天的日期。
下面每一行在面板里选一个时间,右边显示绑定值:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimePicker } from '@ns/ui'
const plain = ref('08:30:00')
const minutes = ref('08:30')
const withSeconds = ref('08:30:00')
const custom = ref('08-30')
const asDate = ref<Date>()
const initialDate = ref<Date>(new Date(2024, 0, 15, 8, 30, 0))
const show = (value: Date | string | undefined) => {
if (value instanceof Date) return `Date:${value.toLocaleString()}`
return value === undefined ? 'undefined' : `'${value}'`
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">不传</span>
<NsTimePicker v-model="plain" style="width: 200px" />
<span class="row-value">{{ show(plain) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">不传,format="HH:mm"</span>
<NsTimePicker v-model="minutes" format="HH:mm" style="width: 200px" />
<span class="row-value">{{ show(minutes) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">HH:mm:ss,format="HH:mm"</span>
<NsTimePicker
v-model="withSeconds"
format="HH:mm"
value-format="HH:mm:ss"
style="width: 200px"
/>
<span class="row-value">{{ show(withSeconds) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">HH-mm</span>
<NsTimePicker v-model="custom" format="HH:mm" value-format="HH-mm" style="width: 200px" />
<span class="row-value">{{ show(custom) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">Date</span>
<NsTimePicker v-model="asDate" value-format="Date" style="width: 200px" />
<span class="row-value">{{ show(asDate) }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">不传,初始值是 Date</span>
<NsTimePicker v-model="initialDate" style="width: 200px" />
<span class="row-value">{{ show(initialDate) }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 168px;
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>
最后一行改了时间以后,日期还是 2024 年 1 月 15 日。
可清空
clearable 为 true 且有值时,输入框右边显示清除按钮。清空后绑定值是 undefined,并触发 clear 事件。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTimePicker } from '@ns/ui'
const time = ref<string | undefined>('08:30:00')
const clearCount = ref(0)
</script>
<template>
<NsTimePicker v-model="time" clearable style="width: 240px" @clear="clearCount++" />
<p style="margin-top: 12px">绑定值:{{ time ?? 'undefined' }},已清空 {{ clearCount }} 次</p>
</template>
手动输入
默认可以直接在输入框里输入时间:
- 按
format的格式输完整(如12:30:45)立即生效。 - 没补零的写法(如
9:5:7)在离开输入框或按回车时补全后生效。 - 不是时间的内容、超出范围的时间(如
25:00:00)不生效,离开输入框后恢复成原来的值。
editable 设为 false 后输入框不能输入,只能在面板里选。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimePicker } from '@ns/ui'
const time = ref('08:30:00')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">可以输入(默认)</span>
<NsTimePicker v-model="time" style="width: 200px" />
<span class="row-value">试试输入 9:5:7 后按回车</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">editable=false</span>
<NsTimePicker v-model="time" :editable="false" style="width: 200px" />
<span class="row-value">只能在面板里选</span>
</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);
}
.row-value {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用和只读
disabled 和 readonly 都不能打开面板、不能输入、不显示清除按钮。区别是 disabled 整体变灰且输入框不能聚焦,readonly 外观不变。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimePicker } from '@ns/ui'
const time = ref('08:30:00')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsTimePicker v-model="time" disabled clearable style="width: 200px" />
<NsTimePicker disabled placeholder="没有值" style="width: 200px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsTimePicker v-model="time" readonly clearable style="width: 200px" />
<NsTimePicker readonly placeholder="没有值" style="width: 200px" />
</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>
尺寸
size 可选 large、default、small,输入框和同尺寸的 Input、Select、Button 一致:高度 40 / 32 / 24px,字号 16 / 14 / 12px,圆角 8 / 6 / 4px,时钟、清空图标 18 / 16 / 14px。时间面板不随尺寸变化。不写时依次跟随所在的 NsForm / NsFormItem、外层 NsConfigProvider 的 size,都没有时是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTimePicker } from '@ns/ui'
const time = ref('08:30:00')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsTimePicker v-model="time" size="large" clearable style="width: 200px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsTimePicker v-model="time" clearable style="width: 200px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsTimePicker v-model="time" size="small" clearable style="width: 200px" />
<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>
事件
操作下面的选择器,最近触发的事件按时间倒序列在下面。点“确定”时即使时间没变也会触发 change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTimePicker } from '@ns/ui'
const time = ref<string>()
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (value: Date | string | undefined) => log(`change:${String(value)}`)
</script>
<template>
<NsTimePicker
v-model="time"
clearable
style="width: 240px"
@change="onChange"
@clear="log('clear')"
@focus="log('focus')"
@blur="log('blur')"
/>
<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。focus 只让输入框获得焦点,不打开面板。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTimePicker } from '@ns/ui'
import type { TimePickerInstance } from '@ns/ui'
const pickerRef = ref<TimePickerInstance>()
const time = ref('08:30:00')
const focused = ref(false)
// 聚焦,2 秒后再让它失去焦点
const focusForAWhile = () => {
pickerRef.value?.focus()
setTimeout(() => pickerRef.value?.blur(), 2000)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsTimePicker
ref="pickerRef"
v-model="time"
style="width: 240px"
@focus="focused = true"
@blur="focused = false"
/>
<NsSpace wrap>
<NsButton @click="pickerRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="focusForAWhile">聚焦 2 秒后失焦(blur)</NsButton>
<span>输入框{{ focused ? '有' : '没有' }}焦点</span>
</NsSpace>
</NsSpace>
</template>
键盘操作
焦点在输入框上时:
| 按键 | 作用 |
|---|---|
Enter | 面板没打开时打开;打开时相当于点“确定” |
↓ | 面板没打开时打开;打开时焦点进入第一列 |
Esc | 关闭面板,不改值 |
Tab | 面板打开时焦点进入第一列,面板不关;面板没打开时焦点照常离开 |
Shift+Tab | 焦点往回离开,面板关闭 |
焦点在面板里时:
| 按键 | 作用 |
|---|---|
↑ ↓ | 这一列选上一个、下一个,到头了从另一头接着(23 时往下是 0 时) |
Home End | 这一列选第一个、最后一个 |
Enter | 在列表上相当于点“确定”;在“取消”“确定”按钮上照常按下按钮 |
Esc | 关闭面板,不改值,焦点回到输入框 |
Tab | 依次经过时、分、秒三列和“取消”“确定”。在“确定”上按 Tab 关闭面板(不改值),焦点回到输入框 |
Shift+Tab | 往回移动;在第一列上按时回到输入框,面板不关 |
- 方向键改的只是面板里的选择,按
Enter或点“确定”才生效,和用鼠标点选一样。 - 每一列是一个列表(
role="listbox"),焦点停在列表上,读屏软件通过aria-activedescendant读出当前选中的那一项。 - 焦点从输入框移进面板时输入框会失去焦点:输入框里输入到一半的时间(如
8:5)这时生效,触发blur事件;在表单里,失焦校验等面板关闭后再做。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | Date | string | - | 绑定值,支持 v-model。字符串按 valueFormat 解析;解析不出来或时间超出范围时按没有值处理 |
| format | string | 'HH:mm:ss' | 显示格式,同时决定面板里有哪几列 |
| valueFormat | string | - | 绑定值的格式,见上面的“绑定值的格式” |
| placeholder | string | '请选择时间' | 没有值时的占位文字 |
| clearable | boolean | false | 有值时是否显示清除按钮 |
| editable | boolean | true | 输入框是否可以手动输入 |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读 |
| size | 'large' | 'default' | 'small' | — | 尺寸。不写时依次取表单、NsConfigProvider 的 size,都没有时是 'default' |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: Date | string | undefined) | 值变化时触发:点“确定”、输入了完整的时间、清空 |
| change | (value: Date | string | undefined) | 触发时机和 update:modelValue 相同。点“确定”时即使时间没变也会触发 |
| clear | - | 点清除按钮时触发 |
| focus | (event: FocusEvent) | 输入框获得焦点 |
| blur | (event: FocusEvent) | 输入框失去焦点。用鼠标点面板里的内容不会让输入框失去焦点,用键盘进入面板时会触发 |
Slots
没有插槽。
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | - | void | 让输入框获得焦点(不会打开面板) |
| blur | - | void | 让输入框失去焦点 |
类型
type TimePickerSize = 'large' | 'default' | 'small'
interface TimePickerInstance {
focus: () => void
blur: () => void
}
注意事项
- 面板里选了时间要点“确定”(或在列表上按
Enter)才生效。点“取消”、按Esc、点面板外面、在“确定”上按Tab都只关闭面板,不改值。 - 只支持 24 小时制。格式里的
h和H一样按 24 小时处理,没有上午、下午。 - 面板渲染在
body下,第一次打开时才渲染,会跟着输入框一起滚动;下面放不下时自动向上展开,靠近窗口右边时向左收回,不会超出窗口。要改面板的样式,选择器不要写在组件的父元素下面(面板不在那里),直接用.ns-time-picker__dropdown。面板的z-index写在行内样式上,取外层NsConfigProvider的zIndex,默认 2000;要调层级用NsConfigProvider(行内样式会盖过样式表里写的z-index)。 - 字符串绑定值里带日期也可以(如
2024-01-01 08:15:30),组件只取其中的时间部分;选完后发出的是valueFormat指定的格式,日期部分不会保留。需要保留日期时绑定Date。 - 没有写
valueFormat时,绑定值的格式跟着format走(见上表)。显示格式和后端要的格式不一样时,明确写上valueFormat。
优化点
- [ ] 支持时间范围选择
- [ ] 支持自定义时间项(禁用某些时、分、秒)
- [ ] 支持步进时间选择(如每 15 分钟一档)
- [ ] 支持 12 小时制(上午、下午)
- [ ] “确定”“取消”等文字支持国际化