更新记录

1.13（2026-07-17） 下载此版本

优化样式。

1.12（2026-07-10） 下载此版本

优化组件。

1.11（2026-07-06） 下载此版本

优化日期范围选择。

平台兼容性

uni-app(4.76)

jx-datetime-picker 日期时间选择器

一个简洁易用的日期时间选择组件，支持多种日期格式和时间戳。

功能特性

• 支持多种日期模式：年、年月、年月日、年月日时、年月日时分、年月日时分秒、时分、时分秒、完整日期时间
• 支持字符串和时间戳两种返回格式
• 自动格式映射，根据模式自动匹配日期格式
• 智能解析，支持各种格式的输入
• 支持自定义 placeholder
• 支持多种边框模式：全边框、下边框、无边框
• 当值为 0 时显示 placeholder
• 支持清除功能，可控制是否显示清除按钮
• 支持日期范围选择（range 模式），可分别选择开始和结束日期

Props

格式映射

使用示例

基础用法

<template>
  <jx-datetime-picker
    v-model="date"
    mode="year-month-date"
    format="string"
  />
</template>

<script>
export default {
  data() {
    return {
      date: ''
    }
  }
}
</script>

显示 placeholder（值为 0 时）

<template>
  <jx-datetime-picker
    v-model="date"
    placeholder="请选择日期"
  />
</template>

<script>
export default {
  data() {
    return {
      date: 0  // 值为 0 时显示 placeholder
    }
  }
}
</script>

不同边框模式

<!-- 全边框（默认） -->
<jx-datetime-picker v-model="date" border-mode="full" />

<!-- 只有下边框 -->
<jx-datetime-picker v-model="date" border-mode="bottom" />

<!-- 无边框 -->
<jx-datetime-picker v-model="date" border-mode="none" />

清除功能

<!-- 支持清除，选中值后会出现清除按钮 -->
<jx-datetime-picker v-model="date" clearable />

<!-- 监听清除事件 -->
<jx-datetime-picker v-model="date" clearable @clear="handleClear" />

返回时间戳

<jx-datetime-picker
  v-model="date"
  mode="datetime"
  format="timestamp"
/>

不同模式示例

<!-- 只选择年 -->
<jx-datetime-picker v-model="year" mode="year" />

<!-- 选择年月 -->
<jx-datetime-picker v-model="yearMonth" mode="year-month" />

<!-- 选择年月日 -->
<jx-datetime-picker v-model="fullDate" mode="year-month-date" />

<!-- 选择年月日时 -->
<jx-datetime-picker v-model="dateHour" mode="year-month-date-hour" />

<!-- 选择年月日时分 -->
<jx-datetime-picker v-model="dateHourMin" mode="year-month-date-hour-minute" />

<!-- 选择年月日时分秒 -->
<jx-datetime-picker v-model="dateFull" mode="year-month-date-hour-minute-second" />

<!-- 选择时分 -->
<jx-datetime-picker v-model="hourMinute" mode="hour-minute" />

<!-- 选择时分秒 -->
<jx-datetime-picker v-model="time" mode="hour-minute-second" />

<!-- 完整日期时间 -->
<jx-datetime-picker v-model="datetime" mode="datetime" />

限制时间范围

可以使用 start 和 end 参数限制可选择的时间范围，支持时间戳和字符串两种格式：

<!-- 日期模式:使用字符串限制范围 -->
<jx-datetime-picker
  mode="year-month-date"
  start="2024-01-01"
  end="2024-12-31"
  v-model="date"
/>

<!-- 日期时间模式:使用时间戳限制范围 -->
<jx-datetime-picker
  mode="datetime"
  :start="1609459200000"
  :end="1640995200000"
  v-model="datetime"
  format="timestamp"
/>

<!-- 时分模式:限制营业时间 9:00-21:00 -->
<jx-datetime-picker
  mode="hour-minute"
  start="09:00"
  end="21:00"
  v-model="time"
/>

<!-- 时分秒模式:限制具体时间范围 -->
<jx-datetime-picker
  mode="hour-minute-second"
  start="09:00:00"
  end="18:00:00"
  v-model="time"
/>

重要说明

1. 纯时间模式（hour-minute、hour-minute-second）：

   • 只限制时间部分，不受日期影响
   • 支持格式："HH:mm" 或 "HH:mm:ss" 或 "H:mm"（小时可以是单数字）
   • 示例：
     • start="9:00" end="21:00" → 可选时间 9:00 到 21:00
     • start="09:00:00" end="18:00:00" → 可选时间 09:00:00 到 18:00:00
     • start="8:59:59" end="21:59:59" → 注意：小时8只能选59分钟

2. 日期模式（year-month-date、datetime 等）：

   • 限制完整的日期时间范围
   • 支持格式：
     • 时间戳（数字）：Date.now() 或 1609459200000
     • 完整日期时间："YYYY-MM-DD HH:mm:ss"
     • 完整日期："YYYY-MM-DD"
     • 年月："YYYY-MM"
     • 年份："YYYY"

3. 混合使用：

   <!-- 时间戳 + 字符串 -->
   <jx-datetime-picker
    mode="datetime"
    :start="Date.now()"
    end="2030-12-31 23:59:59"
   />
   
   <!-- 纯时间格式 -->
   <jx-datetime-picker
    mode="hour-minute"
    start="09:00"
    end="21:00"
   />

4. 联动效果：

   • 选择器会自动联动更新可选范围
   • 例如选择 2024年时，月份会自动限制；选择小时后，分钟会自动调整

5. 时间格式解析：

   • 组件会智能识别各种格式
   • 支持单数字小时："8:59" 和 "08:59" 都有效
   • 支持秒数省略："09:00" 会自动补齐为 "09:00:00"

事件监听

<jx-datetime-picker
  v-model="date"
  @change="handleDateChange"
  @clear="handleClear"
/>

change 事件

选择日期后触发：

{
  date: Date,          // 日期对象
  timestamp: Number,   // 时间戳
  formatted: String,   // 格式化字符串
  mode: String,        // 当前模式
  formatTemplate: String  // 格式模板
}

clear 事件

清除日期后触发（需设置 clearable），此时 v-model 的值会被设为 0。

日期范围选择（range 模式）

当设置 range 为 true 时，组件进入日期范围选择模式，用户可以分别选择开始日期和结束日期。

基本用法

<template>
  <!-- 启用范围选择模式 -->
  <jx-datetime-picker
    v-model="dateRange"
    mode="year-month-date"
    :range="true"
  />
</template>

<script>
export default {
  data() {
    return {
      dateRange: []  // 返回值：[开始时间戳, 结束时间戳]
    }
  }
}
</script>

返回值格式

在 range 模式下，v-model 绑定的值为数组格式 [开始时间戳, 结束时间戳]：

// 示例返回值
[1704067200000, 1704153599999]
// 对应：[2024-01-01 00:00:00, 2024-01-01 23:56:59.999]

结束时间自动补全

在 range 模式下，如果结束日期未设置时分秒，组件会自动补全为当天的 23:56:59.999：

// 用户选择结束日期为 2024-01-01（未选择时分秒）
// 实际返回值为：2024-01-01 23:56:59.999 的时间戳

// 用户选择结束日期为 2024-01-01 14:30（已选择时分）
// 实际返回值为：2024-01-01 14:30:00.000 的时间戳（不会补全）

完整示例

<template>
  <view>
    <!-- 基础范围选择 -->
    <jx-datetime-picker
      v-model="dateRange"
      mode="year-month-date"
      :range="true"
      placeholder="请选择"
    />

    <!-- 带时间的范围选择 -->
    <jx-datetime-picker
      v-model="datetimeRange"
      mode="year-month-date-hour-minute"
      :range="true"
      format="timestamp"
    />

    <!-- 限制范围 -->
    <jx-datetime-picker
      v-model="limitedRange"
      mode="year-month-date"
      :range="true"
      start="2024-01-01"
      end="2024-12-31"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      dateRange: [],          // [开始日期时间戳, 结束日期时间戳]
      datetimeRange: [],      // [开始时间时间戳, 结束时间时间戳]
      limitedRange: []        // 受限制的范围
    }
  },
  methods: {
    handleRangeChange(value) {
      console.log('开始时间:', new Date(value[0]).toLocaleString());
      console.log('结束时间:', new Date(value[1]).toLocaleString());
    }
  }
}
</script>

使用说明

1. 点击区域：点击"开始日期"区域选择开始日期，点击"结束日期"区域选择结束日期
2. 返回值：始终返回数组格式 [开始时间戳, 结束时间戳]
3. 结束时间补全：仅对结束日期生效，开始日期不会自动补全
4. 模式兼容：支持所有日期模式（year、year-month、year-month-date 等）
5. 时间模式：纯时间模式（hour-minute、hour-minute-second）也支持 range