FxTimePicker 时间选择器

用于时间输入的时间选择器。

FxTimePicker 属于 @fx/components。

任意时间选择

可选择任意时间。

默认可用鼠标滚轮选择时间，设置 arrow-control 后可使用箭头按钮选择。

<template>
  <div class="example-basic">
    <FxTimePicker v-model="value1" placeholder="任意时间" />
    <FxTimePicker v-model="value2" arrow-control placeholder="任意时间" />
  </div>
</template>

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

const value1 = ref()
const value2 = ref()
</script>

<style scoped>
.example-basic {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}
</style>

限制时间范围

也可以限制时间范围。

通过 disabledHours、disabledMinutes、disabledSeconds 限制可选时间范围。

<template>
  <div class="example-basic">
    <FxTimePicker
      v-model="value"
      :disabled-hours="disabledHours"
      :disabled-minutes="disabledMinutes"
      :disabled-seconds="disabledSeconds"
      placeholder="任意时间"
    />
  </div>
</template>

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

const value = ref(new Date(2016, 9, 10, 18, 30))

const makeRange = (start: number, end: number) => {
  const result: number[] = []
  for (let i = start; i <= end; i++) {
    result.push(i)
  }
  return result
}
const disabledHours = () => {
  return makeRange(0, 16).concat(makeRange(19, 23))
}
const disabledMinutes = (hour: number) => {
  if (hour === 17) {
    return makeRange(0, 29)
  }
  if (hour === 18) {
    return makeRange(31, 59)
  }
  return []
}
const disabledSeconds = (hour: number, minute: number) => {
  if (hour === 18 && minute === 30) {
    return makeRange(1, 59)
  }
  return []
}
</script>

任意时间范围

可选择一个时间范围。

添加 is-range 属性即可选择时间范围，arrow-control 在范围模式下同样支持。

<template>
  <div class="demo-range">
    <FxTimePicker
      v-model="value1"
      is-range
      range-separator="至"
      start-placeholder="开始时间"
      end-placeholder="结束时间"
    />
    <FxTimePicker
      v-model="value2"
      is-range
      arrow-control
      range-separator="至"
      start-placeholder="开始时间"
      end-placeholder="结束时间"
    />
  </div>
</template>

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

const value1 = ref<[Date, Date]>([
  new Date(2016, 9, 10, 8, 40),
  new Date(2016, 9, 10, 9, 40),
])
const value2 = ref<[Date, Date]>([
  new Date(2016, 9, 10, 8, 40),
  new Date(2016, 9, 10, 9, 40),
])
</script>

<style scoped>
.demo-range {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
</style>

扩展能力

以下为 FxTimePicker 在基础时间选择之外额外提供的能力。

时间格式

format 控制输入框显示格式（dayjs token），value-format 控制绑定值格式；未指定 value-format 时绑定 Date 对象。

<template>
  <div class="demo-row">
    <FxTimePicker v-model="value1" format="HH:mm" placeholder="HH:mm" />
    <FxTimePicker v-model="value2" format="hh:mm A" placeholder="hh:mm A" />
    <FxTimePicker
      v-model="value3"
      value-format="HH:mm:ss"
      placeholder="绑定值 HH:mm:ss"
    />
  </div>
</template>

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

const value1 = ref()
const value2 = ref()
const value3 = ref()
</script>

<style scoped>
.demo-row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}
</style>

禁用

disabled 完全禁用选择器（不弹层、不可编辑）。

<template>
  <FxTimePicker v-model="value" disabled placeholder="禁用状态" />
</template>

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

const value = ref(new Date(2026, 0, 1, 12, 0, 0))
</script>

API

Attributes

属性	说明	类型	默认值
model-value / v-model	绑定值，数组时长度为 2	number | string | Date | [Date, Date] | [number, number] | [string, string]	—
readonly	是否只读	boolean	false
disabled	是否禁用	boolean	false
editable	输入框是否可键入	boolean	true
clearable	是否显示清空按钮	boolean	true
size	输入框尺寸	'large' | 'default' | 'small'	—
placeholder	非范围模式的占位文本	string	—
start-placeholder	范围模式起始占位	string	—
end-placeholder	范围模式结束占位	string	—
is-range	是否选择时间范围	boolean	false
arrow-control	是否使用箭头按钮选时间	boolean	false
popper-class	下拉自定义类名	string	—
popper-style	下拉自定义样式	string | object	—
popper-options	透传浮层选项	object	{}
fallback-placements	浮层备选位置列表	Placement[]	['bottom','top','right','left']
placement	浮层位置	Placement	bottom
range-separator	范围分隔符	string	'-'
format	输入框显示格式	string	—
default-value	面板默认聚焦时间	Date | [Date, Date]	—
value-format	绑定值格式，未指定则绑定 Date 对象	string	—
id	原生 id	string | [string, string]	—
name	原生 name	string | [string, string]	—
aria-label	原生 aria-label	string	—
prefix-icon	自定义前缀图标	string | Component	ep:clock
clear-icon	自定义清空图标	string | Component	ep:circle-close
disabled-hours	禁用小时	(role: string, comparingDate?: Dayjs) => number[]	—
disabled-minutes	禁用分钟	(hour: number, role: string, comparingDate?: Dayjs) => number[]	—
disabled-seconds	禁用秒	(hour: number, minute: number, role: string, comparingDate?: Dayjs) => number[]	—
teleported	是否将下拉挂载到 body	boolean	true
tabindex	输入框 tabindex	string | number	0
empty-values	组件的空值列表	array	—
value-on-clear	清空时回填的值	string | number | boolean | Function	—
save-on-blur	未选值时聚焦是否自动填入当前时间	boolean	true
validate-event	是否触发表单校验	boolean	true
automatic-dropdown	聚焦输入框时自动展开下拉	boolean	true

Events

事件名	说明	类型
change	用户确认选值时触发	(val) => void
blur	输入框失焦时触发	(e: FocusEvent) => void
focus	输入框聚焦时触发	(e: FocusEvent) => void
clear	点击清空按钮时触发	() => void
visible-change	下拉显隐时触发	(visible: boolean) => void

Exposes

方法	说明	类型
focus	聚焦输入框	() => void
blur	失焦输入框	() => void
handleOpen	打开下拉	() => void
handleClose	关闭下拉	() => void

类型声明

展开查看

type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end'