WeekRangePicker 周范围选择器

简介

按周选择连续区间。周固定为 ISO 周（周一 00:00:00 ~ 周日 23:59:59.999），不随界面语言变化，v-model 即这两端的时间戳。

键盘：← / → 移动一周，↑ / ↓ 跨一行，PageUp / PageDown 换季度，Enter 选中，Esc 关闭。

代码演示

基础使用

输入框展示格式由 format 决定，默认 2026 W05。

<template>
  <co-week-range-picker v-model="value" start-placeholder="开始" end-placeholder="结束" />

  <div class="mt-2">
    <el-button @click="onSetValue">选中 2026 第 5 ~ 11 周</el-button>
    <el-button @click="value = null">清空</el-button>
  </div>

  <div class="mt-2">{{ display }}</div>
</template>

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

const value = ref<Date[] | null>(null);

const onSetValue = () => {
  value.value = [new Date(2026, 0, 28), new Date(2026, 2, 8)];
};

const display = computed(
  () => value.value?.map((item) => dayjs(item).format('YYYY-MM-DD HH:mm:ss')) ?? '未选择',
);
</script>

禁用部分周

disabled-week 收到该周的 { year, week, start, end }，返回 true 即不可选 —— 点击无效，键盘移动时也会跳过。

<template>
  <co-week-range-picker v-model="value" :disabled-week="disabledWeek" />

  <div class="mt-2">{{ display }}</div>
</template>

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

const value = ref<Date[] | null>(null);

/** 今天之后的周不可选 */
const disabledWeek = ({ start }: { start: Date }) => dayjs(start).isAfter(dayjs(), 'week');

const display = computed(() => {
  if (!value.value) return '未选择';

  return value.value.map((item) => dayjs(item).format('YYYY-MM-DD')).join(' ~ ');
});
</script>

自定义快捷项

不传 shortcuts 时内置「本周 / 上周 / 近 4 周 / 本月 / 本年」；传入自己的数组会整体替换，传 [] 则收起。

<template>
  <co-week-range-picker v-model="value" :shortcuts="shortcuts" />

  <div class="mt-2">{{ display }}</div>
</template>

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

const value = ref<Date[] | null>(null);

/** 传 `[]` 可以收起内置的「本周 / 上周 / 近 4 周 / 本月 / 本年」 */
const shortcuts = [
  { text: 'Q1', value: () => [new Date(2026, 0, 1), new Date(2026, 2, 31)] as [Date, Date] },
  { text: 'Q2', value: () => [new Date(2026, 3, 1), new Date(2026, 5, 30)] as [Date, Date] },
  { text: 'Q3', value: () => [new Date(2026, 6, 1), new Date(2026, 8, 30)] as [Date, Date] },
  { text: 'Q4', value: () => [new Date(2026, 9, 1), new Date(2026, 11, 31)] as [Date, Date] },
];

const display = computed(() => {
  if (!value.value) return '未选择';

  return value.value.map((item) => dayjs(item).format('YYYY-MM-DD')).join(' ~ ');
});
</script>

跨年选择

值跨年时，面板打开在起始周所在季度。

<template>
  <co-week-range-picker v-model="value" />

  <div class="mt-2">{{ display }}</div>
</template>

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

/** 2025 第 52 周 ~ 2026 第 2 周：值跨年，打开面板锚到 2025 Q4，点 › 可看到另一半 */
const value = ref<Date[] | null>([new Date(2025, 11, 22), new Date(2026, 0, 11)]);

const display = computed(() =>
  value.value?.map((item) => dayjs(item).format('YYYY-MM-DD')).join(' ~ '),
);
</script>

API

WeekRangePickerProps

属性	描述	类型	默认值
model-value	周区间，两端分别对齐到周一 / 周日	Date[] | null	-
format	输入框展示格式	string	GGGG [W]WW
disabled-week	禁用某些周	(week: WeekEntry) => boolean	-
shortcuts	快捷项，[] 收起内置项	WeekShortcut[]	内置 5 项
start-placeholder	开始输入框的 placeholder	string	-
end-placeholder	结束输入框的 placeholder	string	-
readonly	是否只读	boolean	false
disabled	是否禁用	boolean	false
clearable	是否可清空	boolean	true
validate-event	是否触发表单验证	boolean	true

其余属性（size、popper-class 等）透传 el-date-picker 的公共属性。输入框不支持手动输入。

WeekRangePickerSlots

插槽	描述	属性
range-separator	两个输入框之间的分隔	-

WeekRangePickerEmits

事件	描述	类型
update:modelValue	绑定值被改变时触发	(value: Date[] | null) => void
change	绑定值被改变时触发	(value: Date[] | null) => void
clear	点击清空按钮时触发	() => void
focus / blur	输入框聚焦 / 失焦	(event: FocusEvent) => void
visible-change	面板展开 / 收起	(visible: boolean) => void

WeekRangePickerExpose

方法	描述
focus	聚焦输入框
blur	失焦
handleOpen	展开面板
handleClose	收起面板

类型

interface WeekEntry {
  /** ISO 周年，可能不等于 start 的日历年 */
  year: number;
  /** ISO 周号 1 ~ 53 */
  week: number;
  /** 周一 00:00:00.000 */
  start: Date;
  /** 周日 23:59:59.999 */
  end: Date;
}

interface WeekShortcut {
  text: string;
  value: () => [Date, Date];
}