TechUI Docs

简中

EN

简中

EN

主题

时间选择器 (原生) ​

TuiTimePickerNative 是基于浏览器原生 <input type="date/time/..."> 封装的组件。 它利用了操作系统自带的时间选择控件（如移动端的滚轮、桌面的原生日历），具有体积小、在移动端体验极佳的特点。

兼容性提示

本组件依赖浏览器原生实现。

  1. UI 差异: 不同浏览器（Chrome, Safari, Firefox）和不同操作系统（Win, Mac, Android, iOS）下的弹窗样式完全不同。
  2. 功能支持: type="datetime" 在内部被转换为 datetime-local。
  3. Firefox/Safari: 部分类型（如 week, month）在 Firefox 或旧版 Safari 中可能不被支持，会回退为普通的文本输入框。

基础用法 ​

日期与时间 ​

通过 type 属性控制选择器类型。

  • date (默认): 选择年月日。
  • datetime: 选择年月日及时间（内部渲染为 type="datetime-local"）。
  • time: 仅选择时间。
html
<script setup>
import { ref } from 'vue';
const dateVal = ref('');
const timeVal = ref('');
</script>

<template>
  <div class="demo-gap">
    <TuiTimePickerNative v-model="dateVal" type="date" placeholder="选择日期" />
    <TuiTimePickerNative v-model="timeVal" type="time" placeholder="选择时间" />
  </div>
</template>

底层依赖 Day.js ​

为了在原生控件的基础上提供灵活的格式化显示能力，本组件底层使用了 Day.js 库进行日期的解析与格式化。

这意味着：

  1. 格式标准: format 属性完全支持 Day.js 的格式占位符（例如 YYYY 代表四位年份，MM 代表两位月份）。
  2. 鲁棒性: 组件能够自动处理原生 Input 返回的标准 ISO 格式字符串，并将其转换为您指定的阅读格式。

格式化显示 ​

虽然原生 Input 的 value 始终遵循 ISO 标准格式（如 YYYY-MM-DD），但本组件支持通过 format 属性自定义显示在输入框中的文本格式。

原理

组件内部维护了一个用于显示的文本框和一个隐藏的原生 Input。当用户选择原生日期后，组件使用 dayjs 将其格式化后展示给用户，但 v-model 绑定的值仍然是标准格式。

html
<template>
  <TuiTimePickerNative 
    type="date" 
    v-model="val1" 
    format="YYYY年MM月DD日" 
  />

  <TuiTimePickerNative 
    type="datetime" 
    v-model="val2" 
    format="YYYY/MM/DD HH:mm" 
  />
</template>

其他类型 ​

支持选择月份和周数。

  • month: 选择年月。
  • week: 选择某年的第几周。

注意: 请务必在 Chrome/Edge 等 Webkit 内核浏览器中测试此功能，Firefox 可能不支持。

html
<template>
  <TuiTimePickerNative type="month" format="YYYY年MM月" />
  <TuiTimePickerNative type="week" format="YYYY年第WW周" />
</template>

限制与状态 ​

支持原生 Input 的大部分约束属性。

  • min / max: 限制可选择的日期范围。
  • step: 设置时间步长（例如 step="60" 表示秒）。
  • clearable: 是否显示清空按钮。
  • disabled / readonly: 禁用或只读。
html
<template>
  <TuiTimePickerNative 
    type="date" 
    min="2023-01-01" 
    max="2023-12-31" 
    clearable 
    placeholder="2023年内有效" 
  />
</template>

API 参考 ​

Props ​

属性名类型默认值说明
modelValueString/Date-绑定值。
typeString'date'类型。可选：date, time, datetime (映射为 datetime-local), month, week。
formatString-显示在输入框中的格式化字符串（基于 Day.js 规范）。
sizeString'default'尺寸。可选：large, default, small。
clearableBooleanfalse是否可清空。
placeholderString-占位文本。
minString-原生属性，允许的最小值。
maxString-原生属性，允许的最大值。
stepString/Number-原生属性，步长。
disabledBooleanfalse是否禁用。
readonlyBooleanfalse是否只读。
prefixIconString-头部图标类名。
suffixIconString-尾部图标类名。

Events ​

事件名说明回调参数
update:modelValue绑定值变化时触发。(value)
change失去焦点且值改变时触发。(value)
focus获得焦点时触发。(event)
blur失去焦点时触发。(event)
clear点击清空按钮时触发。-

Exposed Methods ​

方法名说明
focus使输入框获取焦点。
blur使输入框失去焦点。
openPicker核心功能。手动触发显示原生日期选择弹窗（模拟点击）。