bootstrap - 日期時間選擇器

項目 

此項目是 bootstrap-datetimepicker 項目 的一個分支，原項目不支持  Time 選擇。
其它部分也進行了改進、增強，例如 load 過程增加了對 ISO-8601 日期格式的支持。
文檔是拷貝/粘貼字原項目的文檔，並且加入了更多細節說明。
 

別猶豫了，下載下來試試吧 !

下載 ZIP 包

此地址可以克隆或fork本項目

git clone git://github.com/smalot/bootstrap-datetimepicker.git

希望這個小小的項目能幫到你 !

Tags: twitter-bootstrap, datetime, picker, component, javascript, widget

截圖

十年視圖

年視圖

月視圖

日視圖*

小時視圖 *

Day view w/ meridian *

Hour view w/ meridian *

(*)  Added views to select the time part.

依賴

需要bootstrap的下拉菜單組件 (dropdowns.less) 的某些樣式，還有bootstrap的sprites (sprites.less and associated images) 中的箭頭圖標。

A standalone .css file (including necessary dropdown styles and alternative, text-based arrows) can be generated by running build/build_standalone.less through the lessc compiler:

$ lessc build/build_standalone.less datetimepicker.css

選項

所有需要"Date" 的選項都可以處理Date 對象; a String formatted according to the given format; or a timedelta relative to today, eg '-1d', '+6m +1y', etc, where valid units are 'd' (day), 'w' (week), 'm' (month), and 'y' (year).

你也可以指定一個符合 ISO-8601 格式的日期時間，就可以忽略下面的格式：

• yyyy-mm-dd
• yyyy-mm-dd hh:ii
• yyyy-mm-ddThh:ii
• yyyy-mm-dd hh:ii:ss
• yyyy-mm-ddThh:ii:ssZ

 

format

String. 默認值: 'mm/dd/yyyy'

日期格式， p, P, h, hh, i, ii, s, ss, d, dd, m, mm, M, MM, yy, yyyy 的任意組合。

• p : meridian in lower case ('am' or 'pm') - according to locale file
• P : meridian in upper case ('AM' or 'PM') - according to locale file
• s : seconds without leading zeros
• ss : seconds, 2 digits with leading zeros
• i : minutes without leading zeros
• ii : minutes, 2 digits with leading zeros
• h : hour without leading zeros - 24-hour format
• hh : hour, 2 digits with leading zeros - 24-hour format
• H : hour without leading zeros - 12-hour format
• HH : hour, 2 digits with leading zeros - 12-hour format
• d : day of the month without leading zeros
• dd : day of the month, 2 digits with leading zeros
• m : numeric representation of month without leading zeros
• mm : numeric representation of the month, 2 digits with leading zeros
• M : short textual representation of a month, three letters
• MM : full textual representation of a month, such as January or March
• yy : two digit representation of a year
• yyyy : full numeric representation of a year, 4 digits

 

weekStart

Integer. 默認值：0

一周從哪一天開始。0（星期日）到6（星期六）

startDate

Date. 默認值：開始時間

The earliest date that may be selected; all earlier dates will be disabled.

endDate

Date. 默認值：結束時間

The latest date that may be selected; all later dates will be disabled.

daysOfWeekDisabled

String, Array. 默認值: '', []

Days of the week that should be disabled. Values are 0 (Sunday) to 6 (Saturday). Multiple values should be comma-separated. Example: disable weekends: '0,6' or [0,6].

autoclose

Boolean. 默認值：false

當選擇一個日期之后是否立即關閉此日期時間選擇器。

startView

Number, String. 默認值：2, 'month'

日期時間選擇器打開之后首先顯示的視圖。 可接受的值：

• 0 or 'hour' for the hour view
• 1 or 'day' for the day view
• 2 or 'month' for month view (the default)
• 3 or 'year' for the 12-month overview
• 4 or 'decade' for the 10-year overview. Useful for date-of-birth datetimepickers.

minView

Number, String. 默認值：0, 'hour'

日期時間選擇器所能夠提供的最精確的時間選擇視圖。

maxView

Number, String. 默認值：4, 'decade'

日期時間選擇器最高能展示的選擇范圍視圖。

todayBtn

Boolean, "linked". 默認值: false

如果此值為true 或 "linked"，則在日期時間選擇器組件的底部顯示一個 "Today" 按鈕用以選擇當前日期。如果是true的話，"Today" 按鈕僅僅將視圖轉到當天的日期，如果是"linked"，當天日期將會被選中。

todayHighlight

Boolean. 默認值: false

如果為true, 高亮當前日期。

keyboardNavigation

Boolean. 默認值: true

是否允許通過方向鍵改變日期。

language

String. 默認值: 'en'

The two-letter code of the language to use for month and day names. These will also be used as the input's value (and subsequently sent to the server in the case of form submissions). Currently ships with English ('en'), German ('de'), Brazilian ('br'), and Spanish ('es') translations, but others can be added (see I18N below). If an unknown language code is given, English will be used.

forceParse

Boolean. 默認值: true

當選擇器關閉的時候，是否強制解析輸入框中的值。也就是說，當用戶在輸入框中輸入了不正確的日期，選擇器將會盡量解析輸入的值，並將解析后的正確值按照給定的格式format設置到輸入框中。

minuteStep

Number. 默認值: 5

此數值被當做步進值用於構建小時視圖。對於每個 minuteStep 都會生成一組預設時間（分鍾）用於選擇。

pickerReferer : 不建議使用

String. 默認值: 'default' (other value available : 'input')

The referer element to place the picker for the component implementation. If you want to place the picker just under the input field, just specify input.

pickerPosition

String. 默認值: 'bottom-right' (還支持 : 'bottom-left')

此選項當前只在組件實現中提供支持。通過設置選項可以講選擇器放倒輸入框下方。

viewSelect

Number or String. 默認值: same as minView (supported values are: 'decade', 'year', 'month', 'day', 'hour')

With this option you can select the view from which the date will be selected. By default it's the last one, however you can choose the first one, so at each click the date will be updated.

showMeridian

Boolean. 默認值: false

This option will enable meridian views for day and hour views.

initialDate

Date or String. 默認值: new Date()

You can initialize the viewer with a date. By default it's now, so you can specify yesterday or today at midnight ...

標記

組件模版。

<div class="input-append date" id="datetimepicker" data-date="12-02-2012" data-date-format="dd-mm-yyyy">
    <input class="span2" size="16" type="text" value="12-02-2012">
    <span class="add-on"><i class="icon-th"></i></span>
</div>            

帶有重置按鈕（用於清空輸入框）的組件模版。

<div class="input-append date" id="datetimepicker" data-date="12-02-2012" data-date-format="dd-mm-yyyy">
    <input class="span2" size="16" type="text" value="12-02-2012">
    <span class="add-on"><i class="icon-remove"></i></span>
    <span class="add-on"><i class="icon-th"></i></span>
</div>            

方法

.datetimepicker(options)

初始化日期時間選擇器。

remove

參數: None

移除日期時間選擇器。同時移除已經綁定的event、內部綁定的對象和HTML元素。

$('#datetimepicker').datetimepicker('remove');

show

參數: None

顯示日期時間選擇器。

$('#datetimepicker').datetimepicker('show');

hide

參數: None

隱藏日期時間選擇器。

$('#datetimepicker').datetimepicker('hide');

update

參數: None

使用當前輸入框中的值更新日期時間選擇器。

$('#datetimepicker').datetimepicker('update');

setStartDate

參數:

• startDate (String)

給日期時間選擇器設置一個新的起始日期。

$('#datetimepicker').datetimepicker('setStartDate', '2012-01-01');

Omit startDate (or provide an otherwise falsey value) to unset the limit.

$('#datetimepicker').datetimepicker('setStartDate');
$('#datetimepicker').datetimepicker('setStartDate', null);

setEndDate

參數:

• endDate (String)

給日期時間選擇器設置結束日期。

$('#datetimepicker').datetimepicker('setEndDate', '2012-01-01');

Omit endDate (or provide an otherwise falsey value) to unset the limit.

$('#datetimepicker').datetimepicker('setEndDate');
$('#datetimepicker').datetimepicker('setEndDate', null);

setDaysOfWeekDisabled

參數:

• daysOfWeekDisabled (String|Array)

Sets the days of week that should be disabled.

$('#datetimepicker').datetimepicker('setDaysOfWeekDisabled', [0,6]);

Omit daysOfWeekDisabled (or provide an otherwise falsey value) to unset the disabled days.

$('#datetimepicker').datetimepicker('setDaysOfWeekDisabled');
$('#datetimepicker').datetimepicker('setDaysOfWeekDisabled', null);

事件（Events）

Datetimepicker 類暴露了一組event用以對日期進行操作。

show

當選擇器顯示時被觸發。

hide

當選擇器隱藏時被觸發。

changeDate

當日期被改變時被觸發。

$('#date-end')
.datetimepicker()
.on('changeDate', function(ev){
    if (ev.date.valueOf() < date-start-display.valueOf()){
        ....
    }
});
            

changeYear

當十年視圖上的年視圖view被改變時觸發。

changeMonth

當年視圖上的月視圖view被改變時觸發。

outOfRange

當用戶選擇的日期超出startDate 或endDate 時，或者通過setDate 或 setUTCDate方法設置日期超出范圍時被觸發。

鍵盤支持

日期時間選擇器提供了鍵盤導航：

up, down, left, right 方向鍵

這些方向鍵中，left/right 向后/向前 一天，up/down 向后/向前 一周。

配合shift鍵，up/left 向后退一個月，down/right 向前進一個月。

配置ctrl鍵，up/left 向后退一年，down/right 向前進一年。

Shift+ctrl 和 ctrl 同等效果 - 也就是說，他們不能同時改變月和年，只能單獨改變年。

escape

escape 鍵可以用來隱藏、重新顯示日期時間選擇器；當用戶希望手工編輯輸入框中的值是會很有用。

enter

當選擇器處於顯示狀態時，enter鍵只是將其隱藏。當選擇器處於隱藏狀態時，enter鍵發揮通常的功能 - 提交當前表單，或者其他。

I18N國際化

本插件支持月、每周中天的名稱、weekStart選項的國際化。默認是語言是English ('en');其它可以使用的翻譯文件在js/locales/ 目錄中，只需在本插件之后引入需要的語言文件即可。需要增加額外語言支持的話，只需向 $.fn.datetimepicker.dates中增加一個key即可，一定要放在調用 .datetimepicker()之前。如下案例：

$.fn.datetimepicker.dates['en'] = {
    days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
    daysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    daysMin: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"],
    months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
    monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
    today: "Today"
};

Right-to-left languages may also include rtl: true to make the calendar display appropriately.

If your browser (or those of your users) is displaying characters wrong, chances are the browser is loading the javascript file with a non-unicode encoding. Simply add charset="UTF-8" to your script tag:

<script type="text/javascript" src="bootstrap-datetimepicker.de.js" charset="UTF-8"></script>

使用

綁定輸入框，並設置format選項：

<input type="text" value="2012-05-15 21:05" id="datetimepicker">

$('#datetimepicker').datetimepicker({
    format: 'yyyy-mm-dd hh:ii'
});

綁定輸入框，並設置format標記：

<input type="text" value="2012-05-15 21:05" id="datetimepicker" data-date-format="yyyy-mm-dd hh:ii">

$('#datetimepicker').datetimepicker();

作為組件使用：

<div class="input-append date" id="datetimepicker" data-date="12-02-2012" data-date-format="dd-mm-yyyy">
    <input size="16" type="text" value="12-02-2012" readonly>
    <span class="add-on"><i class="icon-th"></i></span>
</div>

$('#datetimepicker').datetimepicker();

作為內聯日期時間選擇器：

<div id="datetimepicker"></div>

$('#datetimepicker').datetimepicker();