FxCalendar 日历

按月展示日期的日历组件，支持单日历 / 范围双日历（按周边界切分）、按钮 / 下拉两种头部控制器、自定义头部与单元格。

FxCalendar 属于 @fx/components，不依赖任何 UI 框架。

基础用法

v-model 绑定一个 Date，未指定时默认展示当月。v-model 支持双向绑定。

<template>
  <FxCalendar v-model="value" />
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref(new Date())
</script>

控制器类型

可设置头部控制器的形态为 button（按钮组）或 select（年/月下拉）。设为 select 时，可用 formatter 自定义下拉标签。

<template>
  <FxRadioGroup v-model="controllerType" class="mb-4">
    <FxRadioBtn value="select">select</FxRadioBtn>
    <FxRadioBtn value="button">button</FxRadioBtn>
  </FxRadioGroup>
  <FxCalendar v-model="value" :controller-type="controllerType" />
</template>

<script setup lang="ts">
import { ref } from "vue"

const controllerType = ref<"select" | "button">("select")
const value = ref(new Date())
</script>

自定义单元格

通过 date-cell 具名插槽自定义单元格内容：作用域参数 data 含 { type, isSelected, isToday, day, date }，其中 day 为 YYYY-MM-DD 格式，isSelected 表示是否被选中，isToday 表示是否为今天。详见下方 API。

<template>
  <FxCalendar v-model="value">
    <template #date-cell="{ data }">
      <p :class="{ 'is-selected': data.isSelected, 'is-today': data.isToday }">
        {{ data.day.split("-").slice(1).join("-") }}
        {{ data.isSelected ? "✔️" : "" }}
      </p>
    </template>
  </FxCalendar>
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref(new Date())
</script>

<style scoped>
.is-selected,
.is-today {
  color: #1989fa;
}
</style>

范围模式

设置 range 属性指定展示范围：start 须为周首，end 须为周末，且跨度不得超过两个月。组件按周拆分为多张日期表；不满足约束时回退为单日历。

<template>
  <FxCalendar :range="[new Date(2019, 2, 4), new Date(2019, 2, 24)]" />
</template>

自定义头部

通过 header 具名插槽完全替换默认头部：作用域参数 { date } 为已格式化的年月文案。可结合 ref + selectDate() 实现自定义按钮组（暴露方法详见 Exposes）。

<template>
  <FxCalendar ref="calendar">
    <template #header="{ date }">
      <span>自定义头部内容</span>
      <span>{{ date }}</span>
      <FxButtonGroup>
        <FxBtn size="small" @click="selectDate('prev-year')">上一年</FxBtn>
        <FxBtn size="small" @click="selectDate('prev-month')">上个月</FxBtn>
        <FxBtn size="small" @click="selectDate('today')">今天</FxBtn>
        <FxBtn size="small" @click="selectDate('next-month')">下个月</FxBtn>
        <FxBtn size="small" @click="selectDate('next-year')">下一年</FxBtn>
      </FxButtonGroup>
    </template>
  </FxCalendar>
</template>

<script setup lang="ts">
import { ref } from "vue"
import type { CalendarDateType, FxCalendarInstance } from "@fx/components"

const calendar = ref<FxCalendarInstance>()

const selectDate = (val: CalendarDateType) => {
  if (!calendar.value) return
  calendar.value.selectDate(val)
}
</script>

API

Attributes

属性	说明	类型	默认值
model-value (v-model)	绑定值	Date	—
range	时间范围（start 须为周首，end 须为周末，跨度 ≤ 两月）	[Date, Date]	—
controller-type	头部控制器形态	'button' | 'select'	button
formatter	controller-type='select' 时格式化年/月下拉标签	(value: number, type: 'year' | 'month') => string | number	—

Events

事件名	说明	类型
update:modelValue	值变化	(value: Date) => void
input	与 update:modelValue 同步触发	(value: Date) => void

Slots

插槽名	作用域	说明
header	{ date: string }（如 2026 年 7 月）	完全自定义头部，默认渲染标题 + 控制器
date-cell	{ data: CalendarDateCellSlot }	自定义单元格，data 含 { type, isSelected, isToday, day, date }

CalendarDateCellSlot：

interface CalendarDateCellSlot {
  type: 'prev-month' | 'current-month' | 'next-month'
  isSelected: boolean
  isToday: boolean
  day: string   // YYYY-MM-DD
  date: Date
}

Exposes

名称	说明	类型
selectedDay	当前选中日期	ComputedRef<Dayjs | undefined>
pickDay	选中指定日期	(day: Dayjs) => void
selectDate	头部按钮动作	(type: 'prev-month' | 'next-month' | 'prev-year' | 'next-year' | 'today') => void
calculateValidatedDateRange	根据起止日期计算合法的按周切分范围	(start: Dayjs, end: Dayjs) => [Dayjs, Dayjs][]

Exposes 中的 Dayjs 来自 dayjs（@fx/utils 已内置并扩展常用插件）。