BizWorkdayCalendar 法定工作日历

法定工作日历：内置国务院办公厅 2024~2026 年放假安排数据包（法定节假日、调休补班、连休日一应俱全），月历三态标记——法定节假日显示节日名、调休连休日出「休」角标、调休补班的周末出「班」角标；overrides 支持自定义覆盖（公司司庆、区域调休等）。与组件同模块导出工作日计算纯函数（isWorkday / countWorkdays / addWorkdays / getWorkdayDisabledDate），日历展示与业务核算共用同一套口径，避免「页面显示放假、后台算成工作日」的口径漂移。

适用于：请假/外出申请天数核算、交付期与 SLA 到期日推算、考勤日历、合同生效日只能选工作日、全年放假安排公告页。

与 BizCalendarBoard 的分工

BizCalendarBoard 是空白日期排版板（按天组织内容的 UI 容器，无节假日数据、无日期计算）；本组件价值在法定数据 + 工作日口径——需要渲染日程内容用 Board，需要节假日判定/推算用本组件（两者可经 #cell 插槽组合）。

基础用法

2026 年 10 月

一二三四五六日

28

29

30

1国庆节

2国庆节

3国庆节

4休

5休

6休

7休

8

9

10班

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

1

2

3

4

5

6

7

8

节假日班调休上班法定节假日（三薪）当月工作日 18 天

选中信息

选中日期：未选择

内置 2024~2026 年国务院放假安排：法定节假日显示节日名，调休连休日出「休」角标，调休补班的周末出「班」角标。

月历展示 + 点击选择日期；右侧面板展示 cell-click 回传的完整单元格状态（工作日/法定节假日/节日名）。

<script setup lang="ts">
/** 场景：基础月历——法定节假日/调休三态标记 + 点击选日期 + 图例统计 */
import { ref } from 'vue'
import { BizWorkdayCalendar } from 'vue3-ep-biz-lib'
import type { WorkdayCellMeta } from 'vue3-ep-biz-lib'

const selected = ref('')
const clicked = ref<WorkdayCellMeta | null>(null)
const month = ref('2026-10')

const onCellClick = (meta: WorkdayCellMeta): void => {
  clicked.value = meta
}
</script>

<template>
  <div style="display: flex; gap: 20px; align-items: flex-start; flex-wrap: wrap">
    <BizWorkdayCalendar v-model="selected" v-model:month="month" @cell-click="onCellClick" />
    <el-card shadow="never" style="width: 280px">
      <template #header>选中信息</template>
      <p style="margin: 0 0 8px">选中日期：<strong>{{ selected || '未选择' }}</strong></p>
      <template v-if="clicked">
        <p style="margin: 0 0 8px">
          属性：
          <el-tag size="small" :type="clicked.isWorkday ? 'success' : 'danger'">
            {{ clicked.isWorkday ? '工作日' : '休息日' }}
          </el-tag>
          <el-tag v-if="clicked.statutory" size="small" type="warning" style="margin-left: 4px">法定节假日（三薪）</el-tag>
        </p>
        <p v-if="clicked.holidayName" style="margin: 0">节日：{{ clicked.holidayName }}</p>
      </template>
      <p style="margin: 8px 0 0; font-size: 13px; color: var(--el-text-color-secondary)">
        内置 2024~2026 年国务院放假安排：法定节假日显示节日名，调休连休日出「休」角标，调休补班的周末出「班」角标。
      </p>
    </el-card>
  </div>
</template>

显示代码

自定义覆盖

2026 年 10 月

一二三四五六日

28

29

30

1国庆节

2国庆节

3国庆节

4休

5休

6休

7休

8

9司庆

10班

11

12

13

14

15

16

17班

18

19

20

21

22

23

24班

25

26

27

28

29

30

31

1

2

3

4

5

6

7

8

节假日班调休上班法定节假日（三薪）当月工作日 19 天

10-09（周五）设为司庆假日：工作日变休息日，显示自定义名「司庆」

10-17 / 10-24（周六）设为补班：休息日变工作日，出「班」角标

图例中的「当月工作日」统计同步按覆盖后口径计算。

overrides 优先级最高：追加公司假日（工作日变休息日并显示自定义名）、把指定周六设为补班；图例的当月工作日统计同步按覆盖后口径计算。

<script setup lang="ts">
/** 场景：自定义覆盖——追加公司假日（司庆/年会）、把指定周六设为补班 */
import { ref } from 'vue'
import { BizWorkdayCalendar } from 'vue3-ep-biz-lib'
import type { WorkdayOverride } from 'vue3-ep-biz-lib'

const month = ref('2026-10')

/** overrides 优先级最高：司庆当天休假（盖过工作日），10 月两个周六补班 */
const overrides: Record<string, WorkdayOverride> = {
  '2026-10-09': { type: 'holiday', name: '司庆' },
  '2026-10-17': { type: 'workday' },
  '2026-10-24': { type: 'workday' },
}
</script>

<template>
  <div style="display: flex; gap: 20px; align-items: flex-start; flex-wrap: wrap">
    <BizWorkdayCalendar v-model:month="month" :overrides="overrides" />
    <el-alert type="info" :closable="false" style="width: 320px">
      <p style="margin: 0 0 6px"><strong>10-09</strong>（周五）设为司庆假日：工作日变休息日，显示自定义名「司庆」</p>
      <p style="margin: 0 0 6px"><strong>10-17 / 10-24</strong>（周六）设为补班：休息日变工作日，出「班」角标</p>
      <p style="margin: 0">图例中的「当月工作日」统计同步按覆盖后口径计算。</p>
    </el-alert>
  </div>
</template>

显示代码

区间工作日统计

至

自然日

26

天

工作日

14

天

休息日

12

天

常用于工期估算 / 考勤核算：与组件同源的 countWorkdays(start, end) 纯函数直接调用，节假日与调休补班自动纳入口径。

countWorkdays(start, end) 含首尾自动排除周末与节假日——工期估算、考勤核算直接调用纯函数。

<script setup lang="ts">
/** 场景：区间工作日统计——countWorkdays 含首尾，自动排除周末与节假日 */
import { computed, ref } from 'vue'
import { countWorkdays, toDateKey } from 'vue3-ep-biz-lib'

const today = toDateKey(new Date())
const start = ref(today.slice(0, 8) + '01')
const end = ref(today)

const naturalDays = computed(() => {
  if (start.value === '' || end.value === '') return 0
  const a = new Date(start.value)
  const b = new Date(end.value)
  const [from, to] = a <= b ? [a, b] : [b, a]
  return Math.round((to.getTime() - from.getTime()) / 86400000) + 1
})
const workdays = computed(() => (start.value === '' || end.value === '' ? 0 : countWorkdays(start.value, end.value)))
</script>

<template>
  <el-space direction="vertical" size="large">
    <el-space>
      <el-date-picker v-model="start" type="date" value-format="YYYY-MM-DD" placeholder="开始日期" />
      <span>至</span>
      <el-date-picker v-model="end" type="date" value-format="YYYY-MM-DD" placeholder="结束日期" />
    </el-space>
    <el-space size="large">
      <el-statistic title="自然日" :value="naturalDays" suffix="天" />
      <el-statistic title="工作日" :value="workdays" suffix="天" />
      <el-statistic title="休息日" :value="naturalDays - workdays" suffix="天" />
    </el-space>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      常用于工期估算 / 考勤核算：与组件同源的 <code>countWorkdays(start, end)</code> 纯函数直接调用，节假日与调休补班自动纳入口径。
    </p>
  </el-space>
</template>

显示代码

交付期推算

工单受理日：

SLA：

个工作日

承诺交付日

2026-11-09（周一）

addWorkdays(date, n) 自动跳过周末与法定节假日（调休补班照常计入），n 也支持负数（回溯起始日）。

addWorkdays(date, n) 跳过周末与法定节假日推算承诺交付日（SLA 场景），n 支持负数回溯。

<script setup lang="ts">
/** 场景：交付期推算——addWorkdays 从起始日加 N 个工作日得到期日（跳过周末/节假日） */
import { computed, ref } from 'vue'
import { addWorkdays, toDateKey } from 'vue3-ep-biz-lib'

const base = ref(toDateKey(new Date()))
const days = ref(10)

const WEEKDAYS = ['日', '一', '二', '三', '四', '五', '六']

const due = computed(() => {
  if (base.value === '') return null
  return addWorkdays(base.value, days.value)
})
const dueText = computed(() => (due.value === null ? '-' : `${toDateKey(due.value)}（周${WEEKDAYS[due.value.getDay()]}）`))
</script>

<template>
  <el-space direction="vertical" size="large">
    <el-space>
      <span>工单受理日：</span>
      <el-date-picker v-model="base" type="date" value-format="YYYY-MM-DD" />
      <span style="margin-left: 12px">SLA：</span>
      <el-input-number v-model="days" :min="1" :max="365" />
      <span>个工作日</span>
    </el-space>
    <el-result
      icon="success"
      title="承诺交付日"
      :sub-title="dueText"
      style="padding: 12px 0"
    />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      <code>addWorkdays(date, n)</code> 自动跳过周末与法定节假日（调休补班照常计入），n 也支持负数（回溯起始日）。
    </p>
  </el-space>
</template>

显示代码

工作日禁用源

合同生效日

说明

周六日、法定节假日不可选，调休补班日可选

getWorkdayDisabledDate() 生成 el-date-picker 的 disabled-date 函数：非工作日不可选，调休补班日可选。

<script setup lang="ts">
/** 场景：工作日禁用源——getWorkdayDisabledDate 供 el-date-picker 只允许选工作日 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { getWorkdayDisabledDate } from 'vue3-ep-biz-lib'

const effectiveDate = ref('')
const disabledDate = getWorkdayDisabledDate()

const onSubmit = (): void => {
  if (effectiveDate.value === '') {
    ElMessage.warning('请选择合同生效日')
    return
  }
  ElMessage.success(`合同生效日：${effectiveDate.value}`)
}
</script>

<template>
  <el-form label-width="96px" style="max-width: 420px">
    <el-form-item label="合同生效日" required>
      <el-date-picker
        v-model="effectiveDate"
        type="date"
        value-format="YYYY-MM-DD"
        placeholder="只能选工作日"
        :disabled-date="disabledDate"
        style="width: 100%"
      />
    </el-form-item>
    <el-form-item label="说明">
      <span style="font-size: 13px; color: var(--el-text-color-secondary)">周六日、法定节假日不可选，调休补班日可选</span>
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="onSubmit">提交</el-button>
    </el-form-item>
  </el-form>
</template>

显示代码

请假表单联动

请假类型

事假（按工作日核算）

开始日期

结束日期

请假事由

核算结果

1

个工作日

2026 年 10 月

一二三四五六日

28

29

30

1国庆节

2国庆节

3国庆节

4休

5休

6休

7休

8

9

10班

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

1

2

3

4

5

6

7

8

节假日班调休上班法定节假日（三薪）当月工作日 18 天

请假申请典型形态：起止日期 + 事由，工作日天数实时核算（事假按工作日扣），日历与表单共享选中值。

<script setup lang="ts">
/** 场景：请假表单联动——起止日期自动核算工作日天数（事假按工作日扣，节假日不扣） */
import { computed, reactive, ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizWorkdayCalendar, countWorkdays, toDateKey } from 'vue3-ep-biz-lib'

const form = reactive({
  reason: '',
  start: toDateKey(new Date()),
  end: toDateKey(new Date()),
})

/** 起止倒置时按天数 0 处理并提示校验 */
const days = computed(() => {
  if (form.start === '' || form.end === '' || form.start > form.end) return 0
  return countWorkdays(form.start, form.end)
})

const submitting = ref(false)
const onSubmit = (): void => {
  if (form.reason.trim() === '') {
    ElMessage.warning('请填写请假事由')
    return
  }
  if (days.value <= 0) {
    ElMessage.warning('结束日期不能早于开始日期')
    return
  }
  submitting.value = true
  setTimeout(() => {
    submitting.value = false
    ElMessage.success(`已提交：${form.start} ~ ${form.end}，扣事假 ${days.value} 个工作日`)
  }, 600)
}
</script>

<template>
  <div style="display: flex; gap: 20px; align-items: flex-start; flex-wrap: wrap">
    <el-form label-width="96px" style="width: 360px">
      <el-form-item label="请假类型">
        <el-tag>事假（按工作日核算）</el-tag>
      </el-form-item>
      <el-form-item label="开始日期">
        <el-date-picker v-model="form.start" type="date" value-format="YYYY-MM-DD" style="width: 100%" />
      </el-form-item>
      <el-form-item label="结束日期">
        <el-date-picker v-model="form.end" type="date" value-format="YYYY-MM-DD" style="width: 100%" />
      </el-form-item>
      <el-form-item label="请假事由">
        <el-input v-model="form.reason" type="textarea" :rows="2" placeholder="必填" />
      </el-form-item>
      <el-form-item label="核算结果">
        <el-statistic :value="days" suffix="个工作日" :value-style="{ fontSize: '20px' }" />
      </el-form-item>
      <el-form-item>
        <el-button type="primary" :loading="submitting" @click="onSubmit">提交申请</el-button>
      </el-form-item>
    </el-form>
    <BizWorkdayCalendar v-model="form.start" style="flex-shrink: 0" />
  </div>
</template>

显示代码

全年节假日总览

202420252026

2026 年合计放假 32 天。数据包 FESTIVALS 与展平索引 HOLIDAY_DAYS / WORKDAY_DAYS 均从组件库导出，可自渲染年报/公告页。

FESTIVALS 数据包直出官方口径的放假安排表（放假日数/法定三薪日/调休上班日），适合公告页与年报场景。

<script setup lang="ts">
/** 场景：全年节假日总览——FESTIVALS 数据包直出官方口径的放假安排表 */
import { computed, ref } from 'vue'
import { FESTIVALS } from 'vue3-ep-biz-lib'
import type { FestivalArrange } from 'vue3-ep-biz-lib'

interface OverviewRow {
  name: string
  rangeText: string
  restDays: number
  statutoryText: string
  workdayText: string
}

const year = ref(2026)

const rows = computed<OverviewRow[]>(() => {
  const list = FESTIVALS[year.value] ?? []
  const toRow = (f: FestivalArrange): OverviewRow => {
    // 区间天数（含端点）逐段累加
    let rest = 0
    for (const [s, e] of f.ranges) {
      const from = new Date(s)
      const to = new Date(e)
      rest += Math.round((to.getTime() - from.getTime()) / 86400000) + 1
    }
    const fmt = (list2: string[]): string =>
      list2.map((d) => `${Number(d.slice(8))}日`).join('、')
    return {
      name: f.name,
      rangeText: f.ranges.map(([s, e]) => (s === e ? s.slice(5) : `${s.slice(5)}~${e.slice(5)}`)).join(' / '),
      restDays: rest,
      statutoryText: f.statutory === undefined ? '—' : fmt(f.statutory),
      workdayText: f.workdays === undefined ? '—' : f.workdays.map((d) => d.slice(5)).join('、'),
    }
  }
  return list.map(toRow)
})

const totalRest = computed(() => rows.value.reduce((sum, r) => sum + r.restDays, 0))
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 100%">
    <el-radio-group v-model="year">
      <el-radio-button :value="2024">2024</el-radio-button>
      <el-radio-button :value="2025">2025</el-radio-button>
      <el-radio-button :value="2026">2026</el-radio-button>
    </el-radio-group>
    <el-table :data="rows" border size="small">
      <el-table-column prop="name" label="节日" width="90" />
      <el-table-column prop="rangeText" label="放假安排（月-日）" min-width="150" />
      <el-table-column prop="restDays" label="放假日数" width="80" align="center" />
      <el-table-column prop="statutoryText" label="法定节假日（三薪）" min-width="130" />
      <el-table-column prop="workdayText" label="调休上班" min-width="130" />
      <template #empty>该年份暂无内置数据，可经 overrides 自行维护</template>
    </el-table>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      {{ year }} 年合计放假 <strong>{{ totalRest }}</strong> 天。数据包 <code>FESTIVALS</code> 与展平索引
      <code>HOLIDAY_DAYS / WORKDAY_DAYS</code> 均从组件库导出，可自渲染年报/公告页。
    </p>
  </el-space>
</template>

显示代码

自定义单元格

2026 年 10 月

一二三四五六日

28

29

30

1国庆节

2国庆节张工 值守

3国庆节

4休

5休李工 值守

6休

7休

8

9

10班

11

12王工 巡检

13

14

15

16

17

18

19张工 巡检

20

21

22

23

24

25

26李工 值守

27

28

29

30

31

1

2

3

4

5

6

7

8

节假日班调休上班法定节假日（三薪）当月工作日 18 天

#cell 插槽拿到完整 meta（工作日/节假日/角标/选中态），法定标记自绘后可继续叠加业务标记（值班/巡检/约满）。

点击交互、月份切换、图例统计仍由组件托管。

#cell 插槽拿到完整 meta，法定标记自绘后叠加业务标记（值班/巡检/约满），点击与切月仍由组件托管。

<script setup lang="ts">
/** 场景：cell 插槽自定义——在法定日历上叠加值班/巡检标记（排班场景） */
import { ref } from 'vue'
import { BizWorkdayCalendar } from 'vue3-ep-biz-lib'

const month = ref('2026-10')
const selected = ref('')

/** 值班表：date → 班次标记（业务侧通常来自接口） */
const dutyMap: Record<string, string> = {
  '2026-10-02': '张工 值守',
  '2026-10-05': '李工 值守',
  '2026-10-12': '王工 巡检',
  '2026-10-19': '张工 巡检',
  '2026-10-26': '李工 值守',
}
</script>

<template>
  <div style="display: flex; gap: 20px; align-items: flex-start; flex-wrap: wrap">
    <BizWorkdayCalendar v-model="selected" v-model:month="month">
      <template #cell="{ meta }">
        <span style="line-height: 22px; font-variant-numeric: tabular-nums">{{ meta.day }}</span>
        <span
          v-if="meta.statutory && meta.holidayName"
          style="max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 12px; color: var(--el-color-danger)"
        >
          {{ meta.holidayName }}
        </span>
        <span
          v-else-if="meta.badge === 'rest'"
          style="padding: 0 4px; border-radius: 3px; font-size: 12px; line-height: 16px; color: var(--el-color-danger); background: var(--el-color-danger-light-9)"
        >休</span>
        <span
          v-else-if="meta.badge === 'work'"
          style="padding: 0 4px; border-radius: 3px; font-size: 12px; line-height: 16px; color: var(--el-color-warning); background: var(--el-color-warning-light-9)"
        >班</span>
        <span
          v-if="dutyMap[meta.date]"
          style="max-width: 100%; margin-top: 1px; padding: 0 3px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; border-radius: 3px; font-size: 12px; line-height: 16px; color: var(--el-color-primary); background: var(--el-color-primary-light-9)"
          :title="dutyMap[meta.date]"
        >
          {{ dutyMap[meta.date] }}
        </span>
      </template>
    </BizWorkdayCalendar>
    <el-alert type="info" :closable="false" style="width: 320px">
      <p style="margin: 0 0 6px">#cell 插槽拿到完整 <code>meta</code>（工作日/节假日/角标/选中态），法定标记自绘后可继续叠加业务标记（值班/巡检/约满）。</p>
      <p style="margin: 0">点击交互、月份切换、图例统计仍由组件托管。</p>
    </el-alert>
  </div>
</template>

显示代码

Props

属性	类型	默认值	说明
v-model	string	—	选中日期（'YYYY-MM-DD'），点击单元格更新
v-model:month	string	当月	展示月份（'YYYY-MM'），工具栏切换时更新
overrides	Record<string, WorkdayOverride>	—	自定义日覆盖：key='YYYY-MM-DD'，优先级高于内置法定数据
show-legend	boolean	true	是否显示底部图例（含当月工作日统计）
mark-today	boolean	true	是否标记今天
first-day-of-week	0 | 1	1	每周首日：0=周日，1=周一
min-date	string	—	可选日期下限（'YYYY-MM-DD'，含），区间外置灰且点击无效
max-date	string	—	可选日期上限（'YYYY-MM-DD'，含）

WorkdayOverride 结构：{ type: 'holiday' \| 'workday'; name?: string }——holiday 为休息日（可带名），workday 为补班工作日。

Events

事件名	参数	说明
update:model-value	(date: string)	点击可选单元格时触发
update:month	(month: string)	工具栏切月/切年时触发
cell-click	(meta: WorkdayCellMeta)	点击单元格（禁用/非本月不触发）；meta 含 isWorkday / statutory / holidayName / badge 等完整状态

Slots

插槽名	作用域	说明
cell	{ meta: WorkdayCellMeta }	自定义单元格内容（值班标记、约满状态等业务叠加）

Expose

名称	类型	说明
isWorkday	(date: string | Date) => boolean	是否工作日（自动携带当前 overrides）
getCellMeta	(date: string) => WorkdayCellMeta	任意日期完整状态（不受展示月限制）
goToday	() => void	回到今天所在月并选中今天
getMonthStats	(month?: string) => WorkdayMonthStats	月度统计 { total, workdays, restdays }，缺省为当前展示月

工具函数（组件模块同名导出）

函数	签名	说明
isWorkday	(date, overrides?) => boolean	是否工作日
countWorkdays	(start, end, overrides?) => number	区间工作日天数（含首尾，起止倒置自动交换）
addWorkdays	(date, n, overrides?) => Date	加 n 个工作日（n 可负、可为 0），逐日跳过非工作日
getWorkdayDisabledDate	(overrides?) => (date: Date) => boolean	生成 el-date-picker 的 disabled-date 函数
resolveDay	(date, overrides?) => ResolvedDay	单日完整解析（isWorkday/holidayName/statutory/badge）
toDateKey / parseDateKey	(date | string)	'YYYY-MM-DD' 与 Date 互转（本地时区）

判定口径：overrides（自定义，最高）> 内置调休补班 > 内置节假日 > 自然周（周六日休息）。

数据包导出

导出	类型	说明
FESTIVALS	Record<number, FestivalArrange[]>	按年官方口径安排（节日名/放假区间/法定三薪日/调休上班日）
HOLIDAY_DAYS	Record<string, HolidayEntry>	展平休息日索引（key='YYYY-MM-DD'，statutory 标记三薪日）
WORKDAY_DAYS	Record<string, true>	展平调休补班日索引

数据时效

内置数据覆盖 2024~2026 年；此后年份的安排由国务院办公厅通常于上年 11 月发布，数据包未收录前按自然周推导（周六日休息），请经 overrides 自行维护或等组件库版本更新。