uni_modules/neo-datetime-pro/readme.md

# neo-datetime-pro
高级日期时间选择器，支持日期/时间/范围选择、快捷选项、禁用规则等功能。
## 特性
- 单日期选择
- 日期范围选择（开始-结束）
- 时间选择（时/分/秒）
- 日期+时间组合选择
- 快捷选项（今天、最近7天、本月等）
- 禁用日期规则（自定义函数、最小/最大日期）
- 周序号显示
- 国际化支持（中文/英文）
- 移动端友好的底部弹出交互
- 全平台兼容
## 兼容性
| Vue2 | Vue3 | H5 | App | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ小程序 |
|------|------|----|----|--------|----------|--------|--------|---------|
| ✅   | ✅   | ✅ | ✅  | ✅     | ✅       | ✅     | ✅     | ✅      |
## 安装
在 HBuilderX 中右键 `uni_modules` 目录，选择 `从插件市场导入`，搜索 `neo-datetime-pro` 安装。
或者直接复制 `neo-datetime-pro` 目录到项目的 `uni_modules` 目录下。
## 快速开始
### 基础用法
```vue
<template>
  <neo-datetime-pro
    v-model="date"
    placeholder="请选择日期"
  />
</template>
<script>
export default {
  data() {
    return {
      date: ''
    }
  }
}
</script>
```
### 日期范围选择
```vue
<template>
  <neo-datetime-pro
    v-model="dateRange"
    type="daterange"
    placeholder="请选择日期范围"
  />
</template>
<script>
export default {
  data() {
    return {
      dateRange: []
    }
  }
}
</script>
```
### 日期时间选择
```vue
<template>
  <neo-datetime-pro
    v-model="datetime"
    type="datetime"
    format="YYYY-MM-DD HH:mm:ss"
    placeholder="请选择日期时间"
  />
</template>
<script>
export default {
  data() {
    return {
      datetime: ''
    }
  }
}
</script>
```
### 时间选择
支持根据 `format` 自动显示时间部分：
```vue
<template>
  <!-- 时分秒 -->
  <neo-datetime-pro
    v-model="time1"
    type="time"
    format="HH:mm:ss"
    placeholder="请选择时间"
  />
  
  <!-- 仅时分 -->
  <neo-datetime-pro
    v-model="time2"
    type="time"
    format="HH:mm"
    placeholder="请选择时间"
  />
  
  <!-- 仅小时 -->
  <neo-datetime-pro
    v-model="time3"
    type="time"
    format="HH"
    placeholder="请选择小时"
  />
</template>
<script>
export default {
  data() {
    return {
      time1: '',
      time2: '',
      time3: ''
    }
  }
}
</script>
```
### 快捷选项
```vue
<template>
  <neo-datetime-pro
    v-model="dateRange"
    type="daterange"
    :shortcuts="shortcuts"
    placeholder="请选择日期范围"
  />
</template>
<script>
export default {
  data() {
    return {
      dateRange: [],
      shortcuts: [
        { text: '今天', value: 'today' },
        { text: '昨天', value: 'yesterday' },
        { text: '最近7天', value: 'last7days' },
        { text: '最近30天', value: 'last30days' },
        { text: '本周', value: 'thisweek' },
        { text: '本月', value: 'thismonth' }
      ]
    }
  }
}
</script>
```
### 禁用日期
```vue
<template>
  <neo-datetime-pro
    v-model="date"
    :disabled-date="disabledDate"
    placeholder="请选择日期"
  />
</template>
<script>
export default {
  data() {
    return {
      date: ''
    }
  },
  methods: {
    // 禁用过去的日期
    disabledDate(date) {
      return date < new Date()
    }
  }
}
</script>
```
### 最小/最大日期限制
```vue
<template>
  <neo-datetime-pro
    v-model="date"
    :min-date="minDate"
    :max-date="maxDate"
    placeholder="请选择日期"
  />
</template>
<script>
export default {
  data() {
    return {
      date: '',
      minDate: '2025-01-01',
      maxDate: '2025-12-31'
    }
  }
}
</script>
```
### 使用服务器时间
```vue
<template>
  <neo-datetime-pro
    v-model="date"
    :current-time="serverTime"
    placeholder="请选择日期"
  />
</template>
<script>
export default {
  data() {
    return {
      date: '',
      serverTime: null
    }
  },
  async mounted() {
    // 从接口获取服务器时间
    const res = await api.getServerTime()
    this.serverTime = res.data.time // 支持 Date对象、时间戳、字符串
  }
}
</script>
```
## API
### Props
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| modelValue / v-model | String / Array / Date | - | 绑定值 |
| type | String | date | 选择器类型：date/datetime/time/daterange/datetimerange |
| format | String | YYYY-MM-DD | 日期/时间格式，时间选择器会根据 format 智能显示列：<br>• `YYYY-MM-DD` 日期<br>• `YYYY-MM-DD HH:mm:ss` 日期时间<br>• `HH:mm:ss` 时分秒<br>• `HH:mm` 仅时分<br>• `HH` 仅小时 |
| placeholder | String | 请选择 | 占位文本 |
| disabled | Boolean | false | 是否禁用 |
| readonly | Boolean | false | 是否只读 |
| clearable | Boolean | true | 是否显示清空按钮 |
| shortcuts | Array | [] | 快捷选项 |
| disabledDate | Function | - | 禁用日期函数，返回 true 表示禁用 |
| minDate | String / Date | - | 最小日期 |
| maxDate | String / Date | - | 最大日期 |
| showWeekNumber | Boolean | false | 是否显示周序号 |
| locale | String | zh | 语言：zh/en |
| startOfWeek | Number | 0 | 周起始日：0（周日）- 6（周六） |
| currentTime | Date / String / Number | null | 当前时间（支持从接口获取），未传入时使用客户端时间 |
### Events
| 事件名 | 参数 | 说明 |
|--------|------|------|
| change | value | 选中值改变时触发 |
| confirm | value | 点击确定按钮时触发 |
| clear | - | 点击清空按钮时触发 |
### Shortcuts 快捷选项格式
```javascript
[
  { text: '今天', value: 'today' },
  { text: '昨天', value: 'yesterday' },
  { text: '最近7天', value: 'last7days' },
  { text: '最近30天', value: 'last30days' },
  { text: '本周', value: 'thisweek' },
  { text: '本月', value: 'thismonth' },
  // 自定义快捷选项
  { 
    text: '自定义', 
    value: () => {
      return ['2025-01-01', '2025-12-31']
    }
  }
]
```
## 使用建议
1. **日期格式**：支持常见格式如 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss` 等
2. **智能时间格式**：时间选择器会根据 `format` 自动显示对应的列
   - `HH:mm:ss` 显示时/分/秒三列
   - `HH:mm` 显示时/分两列
   - `HH` 仅显示小时一列
3. **范围选择**：`daterange` 和 `datetimerange` 模式下，v-model 绑定数组 `[startDate, endDate]`
4. **禁用规则**：`disabledDate` 函数接收日期对象，返回 `true` 表示禁用该日期
5. **快捷选项**：支持内置值（today、yesterday等）和自定义函数
6. **移动端优化**：底部弹出交互，触摸友好
## 常见问题
### 1. 如何禁用周末？
```javascript
disabledDate(date) {
  const day = date.getDay()
  return day === 0 || day === 6 // 0=周日, 6=周六
}
```
### 2. 如何设置默认值？
```javascript
data() {
  return {
    date: '2025-10-30' // 字符串格式
    // 或
    date: new Date() // Date 对象
  }
}
```
### 3. 如何获取时间戳？
```javascript
@change="handleChange"
methods: {
  handleChange(value) {
    const timestamp = new Date(value).getTime()
    console.log(timestamp)
  }
}
```
## 许可
MIT License
## 更新日志
见 [changelog.md](./changelog.md)