时间选择器 (原生)

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: 仅选择时间。

<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 绑定的值仍然是标准格式。

<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 可能不支持。

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

限制与状态

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

• min / max: 限制可选择的日期范围。
• step: 设置时间步长（例如 step="60" 表示秒）。
• clearable: 是否显示清空按钮。
• disabled / readonly: 禁用或只读。

<template>
  <TuiTimePickerNative 
    type="date" 
    min="2023-01-01" 
    max="2023-12-31" 
    clearable 
    placeholder="2023年内有效" 
  />
</template>

API 参考

Props

属性名	类型	默认值	说明
modelValue	String/Date	-	绑定值。
type	String	'date'	类型。可选：date, time, datetime (映射为 datetime-local), month, week。
format	String	-	显示在输入框中的格式化字符串（基于 Day.js 规范）。
size	String	'default'	尺寸。可选：large, default, small。
clearable	Boolean	false	是否可清空。
placeholder	String	-	占位文本。
min	String	-	原生属性，允许的最小值。
max	String	-	原生属性，允许的最大值。
step	String/Number	-	原生属性，步长。
disabled	Boolean	false	是否禁用。
readonly	Boolean	false	是否只读。
prefixIcon	String	-	头部图标类名。
suffixIcon	String	-	尾部图标类名。

Events

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

Exposed Methods

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