DIV CSS 佈局教程網

jQuery UI Datepicker 完整參數與事件參考
編輯:JQuery特效代碼     

jQuery UI 的 Datepicker 是關於參數最多的官方元件之一。這裡整理它的初始化方式、常用參數、事件回呼與格式化語法,方便查閱。

基本初始化

<!DOCTYPE html>
<html>
<head>
<link href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/base/jquery-ui.css" rel="stylesheet" type="text/css"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>

<script>
$(document).ready(function() {
 $("#datepicker").datepicker();
});
</script>
</head>
<body style="font-size:62.5%;">

<div type="text" id="datepicker"></div>

</body>
</html>

讀寫參數的統一語法:$(el).datepicker('option', '參數名', 值) 設定、$(el).datepicker('option', '參數名') 讀取。

呈現與格式相關

altField(String,預設 ''):將選擇的日期同步到另一個域中,配合 altFormat 可以顯示不同格式的日期字串。

$('.selector').datepicker({ altField: '#actualDate' });

altFormat(String,預設 ''):當設定了 altField 的情況下,顯示在另一個域中的日期格式。

$('.selector').datepicker({ altFormat: 'yy-mm-dd' });

appendText(String,預設 ''):在日期插件的所屬域後面添加指定的字串。

$('.selector').datepicker({ appendText: '(yyyy-mm-dd)' });

dateFormat(String,預設 'mm/dd/yy'):設定日期字串的顯示格式。

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

showMonthAfterYear(Boolean,預設 false):是否在面板的頭部年份後面顯示月份。

numberOfMonths(Number 或 Array,預設 1):一次要顯示多少個月份。整數代表顯示月份的數量,陣列則代表顯示的行與列數量。

$('.selector').datepicker({ numberOfMonths: [2, 3] });

showCurrentAtPos(Number,預設 0):多月份顯示時,當前月份顯示的位置,自頂部/左邊開始算第幾位。

showOtherMonths(Boolean,預設 false):是否在當前面板顯示上、下兩個月的部分日期(不可選)。

stepMonths(Number,預設 1):當點擊上/下一月時,一次翻幾個月。

日期範圍限制

minDate/maxDate(Date、Number 或 String,預設 null):最小/最大可選日期。可以是 Date 物件、數字(從今天算起,例如 +7),或有效字串('y' 年、'm' 月、'w' 周、'd' 日,例如 '+1m +7d')。

$('.selector').datepicker({ minDate: new Date(2007, 1 - 1, 1) });
$('.selector').datepicker({ maxDate: '+1m +1w' });
$('.selector').datepicker('option', 'maxDate', '12/25/2012');

defaultDate(Date、Number 或 String,預設 null):設定預設加載完後第一次顯示時選中的日期,格式同 minDate/maxDate。

$('.selector').datepicker({ defaultDate: +7 });

shortYearCutoff(String 或 Number,預設 '+10'):設定截止年份。若是 0~99 的數字則以當前年份開始算起;若為字串,則轉為數字後再與當前年份相加。當超過截止年份時,則被認為是上個世紀。

$('.selector').datepicker({ shortYearCutoff: 50 });

yearRange(String,預設 '-10:+10'):控制年份下拉列表中顯示的年份範圍,可以是相對當前年(-nn:+nn),也可以是絕對值(-nnnn:+nnnn)。

$('.selector').datepicker({ yearRange: '2000:2010' });

constrainInput(Boolean,預設 true):如果設為 true,則約束當前輸入的日期格式。

月份與星期的名稱

monthNames(Array):所有月份的名稱,預設為英文 January~December。

monthNamesShort(Array):所有月份的縮寫,預設 Jan~Dec。

dayNames(Array):一星期中每天的名稱,從星期天開始。用於 dateFormat 顯示,以及日曆中滑鼠移至行頭時的提示。

dayNamesShort(Array):每天的中等長度縮寫,預設 Sun~Sat。

dayNamesMin(Array):每天的最短縮寫,預設 Su~Sa,用於日曆中的行頭顯示。

中文化範例:

$('.selector').datepicker({
 monthNames: ['一月','二月','三月','四月','五月','六月',
       '七月','八月','九月','十月','十一月','十二月'],
 monthNamesShort: ['一','二','三','四','五','六','七','八','九','十','十一','十二'],
 dayNames: ['星期日','星期一','星期二','星期三','星期四','星期五','星期六'],
 dayNamesShort: ['周日','周一','周二','周三','周四','周五','周六'],
 dayNamesMin: ['日','一','二','三','四','五','六']
});

firstDay(Number,預設 0):設定一周中的第一天。星期天為 0,星期一為 1,以此類推。

按鈕與面板

showOn(String,預設 'focus'):什麼事件觸發顯示面板,可選值為 focus、button、both。

$('.selector').datepicker({ showOn: 'both' });

buttonImage(String,預設 ''):設置彈出按鈕的圖片。若非空,則按鈕的文字將成為 alt 屬性,不直接顯示。

$('.selector').datepicker({ buttonImage: '/images/datepicker.gif' });

buttonImageOnly(Boolean,預設 false):設為 true 時,只在欄位後方放一張圖片作為觸發器,不顯示按鈕外框。

buttonText(String,預設 '...'):設置觸發按鈕的文字內容。

showButtonPanel(Boolean,預設 false):設置是否在面板上顯示相關的按鈕(「關閉」與「今天」)。此參數為 true 時,closeText 與 currentText 才會生效。

closeText(String,預設 'Done'):關閉按鈕的文字。

currentText(String,預設 'Today'):當天按鈕的文字。

gotoCurrent(Boolean,預設 false):如果設為 true,則點擊當天按鈕時,將移至當前已選中的日期,而不是今天。

changeMonth(Boolean,預設 false):允許通過下拉框列表選取月份。

changeYear(Boolean,預設 false):允許通過下拉框列表選取年份。

hideIfNoPrevNext(Boolean,預設 false):當沒有上一個/下一個可選擇的情況下,隱藏掉相應的按鈕(預設為不可用狀態)。

navigationAsDateFormat(Boolean,預設 false):如果設為 true,則 formatDate 函式將應用到 prevText、nextText 和 currentText 的值中顯示,例如顯示為月份名稱。

prevText/nextText(String,預設 'Prev'/'Next'):上個月/下個月連結的顯示文字。

動畫與其他

showAnim(String,預設 'show'):設置顯示、隱藏日期插件的動畫名稱。

$('.selector').datepicker({ showAnim: 'fold' });

showOptions(Options,預設 {}):如果使用 showAnim 來顯示動畫效果,可以通過此參數增加一些附加的參數設置。

$('.selector').datepicker({ showOptions: {direction: 'up'} });

duration(String 或 Number,預設 'normal'):日期控件展開動畫的顯示時間,可選 'slow'、'normal'、'fast','' 代表立刻,數字代表毫秒數。

isRTL(Boolean,預設 false):如果設為 true,則所有文字從右至左顯示。

事件回呼

beforeShow function(input):在日期控件顯示面板之前觸發,參數為當前觸發事件的控件的實例物件。

$('.selector').datepicker({ beforeShow: function(input) { ... } });

beforeShowDay function(date):在面板顯示前,每個日期綁定時都觸發,參數為該日期。必須回傳一個陣列:[0] 此日期是否可選(true/false)、[1] 此日期的 CSS 樣式名稱("" 表示預設)、[2] 滑鼠移上去時出現的提示內容。這是做「可預約日期」或「特價日標記」的關鍵。

$('.selector').datepicker({ beforeShowDay: function(date) { ... } });

onChangeMonthYear function(year, month, inst):當年份或月份改變時觸發,參數為改變後的年份月份和當前實例。

onClose function(dateText, inst):當日期面板關閉後觸發(無論是否有選擇日期),參數為選擇的日期和當前實例。

onSelect function(dateText, inst):選中一個日期後觸發。

$('.selector').datepicker({ onSelect: function(dateText, inst) { ... } });

全域靜態方法

· $.datepicker.setDefaults(settings) — 全域設置日期選擇插件的參數

· $.datepicker.formatDate(format, date, settings) — 格式化顯示的日期字串

· $.datepicker.iso8601Week(date) — 給出一個日期,確認它是當年的第幾週

· $.datepicker.parseDate(format, value, settings) — 按照指定格式取得日期字串

日期格式語法

· d — 每月的第幾天(沒有前導零)

· dd — 每月的第幾天(兩位數字)

· o — 一年中的第幾天(沒有前導零)

· oo — 一年中的第幾天(三位數字)

· D — 星期名稱的簡寫

· DD — 星期名稱的完整寫法

· m — 月份(沒有前導零)

· mm — 月份(兩位數字)

· M — 月份名稱的簡寫

· MM — 月份名稱的完整寫法

· y — 年份(兩位數字)

· yy — 年份(四位數字)

· @ — Unix 時間戳(從 01/01/1970 開始)

· '...' — 文字

· '' — 單引號

·(其他字元)— 原樣輸出為文字

預設格式常數

· ATOM — 'yy-mm-dd'(同 RFC 3339/ISO 8601)

· COOKIE — 'D, dd M yy'

· ISO_8601 — 'yy-mm-dd'

· RFC_822 — 'D, d M y'

· RFC_850 — 'DD, dd-M-y'

· RFC_1036 — 'D, d M y'

· RFC_1123 — 'D, d M yy'

· RFC_2822 — 'D, d M yy'

· RSS — 'D, d M y'

· TIMESTAMP — '@'

· W3C — 'yy-mm-dd'

實務上的兩個提醒

altField 的用處:畫面上顯示「2026 年 8 月 26 日」對使用者友善,但後端要的是 2026-08-26。用 altField 指向一個隱藏欄位並設 altFormat 為 'yy-mm-dd',就能同時滿足兩邊,不必在提交前額外轉格式。

注意 div 與 input 的差別:範例中把 datepicker 掛在 <div> 上,這種用法會讓日曆永遠顯示在頁面上(inline 模式),適合當作篩選條件面板。若掛在 <input> 上則是彈出式,點擊時才出現。兩者行為不同,依需求挑選。

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