更新记录

0.1（2025-11-12）

第一版

平台兼容性

uni-app(4.85)

其他

ys-dateime-picker 预约时间选择器组件说明文档

1. 组件介绍

ys-dateime-picker 是一款高精度预约时间选择组件，支持用户选择 年、月、日、小时、分钟，并可灵活配置预约规则（如预约后延天数、每日可预约时段、分钟选择颗粒度），适用于各类需要精准预约的场景（如服务预约、订单预约等）。

2. 核心特性

• 时间维度完整：支持年、月、日、小时、分钟五级选择
• 预约规则可控：可指定预约后延天数、每日可预约小时区间
• 分钟颗粒度固定：默认 15 分钟为单位（如 00 分、15 分、30 分、45 分）
• 双向交互：选择后触发回调，支持默认值预设
• 状态反馈：未选择时显示提示文本，已选择时高亮显示选中值

3. 基础用法

3.1 组件引入与使用

<template>
  <ys-dateime-picker 
    @change="onTimeChange" 
    :defaultValue="defaultTime" 
    daysLater="0" 
    :debug="false" 
    hourRange="9,22"
  >
    <!-- 选择器触发文本（未选择时显示提示，已选择时显示选中时间） -->
    <text :class="{ 'value': selectedTime !== null }">
      {{ selectedTime || '请选择预约时间' }}
    </text>
  </ys-dateime-picker>
</template>

<script>
export default {
  data() {
    return {
      defaultTime: '', // 默认选中时间（格式：YYYY-MM-DD HH:mm）
      selectedTime: null // 存储选中的时间
    };
  },
  methods: {
    // 时间选择变化回调函数
    onTimeChange(time) {
      console.log('选中的时间：', time); // 输出格式：YYYY-MM-DD HH:mm
      this.selectedTime = time; // 更新选中时间状态
    }
  }
};
</script>

<style>
/* 已选择状态文本样式（可自定义） */
.value {
  color: #1989fa; /* 示例：蓝色高亮 */
  font-weight: 500;
}
</style>

3.2 效果说明

• 未选择时：显示提示文本 请选择预约时间
• 选择后：显示格式化时间（如 2024-05-20 14:30），并触发 onTimeChange 回调
• 分钟选择项固定为：00、15、30、45（不可修改）

4. 属性说明

4.1 属性约束说明

• hourRange 必须满足：
  • 格式为「数字,数字」（中间无空格）
  • 开始小时 < 结束小时
  • 取值范围为 0-23（如 0,24 无效，需写 0,23）
• defaultValue 需满足：
  • 日期必须 ≥「当前日期 + daysLater 天」
  • 小时必须在 hourRange 范围内
  • 分钟必须为 00、15、30、45 中的一个
  • 格式错误时，组件会忽略该默认值（显示为未选择状态）

5. 事件说明

6. 常见配置示例

6.1 基础配置（默认规则）

<!-- 可预约今天，每日 9:00-22:00，无默认值 -->
<ys-dateime-picker @change="onTimeChange">
  <text :class="{ 'value': selectedTime !== null }">{{ selectedTime || '请选择预约时间' }}</text>
</ys-dateime-picker>

6.2 预约后延 1 天，可预约时段 8:00-18:00

<!-- 最早可预约明天，每日 8:00-18:00 -->
<ys-dateime-picker 
  @change="onTimeChange" 
  daysLater="1" 
  hourRange="8,18"
>
  <text :class="{ 'value': selectedTime !== null }">{{ selectedTime || '请选择预约时间' }}</text>
</ys-dateime-picker>

6.3 设置默认预约时间

<template>
  <ys-dateime-picker 
    @change="onTimeChange" 
    :defaultValue="defaultTime" 
    daysLater="0" 
    hourRange="9,22"
  >
    <text :class="{ 'value': selectedTime !== null }">{{ selectedTime || '请选择预约时间' }}</text>
  </ys-dateime-picker>
</template>

<script>
export default {
  data() {
    return {
      defaultTime: '2024-05-20 10:30', // 默认选中 2024-05-20 10:30
      selectedTime: '2024-05-20 10:30'
    };
  },
  // ...其他代码
};
</script>

6.4 开启调试模式

<ys-dateime-picker 
  @change="onTimeChange" 
  :debug="true" 
  daysLater="2" 
  hourRange="10,19"
>
  <text :class="{ 'value': selectedTime !== null }">{{ selectedTime || '请选择预约时间' }}</text>
</ys-dateime-picker>

• 开启后，控制台会输出：
  • 组件初始化参数（daysLater、hourRange 等）
  • 可选时间范围（如「最早可预约日期：2024-05-22，最晚可预约小时：19:00」）
  • 选择过程中的校验日志（如「选中时间 2024-05-22 15:45 符合规则」）

7. 注意事项

1. 时间格式一致性：组件输出和 defaultValue 均使用 YYYY-MM-DD HH:mm 格式，请勿使用其他格式（如 MM/DD/YYYY）
2. 边界值处理：
   • 若 daysLater 设为 3，则当前日期为 2024-05-20 时，最早可预约日期为 2024-05-23
   • 若 hourRange 设为 22,23，则小时仅可选 22，分钟可选 00、15、30、45
3. 样式自定义：触发文本的样式（颜色、字体等）可通过自定义 class 调整（如示例中的 .value 类）
4. 兼容性：组件默认适配移动端，PC 端使用时可能需要额外调整样式（如选择器弹窗大小）