支持 Vue2/Vue3 版本 无差别使用

安装

npm i @blueking/date-picker

使用

• vue3框架下使用

<template>
  <div class="app">
    <DatePicker
      v-model="value"
      v-model:timezone="timezone"
      default-format="YYYY-MM-DD HH:mm:ss"
      :behavior="'normal'"
      :version="2"
      :disabled="false"
      @update:model-value="handleValueChange"
    />
  </div>
</template>
<script setup lang="ts">
import { ref } from 'vue';

import DatePicker from '@blueking/date-picker';
import DatePicker from '@blueking/date-picker/vue3/vue3.css';


const value = ref(['now-2d/d', 'now',]);
const timezone = ref('Asia/Shanghai');
const handleValueChange = (value, info) => {
  console.log(value, info);
};
</script>

• vue2框架下使用

<template>
  <div class="hello">
    <DatePicker
      :modelValue="modelValue"
      :timezone.sync="timezone"
      @update:modelValue="handleValueChange"/>
  </div>
</template>

<script>
import DatePicker from '@blueking/date-picker/vue2'
import '@blueking/date-picker/vue2/vue2.css'
export default {
  data(){
      return {
        modelValue: ['now-2d/d', 'now'],
        timezone: 'Asia/Shanghai'
    }
  },
  components: {
    DatePicker
  },
  methods: {
    handleValueChange(v, info) {
      console.log(v, info)
      this.modelValue = v
    }
  }
}
</script>

自定义日期面板

面板默认停留在上次使用的 Tab；没有使用记录时按当前值推断（如 ['now-1h', 'now'] 进「最近」），推断不出对应 Tab 时进「日期选择」。

「日期选择」Tab 的起止时间在同一个输入框内，点击输入框后弹出日期时间选择面板（默认不展开）：

• 一次性跨范围选择：在双月日历上第一次点击定开始日期、第二次定结束日期，中间实时预览高亮；若第二次点在开始日期之前会自动交换两端。
• 时间滑块：面板底部是 0~24 小时的时间轴，Start / End 两个游标分别控制起止时刻，按分钟步进。游标支持键盘操作：Tab 聚焦后用 ← / → 按分钟步进，按住 Shift 则按小时步进。两个游标允许重叠，跨天时也允许 End 落在 Start 左侧。
• 时刻输入：滑块上方的两个输入框可直接输入 9:00:00 这类文本，与滑块双向联动，解析失败会回滚到原值。
• 设为 now：勾选「开始时间设为 <now>」或「结束时间设为 <now>」后，对应一端固定为相对时间 now，日历退化为单选并提示还需要选哪一端。两者互斥。从「最近」「未来」「自然日期」切到本 Tab 时，起止时间都会按当前时刻换成固定时间，不会自动勾选 now。
• 提交时机：点击面板内的「确认」即最终提交，同时关闭面板；「取消」放弃本次编辑。

起止输入框同样支持直接输入 now、now-1d 等相对时间语法。

时间格式转换

「日期选择」Tab 的输入框下方默认展示「时间格式转换」入口，展开后可在预置格式列表中切换展示格式，当前生效的格式会高亮标记。不需要该入口时传 :enable-format-click="false" 关闭。

展示格式支持受控与非受控两种用法：

• 非受控：只传 defaultFormat（或都不传，用默认值），点击列表项后组件内部立即切换，同时抛出 update:format。
• 受控：传入 format，此时组件不再自行改写格式，点击只抛出 update:format，需外部回写 format 才会生效。推荐直接用 v-model:format。

<!-- 非受控：初始格式由 defaultFormat 决定 -->
<DatePicker
  v-model="value"
  default-format="YYYY-MM-DD HH:mm:ss"
/>

<!-- 受控：格式完全由外部 format 决定 -->
<DatePicker
  v-model="value"
  v-model:format="format"
/>

智能解析

enableSmartParse 开启后，面板顶部会出现「选择时间范围」标题栏和一个自然语言输入框，面板展开时光标默认落在这里。输入描述后点「智能解析」或按 Enter 触发解析，解析结果以气泡形式展示在输入框下方，点「直接应用」即提交并关闭整个面板。

解析能力由宿主实现，组件不内置任何 AI 或 HTTP 请求，只负责调度与状态展示。smartParse 返回一个 DateValue（即 [开始, 结束]，端点支持时间戳、日期字符串和 now-1d 这类相对语法），失败时 throw 或 reject 一个 Error，组件会把 error.message 展示在气泡里。

解析结果仍会经过 validDateRange、minDuration、maxDuration 校验，不通过时只提示原因、不允许应用。enableSmartParse 开启但没传 smartParse 时入口不会展示，并在控制台给出错误提示。

• vue3 框架下使用

<template>
  <DatePicker
    v-model="value"
    :enable-smart-parse="true"
    :smart-parse="smartParse"
  />
</template>
<script setup lang="ts">
import { ref } from 'vue';

import DatePicker, { type DateValue } from '@blueking/date-picker';

const value = ref(['now-2d/d', 'now']);
const smartParse = async (text: string): Promise<DateValue> => {
  const res = await fetch('/api/parse-time-range', {
    method: 'POST',
    body: JSON.stringify({ text }),
  });
  if (!res.ok) throw new Error('解析服务不可用，请稍后重试');
  const { start, end } = await res.json();
  return [start, end];
};
</script>

• vue2 框架下使用

<template>
  <DatePicker
    :modelValue="modelValue"
    :enableSmartParse="true"
    :smartParse="smartParse"
    @update:modelValue="handleValueChange"/>
</template>

<script>
import DatePicker from '@blueking/date-picker/vue2'
import '@blueking/date-picker/vue2/vue2.css'
export default {
  components: { DatePicker },
  data() {
    return {
      modelValue: ['now-2d/d', 'now']
    }
  },
  methods: {
    async smartParse(text) {
      const { start, end } = await this.$http.post('/api/parse-time-range', { text })
      return [start, end]
    },
    handleValueChange(v) {
      this.modelValue = v
    }
  }
}
</script>

日期值与时区的解析规则

modelValue、validDateRange、commonUseList 里的日期值统一按下表解析：

| 值类型 | 解析方式 | | ------------------------------------------------------- | ------------------------------------ | | 时间戳、dayjs 实例 | 绝对时刻，timezone 只影响展示 | | 带时区信息的字符串，如 2024-01-02T12:00:00Z、+08:00 | 同上，绝对时刻 | | 不带时区信息的字符串，如 2024-01-02 12:00:00 | 按 timezone 解释为该时区的本地时间 | | now、now-1h、now/d 等相对表达式 | 按当前时刻计算 |

即 timezone 为 Asia/Tokyo 时传入 '2024-01-02 12:00:00'，表示东京时间 12:00，与在面板输入框里手动输入同一段文本的结果一致，与浏览器所在时区无关。

时区本身也支持受控与非受控两种用法：

• 非受控：不传 timezone，初始取浏览器时区，在面板「时区设置」里切换后组件内部立即生效，同时抛出 update:timezone。
• 受控：传入 timezone，此时组件不再自行改写时区，切换只抛出 update:timezone，需外部回写才会生效。推荐直接用 v-model:timezone。

时区变化后展示文本会按新时区重算。注意上表中不带时区信息的字符串本身就是按 timezone 解释的本地时间，所以切换时区时它的展示文本不会变化。

可选范围与跨度校验

• validDateRange 限定可选的日期范围。超出范围的日期在日历中置灰，常用/最近列表中的对应项置灰并给出原因，各面板提交时也会拦截。与范围有交集的日期即可点选，因此范围端点不在零点时，首尾两天仍然可选。
• minDuration / maxDuration 限定可选的时间跨度（毫秒）。不满足的常用/最近列表项会置灰，自定义范围等面板在点击「确认」时校验并提示。

属性列表

| 属性名 | 描述 | 属性类型 | 默认值 | | ----------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------- | | behavior | 组件展示风格 | 'normal' \| 'simplicity' | 'normal' | | commonUseList | 常用列表 | DateValue[] | | | defaultFormat | 日期转换显示格式，非受控，仅作为初始值 | string | 'YYYY-MM-DD HH:mm:ss' | | disabled | 是否禁用 | boolean | | | format | 日期转换显示格式，受控，传入后需配合 update:format 回写生效 | string | | | modelValue | 日期值 | DateValue \| dayjs.Dayjs[] \| number[] \| string[] \| undefined | | | needTimezone | 是否展示时区 | boolean | | | timezone | 时区值，受控，传入后需配合 update:timezone 回写生效 | string | 浏览器时区 | | validDateRange | 有效可选的日期范围 | DateValue \| undefined | | | version | 版本号 用于控制本地缓存 | number \| string | '1.0' | | minDuration | 最小可选时间跨度毫秒值 | number | | | maxDuration | 最大可选时间跨度毫秒值 | number | | | enableFormatClick | 是否展示「时间格式转换」入口 | boolean | true | | enableSmartParse | 是否展示「智能解析」入口，需同时传入 smartParse | boolean | false | | smartParse | 自然语言解析能力，由宿主实现 | (text: string) => DateValue \| Promise<DateValue> | |

事件列表

| 事件名 | 参数 | 参数类型 | 描述 | | ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------ | | update:modelValue | value, info | value: IDatePickerProps['modelValue']info: Array{dayjs: dayjs.Dayjs \| null;formatText: null | string;} | 更新date值的事件，以及相关信息 | | update:timezone | value, timezoneInfo | value: stringtimezoneInfo: ITimezoneItem | 更新时区值的事件，以及时区信息 | | update:format | value | value: string | 更新时间格式的值 |

TimezonePicker 时区选择器

支持 Vue2/Vue3 版本使用

时区选择器组件，支持搜索和选择全球时区。

注：TimezonePicker 组件来源于 Select组件 所以这里 select 的所有属性和事件都一致使用

使用

• vue3框架下使用

<template>
  <div class="app">
    <TimezonePicker
      v-model:value="timezone"
      :timezoneOptions="customTimezoneOptions"
      @update:value="handleTimezoneChange"
    />
  </div>
</template>
<script setup lang="ts">
import { ref } from 'vue';

import { TimezonePicker } from '@blueking/date-picker';
import '@blueking/date-picker/vue3/vue3.css';

const timezone = ref('Asia/Shanghai');
const customTimezoneOptions = ref(); // 可选，自定义时区选项

const handleTimezoneChange = (value, timezoneInfo) => {
  console.log('选中的时区:', value);
  console.log('时区信息:', timezoneInfo);
};
</script>

• vue2框架下使用

<template>
  <div class="hello">
    <TimezonePicker
      :value="timezone"
      :timezoneOptions="customTimezoneOptions"
      @update:value="handleTimezoneChange"
      @change="handleTimezoneChange"
    />
  </div>
</template>

<script>
import {TimezonePicker } from '@blueking/date-picker/vue2'
import '@blueking/date-picker/vue2/vue2.css'

export default {
  data() {
    return {
      timezone: 'Asia/Shanghai',
      customTimezoneOptions: undefined // 可选，自定义时区选项
    }
  },
  components: {
    TimeZonePicker
  },
  methods: {
    handleTimezoneChange(value, timezoneInfo) {
      console.log('选中的时区:', value);
      console.log('时区信息:', timezoneInfo);
      this.timezone = value;
    }
  }
}
</script>

TimezonePicker 属性列表

| 属性名 | 描述 | 属性类型 | 默认值 | | --------------- | ------------------ | ------------------ | ---------------- | | value | 当前选中的时区值 | string | | | timezoneOptions | 自定义时区选项列表 | ITimeZoneGroup[] | 内置全球时区列表 |

TimezonePicker 事件列表

| 事件名 | 参数 | 参数类型 | 描述 | | ------------ | ------------------- | ------------------------------------------ | ------------------------------ | | update:value | value, timezoneInfo | value: string``timezoneInfo: ITimezoneItem | 更新时区值的事件，以及时区信息 |

类型定义

interface ITimezoneItem {
  abbreviation?: string; // 时区缩写
  country?: string; // 国家名称
  countryCode?: string; // 国家代码
  label: string; // 时区标识符（如 Asia/Shanghai）
  utc?: string; // UTC偏移量（如 UTC+08:00）
}

interface ITimeZoneGroup {
  label: string; // 分组标签
  options: ITimezoneItem[]; // 该分组下的时区选项
}