Calendar 日曆面板

月視圖日曆。沿用 DatePicker core 的月網格演算法，支援範圍約束與方向鍵網格導覽。

基礎用法

基礎用法

2026年10月

日一二三四五六

<script setup>
import { ref } from 'vue'
const date = ref(new Date())
</script>

<template>
  <LhCalendar v-model="date" />
</template>

<script>
export default {
  data() {
    return { date: new Date() }
  },
}
</script>

<template>
  <LhCalendar v-model="date" />
</template>

一段時間與多選

selection 支援三種模式：'single'（預設）/ 'range'（兩次點選確定起止）/ 'multiple'（點選切換多日期）。

一段時間

2026年10月

日一二三四五六

2026年11月

日一二三四五六

<script setup>
import { ref } from 'vue'
const span = ref([new Date(2026, 8, 5), new Date(2026, 8, 20)])
</script>

<template>
  <LhCalendar v-model="span" selection="range" :panels="2" />
</template>

<script>
export default {
  data() {
    return { span: [new Date(2026, 8, 5), new Date(2026, 8, 20)] }
  },
}
</script>

<template>
  <LhCalendar v-model="span" selection="range" :panels="2" />
</template>

多選

2026年10月

日一二三四五六

<script setup>
import { ref } from 'vue'
const dates = ref([new Date(2026, 8, 10)])
</script>

<template>
  <LhCalendar v-model="dates" selection="multiple" />
</template>

<script>
export default {
  data() {
    return { dates: [new Date(2026, 8, 10)] }
  },
}
</script>

<template>
  <LhCalendar v-model="dates" selection="multiple" />
</template>

可選範圍約束

範圍約束

2026年10月

日一二三四五六

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

// 注意：JS 的月份從 0 起算，new Date(2026, 8, 1) 是 9 月 1 日
const range = [new Date(2026, 8, 1), new Date(2026, 8, 28)]
const rangeDate = ref(new Date())
</script>

<template>
  <LhCalendar v-model="rangeDate" :range="range" />
</template>

<script>
export default {
  data() {
    return {
      // 注意：JS 的月份從 0 起算，new Date(2026, 8, 1) 是 9 月 1 日
      range: [new Date(2026, 8, 1), new Date(2026, 8, 28)],
      rangeDate: new Date(),
    }
  },
}
</script>

<template>
  <LhCalendar v-model="rangeDate" :range="range" />
</template>

input 折疊形態

mode="input" 把常駐面板收進輸入框，點選展開，節省縱向空間。panels 控制展開後的月面板數，placeholder 自訂佔位文字，close-on-select 決定選中後是否自動收起。

input 形態 + 雙面板

2026年10月

日一二三四五六

2026年11月

日一二三四五六

<script setup>
import { ref } from 'vue'
const inputDate = ref(new Date())
</script>

<template>
  <LhCalendar
    v-model="inputDate"
    mode="input"
    :panels="2"
    placeholder="请选择日期"
  />
</template>

<script>
export default {
  data() {
    return { inputDate: new Date() }
  },
}
</script>

<template>
  <LhCalendar
    v-model="inputDate"
    mode="input"
    :panels="2"
    placeholder="请选择日期"
  />
</template>

選中後不自動收起

2026年10月

日一二三四五六

<script setup>
import { ref } from 'vue'
const inputDate2 = ref(new Date())
</script>

<template>
  <LhCalendar
    v-model="inputDate2"
    mode="input"
    :close-on-select="false"
    placeholder="选中后保持面板展开"
  />
</template>

<script>
export default {
  data() {
    return { inputDate2: new Date() }
  },
}
</script>

<template>
  <LhCalendar
    v-model="inputDate2"
    mode="input"
    :close-on-select="false"
    placeholder="选中后保持面板展开"
  />
</template>

API

LhCalendar Props

屬性名	說明	類型	預設值
modelValue	目前選中日期（受控 v-model）	Date | Date[]	—
selection	選擇模式：單選（預設）/ 一段時間（起止日期）/ 多選	"single" | "range" | "multiple"	'single'
range	可選日期範圍約束	[Date, Date]	—
mode	展示形態	"panel" | "input"	'panel'
panels	同時展示的月面板數（flex 換行排列）	number	1
placeholder	input 模式的佔位文字	string	—
closeOnSelect	input 模式選中後是否自動收起面板	boolean	true
sx	sx 快速版面配置屬性	LhSxProps	—

Events

事件名	說明	回呼參數
update:modelValue	選中值變化時觸發（v-model）	(value: Date | Date[])
change	選中值變化時觸發	(value: Date | Date[])
select	選中日期時觸發（點選或鍵盤導覽）	(value: Date)

插槽：cell（自訂儲存格）、header（標頭）。

無障礙

• 網格語意 role="grid"（列 row、格 gridcell），當日 aria-current="date"
• 方向鍵移動日期焦點（±1 天 / ±7 天）、Home/End 列首尾、PageUp/Down 翻月——對齊 APG grid pattern
• 範圍外的日期原生 disabled 移出互動

類型定義

本元件對外匯出的 TypeScript 類型結構如下（自動提取自 packages/components/calendar/src/types.ts 與 @lh-ui/share/core/* 原始碼，點選各條目展開檢視完整定義；屬性說明見上方 Props 表）：

LhCalendarMode

/** 展示形態：panel 常駐面板（預設）/ input 點選輸入框展開的折疊面板 */
export type LhCalendarMode = 'panel' | 'input'

LhCalendarValue

/** 受控值的形態隨 selection 變化：單選 Date / 一段時間 Date[]（長度 2 的起止）/ 多選 Date[]。
 *  不用 [Date, Date] 元組：SFC 編譯器無法從元組推斷執行時期類型，會導致 prop 校驗告警 */
export type LhCalendarValue = Date | Date[]

LhCalendarProps

export interface LhCalendarProps {
  /** 目前選中（受控 v-model；未傳時元件內部維護選中態） */
  modelValue?: LhCalendarValue
  /** 選擇模式：單選（預設）/ 一段時間（起止日期）/ 多選 */
  selection?: LhCalendarSelection
  /** 可選日期範圍約束 */
  range?: LhCalendarRange
  /** 展示形態：panel 常駐面板（預設）/ input 點選輸入框展開的折疊面板 */
  mode?: LhCalendarMode
  /** 同時展示的月面板數（flex 換行排列） */
  panels?: number
  /** input 模式的佔位文字 */
  placeholder?: string
  /** input 模式選中後是否自動收起面板 */
  closeOnSelect?: boolean
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

LhCalendarSelection _{（來自 @lh-ui/share/core/calendar）}

/** 選擇模式：單選 / 一段時間（起止）/ 多選 */
export type LhCalendarSelection = 'single' | 'range' | 'multiple'

LhCalendarRange _{（來自 @lh-ui/share/core/calendar）}

/** 可選日期範圍約束 */
export type LhCalendarRange = [Date, Date]