TimePicker 时间选择器

用于在表单中输入或选择具体时间点，也可以选择开始和结束时间。需要拖拽配置一天内多个时间段时，请使用 TimeRangeSelector 时间范围选择。

何时使用

用户需要填写开始时间、截止时间、提醒时间、任务执行时间等具体时间点。
用户需要在筛选表单中选择一个开始和结束时间。
需要固定格式、步长或禁用某些时间项时。

基础用法

当前时间：09:30:00，面板底部可点击“此刻”快速选择当前时间。

vue

<template>
  <x-time-picker v-model="time" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const time = ref('09:30:00');
</script>

受控值和事件

弹层：关闭，等待操作

vue

<template>
  <x-time-picker
    v-model="time"
    v-model:popup-visible="popupVisible"
    allow-clear
    @select="handleSelect"
    @change="handleChange"
    @clear="handleClear"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const time = ref('13:45:00');
const popupVisible = ref(false);
const handleSelect = (value: string) => console.log('select', value);
const handleChange = (value: string | undefined) => console.log('change', value);
const handleClear = () => console.log('clear');
</script>

默认值和范围

范围：09:00:00 ~ 18:00:00

vue

<template>
  <x-time-picker default-value="18:24:23" />
  <x-time-picker v-model="range" type="time-range" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const range = ref(['09:00:00', '18:00:00']);
</script>

尺寸

vue

<template>
  <x-time-picker v-model="time" size="mini" />
  <x-time-picker v-model="time" size="small" />
  <x-time-picker v-model="time" size="medium" />
  <x-time-picker v-model="time" size="large" />
</template>

状态

vue

<template>
  <x-time-picker v-model="time" allow-clear />
  <x-time-picker default-value="09:00:00" readonly />
  <x-time-picker default-value="09:00:00" disabled />
  <x-time-picker v-model="time" error />
</template>

格式和步长

分钟格式：08:30，步长值：10:30:00

vue

<template>
  <x-time-picker v-model="shortTime" format="HH:mm" />
  <x-time-picker
    v-model="time"
    :step="{ hour: 2, minute: 15, second: 30 }"
  />
</template>

禁用时间

隐藏了夜间小时、12 点部分分钟和前 30 秒

vue

<template>
  <x-time-picker
    v-model="time"
    :disabled-hours="disabledHours"
    :disabled-minutes="disabledMinutes"
    :disabled-seconds="disabledSeconds"
    hide-disabled-options
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const time = ref('14:00:00');
const disabledHours = () => [0, 1, 2, 3, 4, 5, 22, 23];
const disabledMinutes = (hour?: number) => (hour === 12 ? [0, 15, 30, 45] : []);
const disabledSeconds = () => Array.from({ length: 30 }, (_, index) => index);
</script>

12 小时制

9:15:00 AM

vue

<template>
  <x-time-picker v-model="time" use12-hours />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const time = ref('9:15:00 AM');
</script>

自定义内容

班次

⌚

vue

<template>
  <x-time-picker v-model="time">
    <template #prefix>班次</template>
    <template #suffix-icon>⌚</template>
    <template #extra>选择值：{{ time || '未选择' }}</template>
  </x-time-picker>
</template>

表单组合

vue

<template>
  <x-form :model="form">
    <x-form-item field="startTime" label="开始时间" required>
      <x-time-picker v-model="form.startTime" allow-clear />
    </x-form-item>
    <x-form-item field="workRange" label="工作时段">
      <x-time-picker v-model="form.workRange" type="time-range" />
    </x-form-item>
  </x-form>
</template>

<script setup lang="ts">
import { reactive } from 'vue';

const form = reactive({
  startTime: '',
  workRange: ['09:00:00', '18:00:00'],
});
</script>

按需导入

import { TimePicker } from 'x-next';

TimePicker Props

参数	说明	类型	默认值
`type`	选择器类型	`'time' \| 'time-range'`	`'time'`
`modelValue`	绑定值	`string \| number \| Date \| Array<string \| number \| Date>`	`undefined`
`defaultValue`	默认值	`string \| number \| Date \| Array<string \| number \| Date>`	`undefined`
`placeholder`	占位文案	`string \| string[]`	`请选择时间` / `['开始时间', '结束时间']`
`disabled`	是否禁用	`boolean`	`false`
`readonly`	是否只读	`boolean`	`false`
`error`	是否错误态	`boolean`	`false`
`allowClear`	是否允许清除	`boolean`	`true`
`format`	展示和解析格式	`string`	`'HH:mm:ss'`，12 小时制为 `'h:mm:ss A'`
`size`	输入框尺寸	`'mini' \| 'small' \| 'medium' \| 'large'`	继承 Form / `medium`
`popupVisible`	控制弹层显示	`boolean`	`undefined`
`defaultPopupVisible`	默认弹层显示	`boolean`	`false`
`position`	弹出位置	`'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br'`	`'bl'`
`popupContainer`	弹层挂载容器	`string \| HTMLElement`	`undefined`
`triggerProps`	透传 Trigger 配置	`Partial<TriggerProps>`	`undefined`
`unmountOnClose`	关闭后销毁面板	`boolean`	`false`
`step`	时 / 分 / 秒步长	`{ hour?: number; minute?: number; second?: number }`	`{ hour: 1, minute: 1, second: 1 }`
`disabledHours`	禁用小时	`() => number[]`	`undefined`
`disabledMinutes`	禁用分钟	`(selectedHour?: number) => number[]`	`undefined`
`disabledSeconds`	禁用秒	`(selectedHour?: number, selectedMinute?: number) => number[]`	`undefined`
`hideDisabledOptions`	隐藏禁用项	`boolean`	`false`
`disableConfirm`	点击时间后立即提交	`boolean`	`false`
`use12Hours`	12 小时制	`boolean`	`false`

TimePicker Events

事件名	说明	参数
`update:modelValue`	值更新	`value`
`change`	确认值变化	`timeString, time`
`select`	面板选择但未必提交	`timeString, time`
`clear`	点击清除	`event`
`popup-visible-change`	弹层显示状态变化	`visible`
`update:popupVisible`	受控弹层更新	`visible`
`focus`	输入框聚焦	`event`
`blur`	输入框失焦	`event`

TimePicker Slots

插槽名	说明
`prefix`	输入框前缀
`suffix-icon`	输入框后缀图标
`extra`	面板页脚额外内容

TimePicker Methods

方法	说明
`focus()`	聚焦输入框
`blur()`	失焦输入框

交互说明

TimePicker 用于表单字段中的具体时间点或开始 / 结束时间。
TimeRangeSelector 用于拖拽配置一天内多个时间段，两者不是替代关系。
非法手动输入不会提交新值；按 Enter 或失焦时会尝试按 format 解析。
disableConfirm 开启后，点击面板时间项会立即提交。
范围模式会在同一个面板内并排展示开始时间和结束时间，左侧选择开始时间，右侧选择结束时间。
面板底部的“此刻”会把当前列值设置为系统当前时间，范围模式下作用于最近操作的开始或结束时间。

TimePicker 时间选择器 ​

何时使用 ​

基础用法 ​

受控值和事件 ​

默认值和范围 ​

尺寸 ​

状态 ​

格式和步长 ​

禁用时间 ​

12 小时制 ​

自定义内容 ​

表单组合 ​

按需导入 ​

TimePicker Props ​

TimePicker Events ​

TimePicker Slots ​

TimePicker Methods ​

交互说明 ​