FxDateTimePicker 日期时间选择器

在一个选择器中同时选择日期与时间。

TIP

日期时间选择由 FxDatePicker 的 type=datetime / datetimerange 提供，本页集中演示其日期时间场景。更详细的属性说明可参考 FxDatePicker 与 FxTimePicker。

本页能力属于 @fx/components。

日期时间

将 type 设置为 datetime 即可在同一选择器中选择日期与时间。快捷选项的用法与日期选择器一致。

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">默认</span>
      <FxDatePicker
        v-model="value1"
        type="datetime"
        placeholder="选择日期时间"
      />
    </div>
    <div class="block">
      <span class="demonstration">带快捷选项</span>
      <FxDatePicker
        v-model="value2"
        type="datetime"
        placeholder="选择日期时间"
        :shortcuts="shortcuts"
      />
    </div>
    <div class="block">
      <span class="demonstration">带默认时间</span>
      <FxDatePicker
        v-model="value3"
        type="datetime"
        placeholder="选择日期时间"
        :default-time="defaultTime"
      />
    </div>
  </div>
</template>

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

const value1 = ref("")
const value2 = ref("")
const value3 = ref("")
const defaultTime = new Date(2000, 1, 1, 12, 0, 0)

const shortcuts = [
  { text: "今天", value: new Date() },
  {
    text: "昨天",
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24)
      return date
    },
  },
  {
    text: "一周前",
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24 * 7)
      return date
    },
  },
]
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

日期时间格式

用 format 控制输入框显示文本的格式；用 value-format 控制绑定值的格式。默认情况下，组件接受并发射 Date 对象。

WARNING

注意大小写

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">emits Date 对象</span>
      <span class="demonstration">值：{{ value1 }}</span>
      <FxDatePicker
        v-model="value1"
        type="datetime"
        placeholder="选择日期时间"
        format="YYYY/MM/DD HH:mm:ss"
      />
    </div>
    <div class="block">
      <span class="demonstration">使用 value-format</span>
      <span class="demonstration">值：{{ value2 }}</span>
      <FxDatePicker
        v-model="value2"
        type="datetime"
        placeholder="选择日期时间"
        format="YYYY/MM/DD hh:mm:ss"
        value-format="YYYY-MM-DD h:m:s a"
      />
    </div>
    <div class="block">
      <span class="demonstration">时间戳</span>
      <span class="demonstration">值：{{ value3 }}</span>
      <FxDatePicker
        v-model="value3"
        type="datetime"
        placeholder="选择日期时间"
        format="YYYY/MM/DD hh:mm:ss"
        value-format="x"
      />
    </div>
  </div>
</template>

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

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

<style scoped>
.demo-datetime-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

面板内的日期时间格式

用 date-format 和 time-format 控制下拉面板内输入框中显示文本的格式。

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">datetime</span>
      <FxDatePicker
        v-model="value1"
        type="datetime"
        placeholder="选择日期时间"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="MMM DD, YYYY"
        time-format="HH:mm"
      />
    </div>
    <div class="block">
      <span class="demonstration">datetimerange</span>
      <FxDatePicker
        v-model="value2"
        type="datetimerange"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="YYYY/MM/DD ddd"
        time-format="A hh:mm:ss"
      />
    </div>
  </div>
</template>

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

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

<style scoped>
.demo-datetime-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

日期时间范围

将 type 设置为 datetimerange 即可选择日期时间范围。

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">默认</span>
      <FxDatePicker
        v-model="value1"
        type="datetimerange"
        range-separator="至"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
      />
    </div>
    <div class="block">
      <span class="demonstration">带快捷选项</span>
      <FxDatePicker
        v-model="value2"
        type="datetimerange"
        range-separator="至"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        :shortcuts="shortcuts"
      />
    </div>
  </div>
</template>

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

const value1 = ref<[Date, Date]>([
  new Date(2000, 10, 10, 10, 10),
  new Date(2000, 10, 11, 10, 10),
])
const value2 = ref("")

const shortcuts = [
  {
    text: "上周",
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
      return [start, end]
    },
  },
  {
    text: "上个月",
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
      return [start, end]
    },
  },
  {
    text: "最近三个月",
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
      return [start, end]
    },
  },
]
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

单面板

默认情况下日期范围选择器有两个面板。如需单面板，设置 single-panel 属性。

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">datetimerange 单面板</span>
      <FxDatePicker v-model="value" type="datetimerange" single-panel />
    </div>
  </div>
</template>

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

const value = ref()
</script>

<style scoped>
.demo-datetime-picker .block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

起止日期的默认时间

type 为 datetimerange 时，起止日期的默认时间均为 00:00:00。可通过 default-time 改变，接受最多两个 Date 对象的数组。

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">起止时间均为 12:00:00</span>
      <FxDatePicker
        v-model="value1"
        type="datetimerange"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        :default-time="defaultTime1"
      />
    </div>
    <div class="block">
      <span class="demonstration">起始 12:00:00，结束 08:00:00</span>
      <FxDatePicker
        v-model="value2"
        type="datetimerange"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        :default-time="defaultTime2"
      />
    </div>
  </div>
</template>

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

const value1 = ref("")
const value2 = ref("")

const defaultTime1 = new Date(2000, 1, 1, 12, 0, 0)
const defaultTime2: [Date, Date] = [
  new Date(2000, 1, 1, 12, 0, 0),
  new Date(2000, 2, 1, 8, 0, 0),
]
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

自定义图标

通过插槽可使用自定义图标。

<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">datetime</span>
      <FxDatePicker
        v-model="value1"
        type="datetime"
        placeholder="选择日期时间"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="MMM DD, YYYY"
        time-format="HH:mm"
      >
        <template #prev-month>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M15 18l-6-6 6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
        <template #next-month>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M9 18l6-6-6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
        <template #prev-year>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M18 18l-6-6 6-6M11 18l-6-6 6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
        <template #next-year>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M6 18l6-6-6-6M13 18l6-6-6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
      </FxDatePicker>
    </div>
    <div class="block">
      <span class="demonstration">datetimerange</span>
      <FxDatePicker
        v-model="value2"
        type="datetimerange"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="YYYY/MM/DD ddd"
        time-format="A hh:mm:ss"
        unlink-panels
      >
        <template #prev-month>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M15 18l-6-6 6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
        <template #next-month>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M9 18l6-6-6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
        <template #prev-year>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M18 18l-6-6 6-6M11 18l-6-6 6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
        <template #next-year>
          <svg class="nav-icon" viewBox="0 0 24 24" fill="none">
            <path d="M6 18l6-6-6-6M13 18l6-6-6-6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
          </svg>
        </template>
      </FxDatePicker>
    </div>
  </div>
</template>

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

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

<style scoped>
.demo-datetime-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;
}
.block {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.demonstration {
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
.nav-icon {
  width: 1em;
  height: 1em;
}
</style>

扩展能力

除上述能力外，FxDatePicker 在 datetime / datetimerange 类型下还支持失焦保存（save-on-blur）、聚焦自动展开（automatic-dropdown）、触发表单校验（validate-event）等扩展属性，详见下方 API。

API

Attributes

属性	说明	类型	默认值
model-value / v-model	绑定值，range 时数组长度为 2	number | string | Date | array	—
readonly	是否只读	boolean	false
disabled	是否禁用	boolean	false
editable	输入框是否可键入	boolean	true
clearable	是否显示清空按钮	boolean	true
size	输入框尺寸	'large' | 'default' | 'small'	default
placeholder	非范围模式的占位	string	—
start-placeholder	范围模式起始占位	string	—
end-placeholder	范围模式结束占位	string	—
arrow-control	是否使用箭头按钮选时间	boolean	false
type	选择器类型	'year' | 'month' | 'date' | 'datetime' | 'week' | 'datetimerange' | 'daterange'	date
format	输入框显示格式	string	YYYY-MM-DD HH:mm:ss
popper-class	下拉自定义类名	string	—
popper-style	下拉自定义样式	string | object	—
popper-options	透传浮层选项	object	{}
fallback-placements	浮层备选位置列表	Placement[]	['bottom','top','right','left']
placement	浮层位置	Placement	bottom
range-separator	范围分隔符	string	'-'
default-value	默认聚焦日期	Date | [Date, Date]	—
default-time	选日期时使用的时间	Date | [Date, Date]	—
value-format	绑定值格式，未指定则绑定 Date 对象	string	—
date-format	面板内日期显示格式	string	YYYY-MM-DD
time-format	面板内时间显示格式	string	HH:mm:ss
id	原生 id	string | [string, string]	—
name	原生 name	string | [string, string]	—
unlink-panels	范围模式两面板独立翻月	boolean	false
single-panel	范围模式仅展示一面板	boolean	false
prefix-icon	自定义前缀图标	string | Component	ep:calendar
clear-icon	自定义清空图标	string | Component	ep:circle-close
shortcuts	快捷选项数组	Array<{ text: string; value: Date | Function }>	—
disabled-date	禁用日期判定函数，返回 Boolean	(date: Date) => boolean	—
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[]	—
cell-class-name	单元格自定义类	(date: Date) => string	—
teleported	是否将下拉挂载到 body	boolean	true
empty-values	组件的空值列表	array	—
value-on-clear	清空时回填的值	string | number | boolean | Function	—
show-now	是否显示「此刻」按钮	boolean	true
show-footer	是否显示底部按钮区	boolean	true
show-confirm	是否显示确认按钮	boolean	true
show-week-number	是否显示周数	boolean	false
save-on-blur	失焦时是否保存当前时间值	boolean	true
automatic-dropdown	聚焦输入框时自动展开面板	boolean	true
validate-event	是否触发表单校验	boolean	true
tabindex	输入框 tabindex	string | number	0
aria-label	a11y 标签	string	—

Events

事件名	说明	类型
change	用户确认选值或点击外部时触发	(val) => void
blur	输入框失焦时触发	(e: FocusEvent) => void
focus	输入框聚焦时触发	(e: FocusEvent) => void
clear	点击清空按钮时触发	() => void
calendar-change	面板日期交互时触发，仅 range	(val: [Date, null | Date]) => void
panel-change	点击导航按钮时触发	(date: Date | [Date, Date], mode: 'month' | 'year', view?: string) => void
visible-change	下拉显隐时触发	(visible: boolean) => void

Slots

插槽名	说明
default	自定义单元格内容
range-separator	自定义范围分隔内容
prev-month	上月导航图标
next-month	下月导航图标
prev-year	上年导航图标
next-year	下年导航图标

Exposes

方法	说明	类型
focus	聚焦输入框	() => void
blur	失焦输入框	() => void

类型声明

展开查看

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