DIV CSS 佈局教程網

jQuery UI Datepicker 參數全解:從格式化到事件回呼
編輯:JQuery特效代碼     

jQuery UI 的 datepicker() 是網站後台最常出現的日曆元件。它的所有選項都遵循同一套「初始化 / 讀取 / 設定」三段式介面,先把這個規則記住,剩下的參數查表即可。

// 初始化
$('.selector').datepicker({ dateFormat: 'yy-mm-dd' });

// 讀取目前設定
var fmt = $('.selector').datepicker('option', 'dateFormat');

// 於執行期變更設定
$('.selector').datepicker('option', 'dateFormat', 'yy-mm-dd');

一、日期格式與替代欄位

  • dateFormat(預設 'mm/dd/yy'):控制日期字串的顯示格式,yy 為四位年、m 為月、d 為日。
  • altField:把選到的日期同步寫入另一個欄位,常用於「畫面顯示台灣格式、送給後端的是 ISO 格式」。
  • altFormat:搭配 altField 使用,指定寫入替代欄位時的格式。
  • appendText:在輸入框後方附加提示文字,例如 '(yyyy-mm-dd)'。
  • constrainInput(預設 true):限制鍵盤輸入只能符合設定格式,可關閉。
  • navigationAsDateFormat:讓上/下月與今天等按鈕文字套用 dateFormat 格式化,例如顯示成月份名稱。

二、預設值與可選範圍

  • defaultDate:首次開啟時預選的日期。可用 Date 物件、數字(+7 表示今天之後七天)或字串('+1m +7d')。
  • minDate / maxDate:限制可選的最小與最大日期,取值規則同 defaultDate。
  • shortYearCutoff(預設 '+10'):兩位數年份的判定門檻,超過則視為上一個世紀。
  • yearRange(預設 '-10:+10'):年份下拉選單的範圍,支援相對(-nn:+nn)與絕對(2000:2010)兩種寫法。
  • changeMonth / changeYear:是否讓月份與年份變成下拉選單,跨年查詢時必開。
  • firstDay:一週從哪天開始,0 是週日、1 是週一。

三、面板外觀與顯示行為

  • numberOfMonths:一次顯示幾個月。整數代表數量,陣列如 [2, 3] 代表兩列三欄。
  • showCurrentAtPos:多月份時,當月顯示在第幾格(從 0 起算)。
  • showMonthAfterYear:標題列是否把月份放在年份之後,中文環境通常設為 true。
  • showOtherMonths:是否顯示前後月份在當月格子上(不可點選)。
  • stepMonths:點擊上月/下月時一次跳幾個月。
  • showOn:觸發日曆的事件,focus(預設)、button、both。
  • showAnim:展開動畫名稱,如 show、fold、slideDown;若想關閉動畫可搭配 duration 設為 0。
  • showOptions:傳入動畫的附加參數,例如 { direction: 'up' }。
  • duration:動畫時長,可用 slow/normal/fast 或毫秒數。
  • hideIfNoPrevNext:沒有可翻的月份時隱藏翻頁按鈕,而非顯示為禁用。
  • gotoCurrent:設為 true 時,點「今天」會跳到目前選取日而非真正的今天。
  • isRTL:文字由右至左排列,供阿拉伯語等語言使用。

四、按鈕與面板

  • buttonImage:以圖片作為觸發鈕,此時按鈕文字會變成 alt 屬性而不直接顯示。
  • buttonImageOnly:設為 true 時,圖片直接放在欄位後方而不包在按鈕裡。
  • buttonText:觸發按鈕的文字。
  • showButtonPanel:是否在面板底部顯示按鈕列(Done、Today 才會出現)。
  • closeText(預設 'Done')與 currentText(預設 'Today'):分別設定關閉鈕與今天鈕的文字,兩者都需先開啟 showButtonPanel。

五、多語系:月份與星期的名稱

  • monthNames:完整月份名稱陣列。
  • monthNamesShort:月份縮寫陣列。
  • dayNames:完整星期名稱,從週日開始。
  • dayNamesShort:星期短縮寫,用於面板行頭。
  • dayNamesMin:星期最短縮寫,例如 Su Mo Tu。

實務上很少手寫這些陣列,直接引入官方提供的 i18n 語言包(如 jquery.ui.datepicker-zh-TW.js)即可一次搞定。

六、事件回呼

beforeShow: function(input)

面板顯示之前觸發,參數是目前的 input 元素,可用來動態調整設定。

beforeShowDay: function(date)

面板上每一天在綁定時都會呼叫一次,必須回傳一個陣列:

[可選與否(true/false), 該日的 CSS class 名稱, 滑鼠移入的提示文字]

要「週六日不可預約」或「已額滿的日期標灰」,都靠這個回呼。

onChangeMonthYear: function(year, month, inst)

切換月份或年份時觸發,常用來同步更新旁邊的統計數字。

onSelect: function(dateText, inst)

選定日期後觸發,dateText 為格式化後的字串,inst 為元件實例。

onClose: function(dateText, inst)

面板關閉時觸發,無論是否有選日期都會執行。

一個實用的完整設定範例

$("#date").datepicker({
  dateFormat: "yy-mm-dd",
  changeMonth: true,
  changeYear: true,
  showMonthAfterYear: true,
  yearRange: "2020:2030",
  minDate: 0,                       // 不可選過去
  maxDate: "+1m",
  showButtonPanel: true,
  currentText: "今天",
  closeText: "關閉",
  beforeShowDay: function (date) {
    var day = date.getDay();
    return [day !== 0 && day !== 6, ""];   // 週末不可選
  },
  onSelect: function (dateText) {
    console.log("已選擇:" + dateText);
  }
});

把「格式、範圍、面板行為、多語系、事件」這五個維度分開思考,日曆元件就不再是一堆難以理解的參數,而是可以按需組裝的積木。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved