vue-devui DatePickerPro 日期选择器实战指南:从基础用法到源码原理

原创2026-10-13 12:50:381,453 阅读
文章标签:前端UI组件设计系统

vue-devui DatePickerPro 日期选择器实战指南:从基础用法到源码原理

DatePickerPro 是 vue-devui 组件库中面向"输入或选择日期"场景的高阶日期选择器组件,包含单日期选择器 DDatePickerPro 与范围日期选择器 DRangeDatePickerPro 两套组件,支持日期/年/月三种选择粒度、时分秒时间联动、自定义面板插槽与日历范围控制。本文以官方组件文档为核心骨架,结合仓库源码(date-picker-pro 组件目录)逐层拆解每个配置项的作用与底层实现,读完你可以直接照着 Demo 落地一个可用的日期选择场景,并理解其"虚拟滚动日历面板 + FlexibleOverlay 弹层 + Form 表单联动"的设计原理。

组件定位与注册方式

DatePickerPro 属于"数据录入"类组件,在组件入口 date-picker-pro/index.ts 中同时导出并注册了 DDatePickerPro 与 DRangeDatePickerPro 两个组件:

export { DatePickerPro, DRangeDatePickerPro };

export default {
  title: 'DatePickerPro 日期选择器',
  category: '数据录入',
  status: '50%',
  install(app: App): void {
    app.component(DatePickerPro.name, DatePickerPro);
    app.component(DRangeDatePickerPro.name, DRangeDatePickerPro);
  },
};

其中 DatePickerPro.name 为 'DDatePickerPro',范围组件名为 'DRangeDatePickerPro'(见 date-picker-pro.tsx 与 range-date-picker-pro.tsx)。使用场景遵循官方文档:当用户需要输入一个日期时;需要点击标准输入框,弹出日期面板进行选择时。

基本用法:三种尺寸

DDatePickerPro 通过 v-model 双向绑定选中值,通过 size 控制输入框尺寸(sm / md / lg),默认尺寸为 md。

<template>
  <div class="picker-pro-format-demo mr30">
    <div class="mb10">Small</div>
    <d-date-picker-pro v-model="datePickerProValue" class="mb20 wh250" size="sm" />
  </div>
  <div class="picker-pro-format-demo mr30">
    <div class="mb10">Middle</div>
    <d-date-picker-pro v-model="datePickerProValue2" class="mb20 wh250" />
  </div>
  <div class="picker-pro-format-demo mr30">
    <div class="mb10">Large</div>
    <d-date-picker-pro v-model="datePickerProValue3" class="mb20 wh250" size="lg" />
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const datePickerProValue = ref<string>('');
    const datePickerProValue2 = ref<string>('');
    const datePickerProValue3 = ref<string>('');

    return {
      datePickerProValue,
      datePickerProValue2,
      datePickerProValue3,
    };
  },
});
</script>

<style>
.mb20 {
  margin-bottom: 20px;
}

.wh250 {
  width: 250px;
}
</style>

从源码看,size 的默认值与类型在 date-picker-pro-types.ts 的公共属性中定义,且支持 Form 上下文覆盖:usePickerPro 中 pickerSize = computed(() => formContext?.size || props.size),也就是说当组件被放入 DForm / DFormItem 时,会优先继承表单统一设置的尺寸。

显示时间:showTime 与时分秒联动

设置 :showTime="true" 后,日历面板右侧会联动出现时分秒时间选择区,此时需要配合 format 声明含时间的格式:

<template>
  <d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250" :showTime="true" format="YYYY/MM/DD HH:mm:ss" />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const datePickerProValue1 = ref<string>('');

    return {
      datePickerProValue1,
    };
  },
});
</script>

时间格式的默认值

format 的默认值会根据是否开启 showTime 自动切换,这一逻辑在 use-picker-pro.ts 中实现:

const format = computed(() => {
  return props.showTime ? props.format || DEFAULT_TIME : props.format || DEFAULT_DATE;
});

对应的默认常量定义在 const.ts:

export const DEFAULT_DATE = 'YYYY/MM/DD';
export const DEFAULT_TIME = `${DEFAULT_DATE} HH:mm:ss`;

即不传 format 时:未开启 showTime 默认显示 YYYY/MM/DD,开启后默认 YYYY/MM/DD HH:mm:ss。

日期与时间的合并逻辑

当同时选择日期和时间时,底层通过 use-date-picker.ts 的 getSelectedDate 把日历选中的日期与时间面板选中的时分秒合并:

const getSelectedDate = (date: Dayjs) => {
  // 日期加上时间
  const curDate = date.toDate().toLocaleDateString();
  const curDateTime = `${curDate} ${timeData.value || '00:00:00'}`;
  return dayjs(curDateTime).locale('zh-cn');
};

如果只选了日期未选时间,默认补 00:00:00;时间面板在 time-picker-panel.tsx 中渲染,时/分/秒三个列表的数据由 use-time-picker-panel.ts 基于 time-picker 的 initializeTimeData 初始化(小时 0-23、分钟/秒 0-59),复用 popup-line 作为滚动选择列表。测试用例 date-picker-pro.spec.tsx 专门校验了三个列表的渲染数量(24 / 60 / 60)。

自定义日历面板区域:rightArea 与 footer 插槽

日历面板提供两个插槽用于高度定制:rightArea 定制面板右侧内容(例如放置日期快捷选项),footer 定制面板下侧内容(例如放置"今天""清除时间"按钮):

<template>
  <div class="mb10">right area</div>
  <d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250" :showTime="true">
    <template #rightArea>
      <slot name="rightArea">
        <ul class="date-picker-right-panel">
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  setDate(-30);
                }
              "
            >
              一个月前
            </d-button>
            <span>{{ getDateString(-30) }}</span>
          </li>
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  setDate(-14);
                }
              "
            >
              两周前
            </d-button>
            <span>{{ getDateString(-14) }}</span>
          </li>
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  setDate(-7);
                }
              "
            >
              一周前
            </d-button>
            <span>{{ getDateString(-7) }}</span>
          </li>
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  setDate(0);
                }
              "
            >
              今天
            </d-button>
            <span>{{ getDateString(0) }}</span>
          </li>
        </ul>
      </slot>
    </template>
  </d-date-picker-pro>
  <div class="mb10">footer</div>
  <d-date-picker-pro v-model="datePickerProValue2" class="mb20 wh250" :showTime="true">
    <template #footer>
      <slot name="footer">
        <div class="date-picker-footer">
          <d-button variant="solid" color="secondary" @click="setToday"> 今天 </d-button>
          <d-button variant="solid" color="secondary" @click="clearDate"> 清除时间 </d-button>
        </div>
      </slot>
    </template>
  </d-date-picker-pro>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const datePickerProValue1 = ref<string | Date>('');
    const datePickerProValue2 = ref<string | Date>('');
    const setDate = (days: number) => {
      datePickerProValue1.value = new Date(new Date().getTime() + days * 24 * 3600 * 1000);
    };
    const getDateString = (days: number) => {
      const date = new Date(new Date().getTime() + days * 24 * 3600 * 1000);
      return `${date.getMonth() + 1}月${date.getDate()}日`;
    };
    const setToday = () => {
      datePickerProValue2.value = new Date(new Date().getTime());
    };
    const clearDate = () => {
      datePickerProValue2.value = '';
    };

    return {
      datePickerProValue1,
      datePickerProValue2,
      setDate,
      getDateString,
      setToday,
      clearDate,
    };
  },
});
</script>
<style>
.date-picker-right-panel {
  padding: 0;
  li {
    list-style-type: none;
    button {
      width: 66px;
    }
    span {
      margin-left: 8px;
    }
  }
}
.date-picker-footer {
  display: flex;
  justify-content: end;
  button {
    margin-left: 10px;
  }
}
</style>

插槽在组件内部的落地位置

面板组件 date-picker-panel.tsx 是插槽的实际消费方:

{ctx.slots?.rightArea && <div class={ns.e('panel-right-area')}>{ctx.slots?.rightArea()}</div>}
...
{ctx.slots?.footer && <div class={ns.e('panel-footer')}>{ctx.slots?.footer()}</div>}
{!ctx.slots?.footer && props.showTime && (
  <div class={ns.e('panel-footer')}>
    <div class={ns.e('panel-footer-center')}>
      <Button variant="solid" onClick={handlerConfirm}>{t('ok')}</Button>
    </div>
  </div>
)}

需要注意两个细节:

  • rightArea 插槽渲染在面板内容区的右侧(panel-right-area),footer 渲染在面板底部(panel-footer)。
  • 若未提供 footer 插槽且开启了 showTime,组件会自动渲染一个"确定"按钮,点击后触发 handlerConfirm 完成时间确认并关闭面板;提供 footer 插槽后则由插槽内容完全接管底部区域。

此外,两个插槽在单日期与范围组件中都通过 renderSlot 透传(见 date-picker-pro.tsx 与 range-date-picker-pro.tsx)。测试 date-picker-pro.spec.tsx 分别验证了 rightArea 中按钮点击后输入框值变为"30 天前"、footer 中按钮点击后值变为当天。

日期格式:format 的完整标识表

通过 format 指定输入框显示的日期格式,例如 YYYY-MM-DD。完整格式标识如下:

标识 示例 描述
YY 22 年,两位数
YYYY 2022 年,四位数
M 1-12 月,从 1 开始
MM 01-12 月,两位数字
MMM Jan-Dec 月,英文缩写
D 1-31 日
DD 01-31 日,两位数
H 0-23 24 小时
HH 00-23 24 小时,两位数
h 1-12 12 小时
hh 01-12 12 小时,两位数
m 0-59 分钟
mm 00-59 分钟,两位数
s 0-59 秒
ss 00-59 秒,两位数
<template>
  <div class="picker-pro-format-demo mr30">
    <div class="mb10">日期格式: YYYY-MM-DD</div>
    <d-date-picker-pro v-model="pickerProFormatValue" class="mb20 wh250" format="YYYY-MM-DD" />
  </div>
  <div class="picker-pro-format-demo">
    <div class="mb10">日期格式: YYYY-MM-DD HH:mm:ss</div>
    <d-date-picker-pro v-model="pickerProFormatValue1" class="mb20 wh250" :showTime="true" format="YYYY-MM-DD HH:mm:ss" />
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const pickerProFormatValue = ref<string>('');
    const pickerProFormatValue1 = ref<string>('');

    return {
      pickerProFormatValue,
      pickerProFormatValue1,
    };
  },
});
</script>
<style>
.picker-pro-format-demo {
  display: inline-block;
}
.mr30 {
  margin-right: 20px;
}
.mb10 {
  margin-bottom: 10px;
}
</style>

非法格式的兜底策略

从源码看,输入框展示的字符串由 utils.ts 的 formatDayjsToStr 生成,它会校验格式化结果是否为合法日期,非法格式自动回退到默认格式:

export const formatDayjsToStr = (date: Dayjs | undefined, format: string, type: string): string | null => {
  if (!date) {
    return null;
  }
  if (type === 'year') {
    return date.year().toString();
  } else if (type === 'month') {
    const month = date.month() + 1 < 10 ? '0' + (date.month() + 1) : date.month() + 1;
    return `${date.year()}-${month}`;
  } else {
    // 兼容非法格式(format),如果是非法格式,则使用默认格式(YYYY/MM/DD)
    return dayjs(date.format(format)).isValid() ? date.format(format) : date.format(DEFAULT_DATE);
  }
};

年月选择器:type 指定选择粒度

通过 type 指定选择器类型,可选 date / year / month,默认 date。当类型为 year 时输入框只展示年份(如 2022),为 month 时展示 YYYY-MM(如 2022-01):

<template>
  <div class="picker-pro-format-demo mr30">
    <div class="mb10">year picker</div>
    <d-date-picker-pro v-model="pickerProFormatValue" class="mb20 wh250" type="year" />
    <div class="mb10">month picker</div>
    <d-date-picker-pro v-model="pickerProFormatValue1" class="mb20 wh250" type="month" />
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const pickerProFormatValue = ref<string>('');
    const pickerProFormatValue1 = ref<string>('');
    return {
      pickerProFormatValue,
      pickerProFormatValue1,
    };
  },
});
</script>

三种面板的分派逻辑

type 决定面板组件渲染哪一种日历,分派逻辑在 date-picker-panel.tsx:

  • type === 'date' → CalendarPanel(日期日历面板),若 showTime 再叠加 TimerPickerPanel;
  • type === 'year' → YearCalendarPanel(纯年份滚动面板);
  • type === 'month' → MonthCalendarPanel(左侧年份 + 右侧 12 个月网格)。

年/月面板同样基于 VirtualList 虚拟滚动渲染(高度常量见 const.ts:年选择器列表高 yearPickerHeight = 186、单行高 yearCalendarItemHeight = 48;月选择器列表高 monthPickerHeight = 300、单行高 monthCalendarItemHeight = 186)。对应的测试 year-picker.spec.tsx 覆盖了年份选择、v-model 回显以及 calendarRange / limitDateRange 对年份的禁用控制。

范围选择器:DRangeDatePickerPro

DRangeDatePickerPro 提供开始/结束日期范围选择,v-model 绑定 [Date, Date] 形式的二元数组(源码中类型为 (Date | string)[],默认 ['', ''])。它支持与单日期选择器一致的 showTime、format、type、separator 等配置:

<template>
  <div class="mb10">basic range picker</div>
  <d-range-date-picker-pro v-model="rangeDatePickerProValue" class="mb20" />
  <div class="mb10">time range picker</div>
  <d-range-date-picker-pro v-model="rangeDatePickerProValue1" class="mb20" :showTime="true" format="YYYY/MM/DD HH:mm:ss" />
  <div class="mb10">year range picker</div>
  <d-range-date-picker-pro v-model="rangeDatePickerProValue2" class="mb20 wh250" type="year" />
  <div class="mb10">month range picker</div>
  <d-range-date-picker-pro v-model="rangeDatePickerProValue3" class="mb20 wh250" type="month" />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const rangeDatePickerProValue = ref<string[]>(['', '']);
    const rangeDatePickerProValue1 = ref<string[]>(['', '']);
    const rangeDatePickerProValue2 = ref<string[]>(['', '']);
    const rangeDatePickerProValue3 = ref<string[]>(['', '']);

    return {
      rangeDatePickerProValue,
      rangeDatePickerProValue1,
      rangeDatePickerProValue2,
      rangeDatePickerProValue3,
    };
  },
});
</script>

focusType:开始/结束输入框的焦点切换

范围组件的核心交互由 focusType(取值 start / end)驱动,实现在 use-range-date-picker-pro.ts:

  • 点击开始输入框 → onFocus('start');点击结束输入框 → onFocus('end');面板未打开时点击任意输入框统一重置为 start。
  • 选中开始日期后,日历选中逻辑会自动调用 changeRangeFocusType 把焦点切到 end,让用户继续选择结束日期(见 use-date-picker.ts 的 handlerConfirm 与 use-calendar-selected.ts 的 emitSelectedDate)。
  • 范围选择默认时间行为:开始日期补 00:00:00,结束日期补 23:59:59(use-date-picker.ts)。
  • 未开启 showTime 时,开始、结束两个日期都选中后自动关闭面板。

separator 用于定义开始与结束输入框之间的分割符,默认 '-'(在 range-date-picker-types.ts 中声明,渲染于 range-date-picker-pro.tsx)。

自定义日期范围面板区域

范围选择器同样支持 rightArea 与 footer 插槽。右侧区域适合放置"一个月前""当前周"等范围快捷选项,底部可放置"清除开始时间""清除结束时间"等操作按钮:

<template>
  <div class="mb10">right area</div>
  <d-range-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250" :showTime="true">
    <template #rightArea>
      <slot name="rightArea">
        <ul class="date-picker-right-panel">
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  setDate(-30);
                }
              "
            >
              一个月前
            </d-button>
          </li>
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  setDate(-14);
                }
              "
            >
              一周前
            </d-button>
          </li>
          <li>
            <d-button
              variant="text"
              color="primary"
              @click="
                () => {
                  selectThisWeek();
                }
              "
            >
              当前周
            </d-button>
          </li>
        </ul>
      </slot>
    </template>
  </d-range-date-picker-pro>
  <div class="mb10">footer</div>
  <d-range-date-picker-pro ref="footerCustom" v-model="datePickerProValue2" class="mb20 wh250" :showTime="true">
    <template #footer>
      <slot name="footer">
        <div class="date-picker-footer">
          <d-button variant="solid" color="secondary" @click="clearStartDate"> 清除开始时间 </d-button>
          <d-button variant="solid" color="secondary" @click="clearEndDate"> 清除结束时间 </d-button>
        </div>
      </slot>
    </template>
  </d-range-date-picker-pro>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const datePickerProValue1 = ref<string | Date[]>(['', '']);
    const datePickerProValue2 = ref<string | Date[]>(['', '']);
    const setDate = (days: number) => {
      datePickerProValue1.value = [new Date(new Date().getTime() + days * 24 * 3600 * 1000), new Date()];
    };
    const selectThisWeek = () => {
      const tody = new Date();
      const start = new Date(new Date().setDate(tody.getDate() - tody.getDay()));
      const end = new Date(new Date().setDate(start.getDate() + 6));
      datePickerProValue1.value = [start, end];
    };

    const footerCustom = ref();

    const clearStartDate = () => {
      const [start, end] = datePickerProValue2.value;
      datePickerProValue2.value = ['', end];
      footerCustom?.value.focusChange('start');
    };
    const clearEndDate = () => {
      const [start, end] = datePickerProValue2.value;
      datePickerProValue2.value = [start, ''];
      footerCustom?.value.focusChange('end');
    };

    return {
      datePickerProValue1,
      datePickerProValue2,
      setDate,
      selectThisWeek,
      footerCustom,
      clearStartDate,
      clearEndDate,
    };
  },
});
</script>

通过实例方法 focusChange 控制焦点

上面 Demo 中通过 ref="footerCustom" 拿到范围组件实例并调用 focusChange('start' | 'end') 手动切换输入框焦点。该能力来自范围组件通过 ctx.expose 暴露的实例方法:

ctx.expose({
  focusChange: onChangeRangeFocusType,
});

见 use-range-date-picker-pro.ts,onChangeRangeFocusType 内部会更新 focusType 并自动 focus() 对应输入框,非常适合在自定义 footer 中配合"清除开始/结束时间"这类局部清空操作使用。

禁用选择器

通过 :disabled="true" 禁用选择器,禁用后输入框不可交互、无法弹出日历面板:

<template>
  <d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250 mr30" :disabled="true" />
  <d-range-date-picker-pro v-model="datePickerProValue2" class="mb20 wh250" :disabled="true" />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const datePickerProValue1 = ref<string>('');
    const datePickerProValue2 = ref<string[]>(['', '']);

    return {
      datePickerProValue1,
      datePickerProValue2,
    };
  },
});
</script>

禁用状态同样支持表单联动:usePickerPro 中 pickerDisabled = computed(() => formContext?.disabled || props.disabled),即 Form 设置 disabled 时组件自动禁用。范围组件禁用后会为容器附加 disabled 修饰类(range-date-picker-pro.tsx)。对应测试见 date-picker-pro.spec.tsx,禁用后 focus 不再弹出面板。

设置日历面板可选时间范围:calendarRange 与 limitDateRange

  • calendarRange:设置日历面板显示的时间范围,类型 [number, number](起始年、结束年),默认 [1970, 2099]。它决定左侧年份虚拟列表与中间月份日历的渲染跨度。
  • limitDateRange:设置日历面板可选择的时间范围,类型 [Date, Date],默认取 [new Date(calendarRange[0]), new Date(calendarRange[1])],范围外的日期置灰不可点选。
<template>
  <d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250 mr30" :calendarRange="[2022, 2025]" :limitDateRange="limitDateRange" />
  <d-range-date-picker-pro
    v-model="datePickerProValue2"
    class="mb20 wh250"
    :calendarRange="[2022, 2025]"
    :limitDateRange="limitDateRange"
  />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const datePickerProValue1 = ref<string>('');
    const datePickerProValue2 = ref<string[]>(['', '']);
    const limitDateRange = ref<Date[]>([new Date(2022, 1, 5), new Date(2023, 1, 5)]);

    return {
      datePickerProValue1,
      datePickerProValue2,
      limitDateRange,
    };
  },
});
</script>

两个范围的底层换算

use-calendar-selected.ts 中,limitDateRange 会被换算为 minDate / maxDate:

const minDate = computed(() => {
  if (props.limitDateRange && props.limitDateRange[0]) {
    return props.limitDateRange[0];
  } else {
    return new Date(calendarRange.value[0], 0, 1);
  }
});
const maxDate = computed(() => {
  if (props.limitDateRange && props.limitDateRange[1]) {
    return props.limitDateRange[1];
  } else {
    return new Date(calendarRange.value[1], 11, 31);
  }
});

日期的禁用判断 isDisabled 在 use-calendar-panel.ts 中实现,只有落在 <a href="https://link.gitcode.com/i/c76aa948d89814926dccc5d6ff8ca066" target="_blank">minDate, maxDate] 闭区间内的日期可点选;年/月选择器同样基于该范围计算禁用状态(见 [year-picker.spec.tsx)。日历数据的初始化(按年生成 12 个月、每个月的 6 行周数据)也在 use-calendar-panel.ts 完成,并对相同 calendarRange 的结果做了 Map 缓存,避免重复计算。

DatePickerPro API 参考

DatePickerPro 参数

参数名 类型 默认 说明 跳转 Demo
v-model Date '' 必选,选中项绑定的值 基本用法
format Format 'YYYY/MM/DD' | 'YYYY/MM/DD HH:mm:ss' 可选,绑定值的日期格式,根据是否 showTime 区别不同默认值 日期格式
placeholder string '请选择日期' 可选,输入框的 placeholder 基本用法
showTime boolean false 可选,是否显示时分秒 显示时间
size string 'md' 可选,输入框的尺寸 基本用法
disabled boolean false 可选,是否禁用选择器 禁用选择器
calendarRange [number,number] [1970, 2099] 可选,设置日历面板显示时间范围 设置日历面板可选时间范围
limitDateRange [Date,Date] [new Date(calendarRange[0]), new Date(calendarRange[1])] 可选,设置日历面板可选时间范围 设置日历面板可选时间范围
type string 'date' 可选,设置日期选择器类型(date/year/month) 年月选择器
show-glow-style boolean true 可选,是否显示悬浮发光效果
position Placement[] ['bottom-start','top-start'] 可选,自定义下拉面板位置

DatePickerPro 事件

事件名 类型 说明 跳转 Demo
toggleChange (bool: boolean) => void 可选,选择器打开关闭 toggle 事件
confirmEvent (date: Date) => void 可选,用户确定选定的值时触发
focus (e: MouseEvent) => void 可选,输入框获取焦点时触发
blur () => void 可选,输入框失去焦点时触发

DatePickerPro 插槽

名称 说明 跳转 Demo
rightArea 自定义 DatePickerPro 日历面板右侧内容, 如:日期快捷选项 自定义日历面板区域
footer 自定义 DatePickerPro 日历面板下侧内容 自定义日历面板区域

DatePickerPro 类型定义

Format

type Format = string;

日期格式 format 支持的标识列表见上文 日期格式:format 的完整标识表。

事件与闭合机制

从源码看,四个事件由 use-picker-pro.ts 统一派发:

  • 输入框聚焦时调用 toggleChange(true) 并 emit focus;
  • 面板关闭(含点击外部关闭)时调用 toggleChange(false) 并 emit blur;
  • 用户确定选中值时 emit confirmEvent(参数为 Date)并关闭面板;
  • 外部点击关闭通过 @vueuse/core 的 onClickOutside 监听 overlay,ignore: [originRef] 保证点击输入框本身不会误关闭。

另外,v-model 变化时会联动触发 formItemContext?.validate('change') 做表单校验;showGlowStyle 控制输入框的悬浮发光效果;position 传入 FlexibleOverlay 控制弹层方位,面板打开/关闭的淡入淡出动画方向(fade-top / fade-bottom)由实际位置计算得出(date-picker-pro.tsx)。

RangeDatePickerPro API 参考

RangeDatePickerPro 参数

参数名 类型 默认 说明 跳转 Demo
v-model [Date, Date] ['',''] 必选,选中项绑定的值 范围选择器
format Format 'YYYY/MM/DD' | 'YYYY/MM/DD HH:mm:ss' 可选,绑定值的日期格式,根据是否 showTime 区别不同默认值 日期格式
placeholder Array ['请选择开始日期', '请选择结束日期'] 可选,输入框的 placeholder 范围选择器
showTime boolean false 可选,是否显示时分秒 范围选择器
separator string '-' 可选,范围选择器的分割符 范围选择器
size string 'md' 可选,输入框的尺寸
disabled boolean false 可选,是否禁用选择器 禁用选择器
calendarRange [number,number] [1970,2099] 可选,设置日历面板显示时间范围 设置日历面板可选时间范围
limitDateRange [Date,Date] [new Date(calendarRange[0]), new Date(calendarRange[1])] 可选,设置日历面板可选时间范围 设置日历面板可选时间范围
type string 'date' 可选,设置日期选择器类型(date/year/month) 范围选择器
show-glow-style boolean true 可选,是否显示悬浮发光效果
position Placement[] ['bottom-start','top-start'] 可选,自定义下拉面板位置

RangeDatePickerPro 事件

事件名 类型 说明 跳转 Demo
toggleChange (bool: boolean) => void 可选,选择器打开关闭 toggle 事件
confirmEvent (date: Date[]) => void 可选,用户确定选定的时间范围时触发
focus (e: MouseEvent) => void 可选,输入框获取焦点时触发
blur () => void 可选,输入框失去焦点时触发

RangeDatePickerPro 插槽

名称 说明 跳转 Demo
rightArea 自定义 RangeDatePickerPro 日历面板右侧内容, 如:日期范围快捷选项 自定义日期范围面板区域
footer 自定义 RangeDatePickerPro 日历面板下侧内容 自定义日期范围面板区域

类型定义

Placement

type Placement =
  | 'top'
  | 'right'
  | 'bottom'
  | 'left'
  | 'top-start'
  | 'top-end'
  | 'right-start'
  | 'right-end'
  | 'bottom-start'
  | 'bottom-end'
  | 'left-start'
  | 'left-end';

补充说明两个源码细节:

  1. position 的实际默认值:类型声明文件 date-picker-pro-types.ts 中 position 的默认值为 ['bottom-start', 'top-start', 'left-start', 'right-start'](比表格示例多了左右两个备选方位),传多个方位时 FlexibleOverlay 会按顺序自适应选择可用位置。
  2. placeholder 的国际化兜底:单日期与范围组件的 placeholder prop 默认值为空,未传时由 createI18nTranslate('DDatePickerPro', app) 从 locale 读取 '请选择日期' / '请选择开始日期' / '请选择结束日期'(中文文案见 locale/lang/zh-cn.ts,英文见 locale/lang/en-us.ts),因此表格中的默认 placeholder 在跟随语言环境自动切换。

底层实现要点总结

最后汇总一下阅读本文所需的源码线索,便于进一步深入:

结合以上内容,你可以快速在项目中使用 DDatePickerPro / DRangeDatePickerPro 完成单日期、时间联动、年月粒度、范围选择、快捷选项定制与禁用/范围限制等场景,并在需要深度定制时直接定位到对应的 composable 与面板组件源码。

登录后查看全文
vue-devui