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.
TimeSelect 时间段选择
从固定间隔的时间点里选一个时间,例如 08:30 到 18:30 每 30 分钟一个,适合预约、排班这类只能选整点、半点的场景。下拉层就是 NsSelect 的下拉层,外观、键盘操作和选择器一样。需要选任意的时、分、秒时用《TimePicker 时间选择器》。
引入
import { NsTimeSelect } from '@ns/ui'
基础用法
用 v-model 绑定,值是 HH:mm 格式的字符串(如 '09:30'),没有值时是 undefined。默认从 09:00 到 18:00,每 30 分钟一个,共 19 个时间点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref<string>()
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsTimeSelect v-model="time" style="width: 240px" />
<span>绑定值:{{ time ?? 'undefined' }}</span>
</NsSpace>
</template>
组件默认宽度是 100%,和 NsSelect 一样占满父容器,需要固定宽度时自己设 style 或 class。placeholder 不传时是“请选择时间”。
自定义起止和间隔
start 是第一个时间点,end 是最后一个时间点,step 是间隔,三个都写成 HH:mm。间隔的小时可以是 1 以上(01:30 表示 1 小时 30 分钟)。end 不在间隔上时,最后一个时间点是它之前的那个,例如 09:00 到 10:45 每 30 分钟,最后一个是 10:30。
每一行展开看看有哪些时间点:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const values = reactive<Record<string, string | undefined>>({})
const rows = [
{ key: 'a', start: '08:30', end: '18:30', step: '00:30', text: '08:30 - 18:30,每 30 分钟' },
{ key: 'b', start: '08:00', end: '12:00', step: '00:15', text: '08:00 - 12:00,每 15 分钟' },
{ key: 'c', start: '00:00', end: '23:00', step: '01:00', text: '全天,每 1 小时' },
{
key: 'd',
start: '09:00',
end: '17:00',
step: '01:30',
text: '09:00 - 17:00,每 1 小时 30 分'
},
{
key: 'e',
start: '09:00',
end: '10:45',
step: '00:30',
text: '09:00 - 10:45,最后一个是 10:30'
}
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace v-for="row in rows" :key="row.key" wrap>
<span class="row-label">{{ row.text }}</span>
<NsTimeSelect
v-model="values[row.key]"
:start="row.start"
:end="row.end"
:step="row.step"
style="width: 180px"
/>
<span class="row-value">{{ values[row.key] ?? 'undefined' }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 240px;
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>
开始、结束时间联动
min-time 和 max-time 把一部分时间点禁用:早于或等于 min-time 的、晚于或等于 max-time 的都不能选(等于的也禁用)。做“开始时间—结束时间”时,开始时间的 max-time 绑结束时间,结束时间的 min-time 绑开始时间,结束时间就只能比开始时间晚,不会相等。
先选开始时间,再展开结束时间看看:
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const startTime = ref<string>()
const endTime = ref<string>()
const toMinutes = (time: string) => {
const [hour, minute] = time.split(':').map(Number)
return hour * 60 + minute
}
const duration = computed(() => {
if (!startTime.value || !endTime.value) return '请选择开始和结束时间'
return `共 ${toMinutes(endTime.value) - toMinutes(startTime.value)} 分钟`
})
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsTimeSelect
v-model="startTime"
start="08:30"
end="18:30"
placeholder="开始时间"
:max-time="endTime"
clearable
style="width: 160px"
/>
<span>至</span>
<NsTimeSelect
v-model="endTime"
start="08:30"
end="18:30"
placeholder="结束时间"
:min-time="startTime"
clearable
style="width: 160px"
/>
</NsSpace>
<span>{{ duration }}</span>
</NsSpace>
</template>
也可以写死一个范围。下面左边只能约午休以后(min-time="12:00",12:00 本身不能选),中间只能约 17:00 以前,右边两个都写了:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const afterLunch = ref<string>()
const beforeOff = ref<string>()
const between = ref<string>()
</script>
<template>
<NsSpace wrap>
<NsTimeSelect
v-model="afterLunch"
min-time="12:00"
placeholder="12:00 以后"
style="width: 160px"
/>
<NsTimeSelect
v-model="beforeOff"
max-time="17:00"
placeholder="17:00 以前"
style="width: 160px"
/>
<NsTimeSelect
v-model="between"
min-time="11:30"
max-time="14:00"
placeholder="11:30 到 14:00 之间"
style="width: 180px"
/>
</NsSpace>
</template>
显示格式(12 小时制)
format 决定选项和输入框里怎么显示,默认 HH:mm。它只影响显示,绑定值始终是 24 小时制的 HH:mm。
| 单位 | 含义 | 例(13:05) |
|---|---|---|
HH / H | 小时(24 小时制) | 13 |
hh / h | 小时(12 小时制) | 01 / 1 |
mm / m | 分钟 | 05 / 5 |
A | 上午 / 下午 | 下午 |
a | AM / PM | PM |
[文字] | 方括号里原样输出 | [点] 输出 点 |
两个字母的写法补零到 2 位。12 小时制里 0 点显示成“上午 12:00”,中午 12 点显示成“下午 12:00”。
下面几个选择器绑定同一个值,只是 format 不同:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref('13:30')
const formats = [
{ format: 'HH:mm', text: 'HH:mm(默认)' },
{ format: 'H:mm', text: 'H:mm,小时不补零' },
{ format: 'A hh:mm', text: 'A hh:mm' },
{ format: 'A h:mm', text: 'A h:mm' },
{ format: 'h:mm a', text: 'h:mm a' },
{ format: 'HH[点]mm[分]', text: 'HH[点]mm[分]' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace v-for="item in formats" :key="item.format" wrap>
<span class="row-label">{{ item.text }}</span>
<NsTimeSelect
v-model="time"
start="08:00"
end="20:00"
:format="item.format"
style="width: 180px"
/>
</NsSpace>
<span>绑定值:{{ time }}</span>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 140px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
尺寸
size 可选 large、default、small,和同尺寸的 NsSelect、NsInput、NsButton 一致:高度 40 / 32 / 24px,字号 16 / 14 / 12px,圆角 8 / 6 / 4px,下拉层的选项也跟着变。不写时依次跟随所在的 NsFormItem、NsForm、外层 NsConfigProvider 的 size,都没有时是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref('10:00')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsTimeSelect v-model="time" size="large" clearable style="width: 200px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsTimeSelect v-model="time" clearable style="width: 200px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsTimeSelect 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>
禁用
disabled 后不能展开、不能用 Tab 聚焦,也不显示清除按钮。要禁用其中几个时间点用 min-time、max-time。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref('10:30')
</script>
<template>
<NsSpace wrap>
<NsTimeSelect v-model="time" disabled clearable style="width: 200px" />
<NsTimeSelect disabled placeholder="没有值" style="width: 200px" />
</NsSpace>
</template>
可清空
clearable 为 true 且有值时,右边显示清除按钮。清空后绑定值是 undefined,依次触发 update:modelValue、clear、change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref<string | undefined>('14:00')
const clearCount = ref(0)
</script>
<template>
<NsSpace wrap>
<NsTimeSelect v-model="time" clearable style="width: 200px" @clear="clearCount++" />
<span>绑定值:{{ time ?? 'undefined' }},已清空 {{ clearCount }} 次</span>
</NsSpace>
</template>
输入过滤
filterable 打开后,展开时可以输入文字,只留下显示文字里包含它的时间点,按回车选中第一个。匹配的是显示出来的文字:12 小时制下可以输入“下午”,但输入 14:30 匹配不到“下午 02:30”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref<string>()
const time12 = ref<string>()
</script>
<template>
<NsSpace wrap>
<NsTimeSelect
v-model="time"
filterable
step="00:15"
placeholder="输入 14 或 :45 试试"
style="width: 200px"
/>
<NsTimeSelect
v-model="time12"
filterable
format="A hh:mm"
placeholder="输入“下午”试试"
style="width: 200px"
/>
</NsSpace>
</template>
原生表单提交
传了 name 时,组件里多一个同名的隐藏 input,值是当前绑定值(没有值时是空字符串),用原生 <form> 提交或 new FormData(form) 时能取到。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTimeSelect } from '@ns/ui'
const time = ref<string | undefined>('10:00')
const submitted = ref('')
const onSubmit = (event: Event) => {
const data = new FormData(event.target as HTMLFormElement)
submitted.value = `meeting_time=${String(data.get('meeting_time'))}`
}
</script>
<template>
<form @submit.prevent="onSubmit">
<NsSpace wrap>
<NsTimeSelect v-model="time" name="meeting_time" clearable style="width: 200px" />
<NsButton type="primary" native-type="submit">提交</NsButton>
<span>{{ submitted || '还没有提交' }}</span>
</NsSpace>
</form>
</template>
在表单里使用
放在 NsFormItem 里时,值变化(选中、清空)触发 change 规则,收起下拉层触发 blur 规则;不写 size、disabled 时跟随表单。展开开始时间后不选直接收起,就会提示必填:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
NsButton,
NsCheckbox,
NsForm,
NsFormItem,
NsMessage,
NsSpace,
NsTimeSelect
} from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const disabled = ref(false)
const model = reactive<{ start?: string; end?: string }>({ start: undefined, end: undefined })
const rules: Record<string, FormRule[]> = {
start: [{ required: true, message: '请选择开始时间', trigger: ['change', 'blur'] }],
end: [{ required: true, message: '请选择结束时间', trigger: ['change', 'blur'] }]
}
const submit = async () => {
const result = await formRef.value?.validate()
if (result?.valid) NsMessage.success(`已预约 ${model.start} - ${model.end}`)
}
</script>
<template>
<NsForm
ref="formRef"
:model="model"
:rules="rules"
:disabled="disabled"
label-width="80px"
style="max-width: 420px"
>
<NsFormItem label="开始时间" prop="start">
<NsTimeSelect
v-model="model.start"
start="08:30"
end="18:30"
:max-time="model.end"
clearable
/>
</NsFormItem>
<NsFormItem label="结束时间" prop="end">
<NsTimeSelect
v-model="model.end"
start="08:30"
end="18:30"
:min-time="model.start"
clearable
/>
</NsFormItem>
<NsFormItem>
<NsSpace>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
<NsCheckbox v-model="disabled">禁用表单</NsCheckbox>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
事件
操作下面的选择器,最近触发的事件按时间倒序列在下面。change 在选中一项或清空时触发,选中的和原来一样也会触发;visibleChange 在下拉层展开、收起时触发;focus、blur 在焦点进入、离开组件时触发,可过滤时焦点在选择器和搜索框之间移动不算。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTimeSelect } 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: string | undefined) => log(`change:${String(value)}`)
const onVisibleChange = (visible: boolean) => log(`visible-change:${visible}`)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsTimeSelect
v-model="time"
clearable
filterable
style="width: 240px"
@change="onChange"
@clear="log('clear')"
@focus="log('focus')"
@blur="log('blur')"
@visible-change="onVisibleChange"
/>
<div class="event-log">
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
<div v-if="!logs.length">还没有触发事件</div>
</div>
</NsSpace>
</template>
<style scoped>
.event-log {
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, NsTimeSelect } from '@ns/ui'
import type { TimeSelectInstance } from '@ns/ui'
const selectRef = ref<TimeSelectInstance>()
const time = ref('09:30')
const focused = ref(false)
// 聚焦,2 秒后再让它失去焦点
const focusForAWhile = () => {
selectRef.value?.focus()
setTimeout(() => selectRef.value?.blur(), 2000)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsTimeSelect
ref="selectRef"
v-model="time"
style="width: 240px"
@focus="focused = true"
@blur="focused = false"
/>
<NsSpace wrap>
<NsButton @click="selectRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="focusForAWhile">聚焦 2 秒后失焦(blur)</NsButton>
<span>选择器{{ focused ? '有' : '没有' }}焦点</span>
</NsSpace>
</NsSpace>
</template>
键盘操作
选择器可以用 Tab 聚焦,聚焦后:
| 按键 | 作用 |
|---|---|
| Enter、空格 | 没展开时展开;展开后选中当前停留的时间点,没有停留项时收起 |
| ↓、↑ | 没展开时展开;展开后在时间点之间移动,跳过禁用的,到头后循环 |
| Esc | 收起下拉层,焦点回到选择器,不改值 |
| Tab | 收起下拉层,焦点移到下一个元素 |
- 展开时从当前选中的时间点开始移动,下拉层滚动到它所在的位置。
- 可过滤时,空格用来在搜索框里输入,不会选中时间点;输入后直接按回车选中第一个匹配的。
- 选择器是
role="combobox",下拉层是role="listbox",每个时间点是role="option",禁用的带aria-disabled="true";读屏软件通过aria-activedescendant读出当前停留的时间点。在NsFormItem里时,选择器通过aria-labelledby关联表单项的标签。不在表单里时,给组件写aria-label(会加到选择器上)。
配置写错时
start、end、step、min-time、max-time、format 写错时,开发环境下在控制台输出 [NsUI] 开头的警告,组件按下表处理,不会报错:
| 情况 | 表现 |
|---|---|
start 不是合法的时间(如 '9点'、'24:00') | 按 '09:00' 处理 |
end 不是合法的时间 | 按 '18:00' 处理 |
step 格式不对或是 '00:00' | 按 '00:30' 处理 |
end 早于 start | 没有时间点,展开后显示“暂无数据” |
min-time、max-time 不是合法的时间 | 忽略这一项,不禁用任何时间点 |
format 里没有时、分的单位(HH、H、hh、h、mm、m) | 按 'HH:mm' 处理 |
合法的时间是 H:mm 或 HH:mm,小时 0 到 23,分钟 00 到 59;带秒的 HH:mm:ss 也认,秒忽略。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | - | 绑定值,支持 v-model。HH:mm 格式,如 '09:30';也认 '9:30'、'09:30:00' |
| start | string | '09:00' | 第一个时间点,HH:mm |
| end | string | '18:00' | 最后一个时间点,HH:mm。不在间隔上时取它之前的最后一个时间点 |
| step | string | '00:30' | 间隔,HH:mm,必须大于 0 |
| minTime | string | - | 早于或等于它的时间点禁用,HH:mm |
| maxTime | string | - | 晚于或等于它的时间点禁用,HH:mm |
| format | string | 'HH:mm' | 显示格式,见“显示格式”。不影响绑定值 |
| placeholder | string | '请选择时间' | 没有值时的占位文字 |
| clearable | boolean | false | 有值时是否显示清除按钮 |
| disabled | boolean | false | 是否禁用。不写时跟随所在的 NsForm |
| filterable | boolean | false | 展开后能否输入文字过滤时间点(按显示文字匹配) |
| size | 'large' | 'default' | 'small' | — | 尺寸。不写时依次取 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 'default' |
| name | string | - | 原生表单提交用的字段名。传了会渲染一个同名的隐藏 input |
| validateEvent | boolean | true | 值变化和收起下拉层时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | undefined) | 值变化时触发:选中一项、清空 |
| change | (value: string | undefined) | 用户选中一项或清空时触发。选中的和原来一样也会触发 |
| clear | - | 点清除按钮时触发 |
| focus | (event: FocusEvent) | 焦点从外面进入组件时触发 |
| blur | (event: FocusEvent) | 焦点离开组件时触发。在选择器和搜索框之间移动不算 |
| visibleChange | (visible: boolean) | 下拉层展开或收起时触发 |
Slots
没有插槽。
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | - | void | 让选择器获得焦点(不展开);可过滤并且已展开时聚焦到搜索框 |
| blur | - | void | 让选择器失去焦点 |
类型
import type { TimeSelectProps, TimeSelectEmits, TimeSelectSize, TimeSelectInstance } from '@ns/ui'
type TimeSelectSize = 'large' | 'default' | 'small'
interface TimeSelectInstance {
focus: () => void
blur: () => void
}
注意事项
- 绑定值始终是 24 小时制的
HH:mm,format只改显示。传进来的'9:30'、'09:30:00'能和 09:30 这个时间点对上,但组件不会主动改写它们,选了新的时间以后才变成HH:mm。 - 绑定值不在时间点里时(例如 09:15,而间隔是 30 分钟),输入框直接显示这个值本身,下拉层里没有选中项。
min-time、max-time等于的那个时间点也禁用,所以开始、结束两个联动时结束时间只能比开始时间晚。- 不支持跨过午夜的范围(如 22:00 到次日 02:00):
end早于start按写错处理,没有时间点。 - 每个时间点都会渲染成下拉层里的一项,间隔太小时(如全天每 1 分钟,1440 项)展开会变慢,按实际需要设间隔。
- 写在组件上的
class、style加在最外层,id、aria-*、data-*等其余属性加在选择器(role="combobox"的元素)上。 - 下拉层通过
Teleport渲染到body下,和NsSelect的一样;给它写样式时直接用.ns-select__dropdown,不要依赖组件的父级选择器。