UseElDatePicker - 日期选择器

组件介绍

UseElDatePicker 是基于 Element Plus 的 ElDatePicker 二次封装的日期选择器组件，专注于为日期选择提供开箱即用的智能格式适配、渲染器模式切换能力，同时标准化日期选择配置项管理，完整兼容原生 ElDatePicker 核心属性，可直接替换原生 ElDatePicker 使用，大幅降低不同日期类型格式适配、表格纯文本渲染等场景的重复开发成本。

核心能力

智能日期格式自动适配

内置格式自动计算逻辑（dateFormatComputed），根据选择器类型（type）自动匹配最优显示格式与值格式：日期时间类型自动使用 YYYY-MM-DD HH:mm:ss、月份范围自动使用 YYYY-MM、其他日期类型默认使用 YYYY-MM-DD，无需手动配置 format 和 valueFormat，同时支持自定义格式覆盖，兼顾开箱即用与灵活定制需求。

内置渲染器模式支持

支持通过 useRender 配置一键切换为纯文本渲染模式，开启后直接展示日期值而非选择器输入框，适配表格列展示、详情页只读展示等场景；支持传入对象形式自定义渲染样式与 class，满足不同展示场景的样式定制需求，无需额外编写 v-if 判断逻辑。

全类型日期选择支持

完整支持 Element Plus 所有 12 种日期选择类型：年（year/years）、月（month/months）、日期（date/dates）、日期时间（datetime）、周（week）、日期时间范围（datetimerange）、日期范围（daterange）、月份范围（monthrange）、年份范围（yearrange），内置类型校验，非法类型自动兜底，覆盖所有业务日期选择场景。

弹层层级问题修复

内置弹层 z-index 修复，强制设置日期选择弹层 popper-style="z-index:999999 !important"，解决在 Drawer、Dialog 等高层级容器内使用时日期选择弹层被遮挡的问题，保证弹层在任何布局场景下都能正常显示，无需手动调整全局 z-index。

标准化占位符配置

统一各类选择场景的占位符默认值：单选模式默认占位符为"请选择"，范围选择模式默认开始占位符为"开始日期"、结束占位符为"结束日期"，范围分隔符默认为"至"，符合中文用户使用习惯，同时支持自定义覆盖，保证项目内日期选择器占位符规范统一。

原生组件完全兼容

基于 ElDatePicker 封装，完整保留 v-model 双向绑定、类型切换、禁用日期等所有原生能力，未在组件中声明的原生属性可通过透传方式直接使用，可直接替换原生 ElDatePicker 使用，无迁移成本，同时补充原生组件缺失的智能格式适配、渲染器模式等能力。

双向绑定标准化实现

通过 computed 标准化实现 v-model 双向绑定，统一处理 String/Number/Array 三种值类型，适配单选、多选、范围选择等不同场景的值类型需求，emit 事件类型严格定义，保证 TypeScript 类型安全，避免值类型不匹配导致的提交异常。

范围选择场景优化

针对日期范围选择场景做专门优化：内置开始/结束占位符、范围分隔符的中文默认配置，自动适配范围类型的日期格式（如 datetimerange 自动带时分秒、monthrange 自动到月份），范围选择值自动以数组格式输出，无需额外处理格式转换，开箱即用满足业务范围查询需求。

使用

UseElDatePicker

Props

import type { PropType } from 'vue'
import type { RenderConfig } from '@/types'

/**
 * 组件props
 */
export default {
  /**
   * 双向绑定数据源
   */
  modelValue: {
    type: [String, Number, Array],
    default: ''
  },
  /**
   * 是否使用渲染器 默认否
   */
  useRender: {
    type: [Boolean, Object] as PropType<boolean | RenderConfig>,
    default: false
  },
  /**
   * 显示类型
   */
  type: {
    type: String,
    default: 'date',
    validator: (val: string) =>
      [
        'year',
        'years',
        'month',
        'months',
        'date',
        'dates',
        'datetime',
        'week',
        'datetimerange',
        'daterange',
        'monthrange',
        'yearrange'
      ].includes(val)
  },
  /**
   * 范围选择时开始日期的占位内容
   */
  startPlaceholder: {
    type: String,
    default: '开始日期'
  },
  /**
   * 范围选择时结束日期的占位内容
   */
  endPlaceholder: {
    type: String,
    default: '结束日期'
  },
  /**
   * 选择范围时的分隔符
   */
  rangeSeparator: {
    type: String,
    default: '至'
  },
  /**
   *  显示在输入框中的格式
   */
  format: {
    type: String,
    default: undefined // 默认undefined 通过dateFormatComputed进行默认赋值
  },
  /**
   * value-format
   */
  valueFormat: {
    type: String,
    default: undefined // 默认undefined 通过dateFormatComputed进行默认赋值
  },
  /**
   * placeholder 默认请选择
   */
  placeholder: {
    type: String,
    default: '请选择'
  }
}

Types

import type { ExtractPropTypes } from 'vue'
import componentProps from './props'

/**
 * props类型
 */
export type Props = ExtractPropTypes<typeof componentProps>

/**
 * emits类型
 */
export type Emits = {
  /** 更新value值 */
  (e: 'update:modelValue', value: string | number | any[]): void
}

UseElDatePicker - 日期选择器 ​

组件介绍 ​

核心能力 ​

使用 ​

Props ​

Types ​

UseElDatePicker - 日期选择器

组件介绍

核心能力

使用

Props

Types