萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

輕量級原生日歷插件 calendar.js 使用指南:配置、模塊化、主題定製

插件特性

  • 零依賴,壓縮後 < 5KB
  • 支持日期/時間選擇、範圍限制、多種格式
  • CMD/AMD/ESM/全局變量多模塊化兼容
  • CSS 變量主題系統,輕鬆換膚
  • 無障礙鍵盤導航、ARIA 屬性

安裝引入

<!-- CSS -->
<link rel="stylesheet" href="calendar.css">

<!-- JS: 全局變量 -->
<script src="calendar.min.js"></script>

<!-- 或 AMD/CMD -->
<script>require(['calendar'], function(calendar) { ... });</script>

<!-- 或 ES Module -->
<script type="module">import Calendar from './calendar.esm.js'; ...</script>

快速開始

<input type="text" id="dateInput" readonly>
<button id="dateBtn">選擇日期</button>

<script>
calendar.init({
  targetId: 'dateInput',        // 日期寫入目標 input
  triggerId: ['dateInput', 'dateBtn'], // 觸發元素(可多個)
  alignId: 'dateInput',         // 定位基準元素
  format: '-',                  // 日期分隔符:'-' | '/' | '.'
  hms: 'on',                    // 'on' 含時分秒,'off' 僅日期
  min: '2024-01-01 00:00:00',   // 最小可選時間
  max: '2025-12-31 23:59:59',   // 最大可選時間
  zIndex: 9999
});
</script>

完整配置選項

參數類型默認值說明
targetIdString必填日期寫入的 input id
triggerIdString/ArraytargetId觸發彈出的元素 id
alignIdStringtargetId彈層定位參考元素 id
formatString'-'日期分隔符:'-'/'/'/'.'
hmsString'on''on' 顯示時分秒,'off' 僅日期
minStringnull最小時間,格式同輸出
maxStringnull最大時間
zIndexNumber9999彈層層級
langString'zh-CN'語言:zh-CN/en-US/ja-JP...
firstDayNumber0週起始日:0=周日,1=周一
onSelectFunctionnull選擇後回調 function(dateStr, dateObj)

CSS 變量主題定製

:root {
  --cal-bg: #fff;
  --cal-border: #e0e0e0;
  --cal-header-bg: #007bff;
  --cal-header-color: #fff;
  --cal-week-color: #666;
  --cal-day-color: #333;
  --cal-day-hover: #e8f4fd;
  --cal-day-selected: #007bff;
  --cal-day-selected-color: #fff;
  --cal-day-disabled: #f5f5f5;
  --cal-day-disabled-color: #ccc;
  --cal-today-ring: #007bff;
  --cal-radius: 8px;
  --cal-shadow: 0 4px 20px rgba(0,0,0,.15);
}

.dark-theme {
  --cal-bg: #1e1e1e;
  --cal-border: #333;
  --cal-header-bg: #333;
  --cal-day-color: #ddd;
  --cal-day-hover: #333;
  --cal-day-selected: #00bfff;
  --cal-day-disabled: #2a2a2a;
  --cal-day-disabled-color: #666;
}

運行時切換:document.documentElement.classList.add('dark-theme') 即可無縫換膚。

模塊化用法示例

// Webpack/ESM
import Calendar from 'calendar.js';
const cal = new Calendar({
  targetId: 'date1',
  triggerId: 'date1',
  onSelect: (str, date) => console.log('選中:', str, date)
});

// RequireJS
define(['calendar'], function(Calendar) {
  new Calendar({ targetId: 'date2', hms: 'off' });
});

// CMD (SeaJS)
seajs.use('calendar', function(Calendar) {
  new Calendar({ targetId: 'date3' });
});

進階:動態銷毀與重建

// 單頁應用路由切換時銷毀
const cal = calendar.init({ targetId: 'dateInput', ... });
// 路由離開時
cal.destroy(); // 移除 DOM、事件監聽、定時器

常見問題

  1. 定位錯誤:alignId 元素必須可見且有佈局尺寸,隱藏元素無法定位。
  2. 日期格式不匹配:min/max 格式必須與 format + hms 一致。
  3. z-index 被遮擋:調大 zIndex 或檢查父級 overflow:hidden/transform 產生新堆疊上下文。
  4. 移動端鍵盤彈出遮擋:監聽 focus 滾動容器進視口,或用 position:fixed 彈層。

總結

calendar.js 以「輕量、零依賴、多模塊、CSS 變量主題」定位輕量級日期選擇需求。核心 API 極簡:init(config) + destroy()。現代項目可直接用 <input type="date/datetime-local"> 原生控件(樣式受限),或引入 Flatpickr/Date-fns 等功能更豐富的庫。

copyright © 萬盛學電腦網 all rights reserved