xtf-linkui

Appearance

xtf-datetime-picker ​

组件说明 ​

xtf-datetime-picker 是日期时间选择器组件，用于选择日期、时间或日期时间。支持多种模式（date/time/datetime/year-month）、日期范围选择、快捷选项、滚轮选择和玻璃拟态样式，适用于表单日期输入、预约时间和筛选条件等场景。

基础用法 ​

1. 日期选择 ​

通过 mode="date" 选择日期：

vue
<template>
  <view>
    <xtf-cell title="选择日期" :value="dateLabel" arrow @click="showDatePicker = true" />
    <xtf-datetime-picker
      v-model="dateValue"
      :show="showDatePicker"
      mode="date"
      title="选择日期"
      @confirm="onDateConfirm"
      @cancel="showDatePicker = false"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      dateValue: new Date().toISOString(),
      showDatePicker: false
    }
  },
  computed: {
    dateLabel() {
      if (!this.dateValue) return '请选择'
      const d = new Date(this.dateValue)
      return (
        d.getFullYear() +
        '/' +
        String(d.getMonth() + 1).padStart(2, '0') +
        '/' +
        String(d.getDate()).padStart(2, '0')
      )
    }
  },
  methods: {
    onDateConfirm(payload) {
      this.dateValue = payload.value
      this.showDatePicker = false
    }
  }
}
</script>

2. 时间选择 ​

通过 mode="time" 选择时间：

vue
<template>
  <view>
    <xtf-cell title="选择时间" :value="timeLabel" arrow @click="showTimePicker = true" />
    <xtf-datetime-picker
      v-model="timeValue"
      :show="showTimePicker"
      mode="time"
      title="选择时间"
      @confirm="onTimeConfirm"
      @cancel="showTimePicker = false"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      timeValue: '',
      showTimePicker: false
    }
  },
  computed: {
    timeLabel() {
      return this.timeValue || '请选择'
    }
  },
  methods: {
    onTimeConfirm(payload) {
      this.timeValue = payload.value
      this.showTimePicker = false
    }
  }
}
</script>

3. 日期时间选择 ​

通过 mode="datetime" 同时选择日期和时间：

vue
<template>
  <view>
    <xtf-cell
      title="选择日期时间"
      :value="datetimeLabel"
      arrow
      @click="showDatetimePicker = true"
    />
    <xtf-datetime-picker
      v-model="datetimeValue"
      :show="showDatetimePicker"
      mode="datetime"
      title="选择日期时间"
      @confirm="onDatetimeConfirm"
      @cancel="showDatetimePicker = false"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      datetimeValue: '',
      showDatetimePicker: false
    }
  },
  computed: {
    datetimeLabel() {
      return this.datetimeValue || '请选择'
    }
  },
  methods: {
    onDatetimeConfirm(payload) {
      this.datetimeValue = payload.value
      this.showDatetimePicker = false
    }
  }
}
</script>

4. 日期范围选择 ​

通过 range 启用范围选择模式：

vue
<template>
  <view>
    <xtf-cell title="选择日期范围" :value="rangeLabel" arrow @click="showRangePicker = true" />
    <xtf-datetime-picker
      v-model="rangeValue"
      :show="showRangePicker"
      mode="date"
      range
      title="选择日期范围"
      @confirm="onRangeConfirm"
      @cancel="showRangePicker = false"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      rangeValue: [],
      showRangePicker: false
    }
  },
  computed: {
    rangeLabel() {
      if (!this.rangeValue || !this.rangeValue.length) return '请选择'
      return this.rangeValue.join(' 至 ')
    }
  },
  methods: {
    onRangeConfirm(payload) {
      this.rangeValue = payload.value
      this.showRangePicker = false
    }
  }
}
</script>

全部属性 ​

属性类型默认值作用描述适用范围
showBooleanfalse是否显示选择器显示控制
value / modelValueString | Number | Date | Array''当前选中值双向绑定
modeString'date'datetime / date / time / year-month / month-day / hour-minute选择模式
showSecondsBooleanfalsedatetime 模式是否追加秒列；开启后日期时间回显包含秒精确时间选择
rangeBooleanfalse是否范围选择范围模式
variantString'glass'视觉变体视觉样式
layoutString'default'布局模式：default 为增强日期面板，system 为居中标题、关闭图标、连续滚轮选中条与底部双按钮系统日期时间选择
rangeSeparatorString'至'范围分隔符范围显示
shortcutsArray[]自定义快捷选项快捷选项
builtinShortcutsBooleantrue是否显示内置快捷选项内置快捷
minDateString | Number | Date''最小日期日期限制
maxDateString | Number | Date''最大日期日期限制
minHourString | Number0最小小时时间限制
maxHourString | Number23最大小时时间限制
minMinuteString | Number0最小分钟时间限制
maxMinuteString | Number59最大分钟时间限制
filterFunctionnull选项过滤函数过滤选项
formatterFunctionnull选项格式化函数格式化
titleString''选择器标题标题
showToolbarBooleantrue是否显示工具栏工具栏
loadingBooleanfalse是否加载中加载状态
confirmTextString''确认按钮文字按钮文字
cancelTextString''取消按钮文字按钮文字
closeOnClickOverlayBooleantrue点击遮罩是否关闭关闭行为
safeAreaInsetBottomBooleantrue是否适配底部安全区安全区
durationString | Number''动画时长动画
zIndexString | Number''层级层级
showHeroBooleantrue是否显示顶部预览区预览区
showHeroMeta / showCurrentValue / showRangeValueBooleantrueHero 元信息、单值和范围摘要开关Hero 区
loadingText / popupCustomClassString''加载文案和弹层类名工具栏/弹层
toolbarClass、heroClass、heroMetaClass、summaryClass、shortcutsClass、bodyClassString''对应区域类名；各区域均有同名 Style 属性样式
showShortcutsBooleantrue是否显示快捷选项快捷选项
showWheelBooleantrue是否显示滚轮滚轮
showColumnHeaderBooleantrue是否显示列标题列标题
customClassString''自定义类名样式覆盖
customStyleString | Object''自定义样式动态样式覆盖

事件 ​

事件名称触发时机回调参数参数说明
input / update:value / update:modelValue确认时触发(value)格式化值或范围数组
change / confirm确认时触发(payload)单值 { value, date, mode, range }；范围 { value, start, end, mode, range }
cancel点击取消按钮时触发--
shortcut-click点击快捷选项时触发(shortcut)快捷选项数据
update:show显示状态变化时触发(show: Boolean)显示状态

插槽 ​

插槽名作用域参数说明
hero{ range, mode, heroTitle, currentLabel, startLabel, endLabel, activeRangeKey, switchRangeKey }替换完整顶部预览区。
hero-meta{ range, mode, heroTitle }替换顶部标题区域。
range-summary{ startLabel, endLabel, activeRangeKey, switchRangeKey, rangeSeparator }替换范围选择的开始和结束摘要。
current-summary{ currentLabel, mode }替换单值选择的当前值摘要。
shortcuts{ shortcuts, handleShortcut }替换快捷项列表；通过 handleShortcut(item) 应用快捷项。

插槽使用示例 ​

vue
<template>
  <view>
    <xtf-button label="选择日期范围" @click="show = true" />
    <xtf-datetime-picker
      v-model="value"
      :show="show"
      range
      mode="date"
      @update:show="show = $event"
      @confirm="onConfirm"
    >
      <template #range-summary="{ startLabel, endLabel, activeRangeKey, switchRangeKey }">
        <view style="display: flex; justify-content: space-between; padding: 20rpx">
          <text
            @click="switchRangeKey('start')"
            :style="{ color: activeRangeKey === 'start' ? '#2563eb' : '#64748b' }"
            >开始：{{ startLabel }}</text>

          <text
            @click="switchRangeKey('end')"
            :style="{ color: activeRangeKey === 'end' ? '#2563eb' : '#64748b' }"
            >结束：{{ endLabel }}</text>

        </view>
      </template>
      <template #shortcuts="{ shortcuts, handleShortcut }">
        <view style="display: flex; padding: 0 24rpx 20rpx">
          <text
            v-for="item in shortcuts"
            :key="item.key"
            style="margin-right: 20rpx"
            @click="handleShortcut(item)"
            >{{ item.label }}</text>

        </view>
      </template>
    </xtf-datetime-picker>
  </view>
</template>

<script>
export default {
  data() {
    return { show: false, value: [] }
  },
  methods: {
    onConfirm({ value }) {
      this.value = value
    }
  }
}
</script>

主题说明 ​

  • 弹出层使用 xtf-popup 组件
  • 工具栏按钮使用 xtf-button 组件
  • 支持通过 variant 切换视觉风格
  • 滚轮区域使用 scroll-view 实现
  • 选中指示器使用 indicator 样式

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。

MIT Licensed

Copyright © 2026 xtf-linkui