Date日期

用于选择日期、日期时间或时间范围。先决定后端需要的值格式，再配置 type、format 和 valueFormat；输入框显示文本与实际提交值可以不同。

场景	type	常用 valueFormat	绑定值
只选择一天	date	YYYY-MM-DD	日期字符串
精确到秒	datetime	YYYY-MM-DD HH:mm:ss	日期时间字符串
起止日期	daterange	YYYY-MM-DD	两个日期字符串组成的数组
起止日期与时间	datetimerange	YYYY-MM-DD HH:mm:ss	两个日期时间字符串组成的数组

未设置 valueFormat 时，日期选择器使用 Date 值。示例中的结果区展示实际绑定值，便于确认接口收到的数据。

复制示例时使用的结果展示组件，见 示例辅助文件。

基础用法

效果预览可直接操作下方示例

基本单位由 type 指定。尝试选择日期、点击快捷选项，再打开“预约日期”查看今天之前的禁用状态；三个字段使用独立的 prop，互不覆盖。

正在加载示例…

<template>
  <avue-form v-model="form"
             :option="option"></avue-form>
  <form-demo-result :value="result" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';

const form = ref({});
const result = computed(() => ({ datetime: form.value.datetime || '', shortcut: form.value.shortcut || '', bookingDate: form.value.bookingDate || '' }));

const option = ref({
  menuBtn: false,
  labelWidth: 100,
  column: [
    {
      label: "日期",
      prop: "datetime",
      type: "datetime",
      span: 24,
      valueFormat: 'YYYY-MM-DD HH:mm:ss',
    },
    {
      label: "快捷方式",
      prop: "shortcut",
      type: "date",
      span: 24,
      valueFormat: 'YYYY-MM-DD',
      shortcuts: [
        {
          text: '今天',
          value: () => new Date(),
        },
        {
          text: '昨天',
          value: () => {
            const date = new Date();
            date.setTime(date.getTime() - 3600 * 1000 * 24);
            return date;
          },
        },
        {
          text: '一周前',
          value: () => {
            const date = new Date();
            date.setTime(date.getTime() - 3600 * 1000 * 24 * 7);
            return date;
          },
        },
      ],
    },
    {
      label: "预约日期",
      prop: "bookingDate",
      type: "date",
      span: 24,
      valueFormat: 'YYYY-MM-DD',
      disabledDate (time) {
        const today = new Date();
        today.setHours(0, 0, 0, 0);
        return time.getTime() < today.getTime();
      },
    },
  ],
});
</script>

日期格式化

提示

请注意大小写

格式	含义	备注	举例
YYYY	年		2017
M	月	不补0	1
MM	月		01
W	周	仅周选择器的format可用；不补0	1
WW	周	仅周选择器的format可用	01
D	日	不补0	2
DD	日		02
H	小时	24小时制；不补0	3
HH	小时	24小时制	03
h	小时	12小时制，须和A或a使用；不补0	3
hh	小时	12小时制，须和A或a使用	03
m	分钟	不补0	4
mm	分钟		04
s	秒	不补0	5
ss	秒		05
A	AM/PM	仅format可用，大写	AM
a	am/pm	仅format可用，小写	am
X	JS时间戳	仅value-format可用；组件绑定值为number类型	1483326245000

格式化

效果预览可直接操作下方示例

使用format指定输入框的格式；使用valueFormat指定绑定值的格式。

正在加载示例…

<template>
  <avue-form v-model="form"
             :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const form = ref({});

const option = ref({
  column: [
    {
      label: "日期",
      prop: "datetime",
      type: "datetime",
      format: 'YYYY年MM月DD日 HH时mm分ss秒',
      valueFormat: 'YYYY-MM-DD HH:mm:ss'
    },
    {
      label: "时间戳",
      prop: "datetime",
      type: "datetime",
      format: "YYYY-MM-DD HH:mm:ss",
      valueFormat: "x",
    }
  ]
});
</script>

其他日期单位

效果预览可直接操作下方示例

按年、月、周等单位选择时，type 决定面板，valueFormat 决定实际值；根据接口约定选择合适的粒度。

正在加载示例…

<template>
  <avue-form v-model="form"
             :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const form = ref({});

const option = ref({
  labelWidth: 110,
  column: [
    {
      label: "时间",
      prop: "time",
      type: "time",
      format: 'HH:mm:ss',
      valueFormat: 'HH:mm:ss',
    },
    {
      label: "周",
      prop: "week",
      type: "week",
      format: "YYYY 第 ww 周"
    },
    {
      label: "月",
      prop: "month",
      type: "month",
    },
    {
      label: "月范围",
      prop: "monthrange",
      type: "monthrange",
      format: 'YYYY-MM',
      valueFormat: 'YYYY-MM'
    },
    {
      label: "年",
      prop: "year",
      type: "year",
    },
    {
      label: "年范围",
      prop: "yearrange",
      type: "yearrange",
    },
    {
      label: "多个年份",
      prop: "years",
      type: "years",
      format: "YYYY",
      valueFormat: "YYYY",
    },
    {
      label: "多个月份",
      prop: "months",
      type: "months",
      format: "YYYY-MM",
      valueFormat: "YYYY-MM",
    },
    {
      label: "多个日期",
      prop: "dates",
      type: "dates",
      format: "YYYY-MM-DD",
      valueFormat: "YYYY-MM-DD",
    },
  ],
});
</script>

日期范围

效果预览可直接操作下方示例

分别选择起止日期，观察结果区的两个元素。清空选择后，提交前应判断值是否为空，避免直接读取不存在的起止项。

正在加载示例…

<template>
  <avue-form v-model="form"
             :option="option"></avue-form>
  <form-demo-result :value="result" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';

const form = ref({});
const result = computed(() => ({ datetimerange: form.value.datetimerange || [], daterange: form.value.daterange || [] }));

const option = ref({
  labelWidth: 110,
  menuBtn: false,
  column: [
    {
      label: "时间日期范围",
      type: 'datetimerange',
      prop: 'datetimerange',
      span: 24,
      format: 'YYYY-MM-DD HH:mm:ss',
      valueFormat: 'YYYY-MM-DD HH:mm:ss',
      startPlaceholder: '时间日期开始范围自定义',
      endPlaceholder: '时间日期结束范围自定义',
    },
    {
      label: "日期范围",
      prop: "daterange",
      type: "daterange",
      span: 24,
      format: 'YYYY-MM-DD',
      valueFormat: 'YYYY-MM-DD',
      startPlaceholder: '日期开始范围自定义',
      endPlaceholder: '日期结束范围自定义',
    }
  ]
});
</script>

下拉框样式

.popperClass .available{
  background-color: rgba(0,0,0,.2);
}

效果预览可直接操作下方示例

popperClass属性配置样式的class名字

正在加载示例…

<template>
  <avue-form v-model="form"
             :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const form = ref({});

const option = ref({
  column: [
    {
      label: "日期",
      prop: "datetime",
      popperClass: 'popperClass',
      type: "datetime",
    }
  ]
});
</script>

默认的起始与结束时刻

defaultTime 控制从面板选中日期时补上的时分秒，不会预先选中日期，也不会改写已有的绑定值。业务中需要初始选中范围时，应给 v-model 对应字段赋值。

效果预览可直接操作下方示例

3.9.5 起，defaultTime 支持标准 HH:mm:ss 字符串及字符串数组，也兼容 Date 和 Date[]。分别在下面两个范围框中选择日期并确认：第一个结果补齐 00:00:00 与 23:59:59，第二个结果补齐 09:00:00 与 18:00:00。点击“清空后重选”可重复验证。

正在加载示例…

<template>
  <el-button @click="clearRanges">清空后重选</el-button>
  <avue-form v-model="form" :option="option" />
  <form-demo-result :value="result" hint="请选择起止日期并确认，结果中会显示各自补齐的时分秒。" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';

const form = ref({ wholeDay: [], officeHours: [], appointment: '' });
const result = computed(() => ({
  wholeDay: form.value.wholeDay,
  officeHours: form.value.officeHours,
  appointment: form.value.appointment,
}));
const option = {
  labelWidth: 110,
  menuBtn: false,
  column: [
    {
      label: '整天范围', prop: 'wholeDay', type: 'datetimerange', span: 24,
      format: 'YYYY-MM-DD HH:mm:ss', valueFormat: 'YYYY-MM-DD HH:mm:ss',
      startPlaceholder: '开始日期', endPlaceholder: '结束日期',
      defaultTime: ['00:00:00', '23:59:59'],
    },
    {
      label: '办公时段', prop: 'officeHours', type: 'datetimerange', span: 24,
      format: 'YYYY-MM-DD HH:mm:ss', valueFormat: 'YYYY-MM-DD HH:mm:ss',
      startPlaceholder: '开始日期', endPlaceholder: '结束日期',
      defaultTime: [new Date(2000, 0, 1, 9, 0, 0), new Date(2000, 0, 1, 18, 0, 0)],
    },
    {
      label: '预约时间', prop: 'appointment', type: 'datetime', span: 24,
      format: 'YYYY-MM-DD HH:mm:ss', valueFormat: 'YYYY-MM-DD HH:mm:ss',
      defaultTime: '09:00:00',
    },
  ],
};
function clearRanges() {
  form.value.wholeDay = [];
  form.value.officeHours = [];
  form.value.appointment = '';
}
</script>

配置	示例	用途
字符串	defaultTime: '09:00:00'	为单个日期时间设置默认时刻
两项字符串数组	defaultTime: ['00:00:00', '23:59:59']	分别控制范围的开始、结束时刻
Date	defaultTime: new Date(2000, 0, 1, 9, 0, 0)	沿用原生日期时间对象配置
两项 Date[]	defaultTime: [new Date(2000, 0, 1, 9), new Date(2000, 0, 1, 18)]	分别控制范围两端的时刻

字符串必须使用补零的 24 小时格式，例如 09:00:00，不要使用 9:0 或 24:00:00。Date 配置只取本地时分秒，不使用其中的年月日。若后端统一存储 UTC 时间，需要在提交时按业务约定转换时区。

自定义模板

效果预览可直接操作下方示例

配置字段 prop 名称加 Type 的插槽即可自定义日期单元格内容；保留日期数值有助于用户识别与选择。

正在加载示例…

<template>
  <avue-form :option="option"
             v-model="form">
    <template #datetime-type="{ item }">
      <span>{{ item.text }}日</span>
    </template>
  </avue-form>
</template>

<script setup>
import { ref } from 'vue';

const form = ref({});

const option = ref({
  column: [
    {
      label: '日期',
      prop: 'datetime',
      type: 'datetime'
    }
  ]
});
</script>