hjg
2024-07-09 30304784e82d4bba24121328da8eb8490aec4f4f
提交 | 用户 | 时间
58d006 1 # [bootstrap-datepicker](http://eternicode.github.com/bootstrap-datepicker/) [![Build Status](https://travis-ci.org/eternicode/bootstrap-datepicker.png?branch=master)](https://travis-ci.org/eternicode/bootstrap-datepicker)
A 2
3 This is a fork of Stefan Petre's [original code](http://www.eyecon.ro/bootstrap-datepicker/);
4 thanks go to him for getting this thing started!
5
6 Please note that this fork is not used on Stefan's page at this time, nor is it maintained or
7 contributed to by him (yet?)
8
9 Versions are incremented according to [semver](http://semver.org/).
10
11 [Online Demo](http://eternicode.github.com/bootstrap-datepicker/)
12
13 # Requirements
14
15 * [Bootstrap](http://twitter.github.com/bootstrap/) 2.0.4+
16 * [jQuery](http://jquery.com/) 1.7.1+
17
18 These are the specific versions bootstrap-datepicker is tested against (`js` files) and built against (`css` files).  Use other versions at your own risk.
19
20 # Example
21
22 Attached to a field with the format specified via options:
23
24 ```html
25 <input type="text" value="02-16-2012" class="datepicker">
26 ```
27 ```javascript
28 $('.datepicker').datepicker({
29     format: 'mm-dd-yyyy'
30 });
31 ```
32
33 Attached to a field with the format specified via data tag:
34
35 ```html
36 <input type="text" value="02/16/12" data-date-format="mm/dd/yy" class="datepicker" >
37 ```
38 ```javascript
39 $('.datepicker').datepicker();
40 ```
41
42 As component:
43
44 ```html
45 <div class="input-append date datepicker" data-date="12-02-2012" data-date-format="dd-mm-yyyy">
46     <input size="16" type="text" value="12-02-2012" readonly><span class="add-on"><i class="icon-th"></i></span>
47 </div>
48 ```
49 ```javascript
50 $('.datepicker').datepicker();
51 ```
52
53 Attached to non-field element, using events to work with the date values.
54
55 ```html
56 <div class="alert alert-error" id="alert">
57     <strong>Oh snap!</strong>
58 </div>
59 <table class="table">
60     <thead>
61         <tr>
62           <th>
63               Start date
64               <a href="#" class="btn small" id="date-start" data-date-format="yyyy-mm-dd" data-date="2012-02-20">Change</a>
65           </th>
66           <th>
67               End date
68               <a href="#" class="btn small" id="date-end" data-date-format="yyyy-mm-dd" data-date="2012-02-25">Change</a>
69           </th>
70         </tr>
71     </thead>
72     <tbody>
73         <tr>
74           <td id="date-start-display">2012-02-20</td>
75           <td id="date-end-display">2012-02-25</td>
76         </tr>
77     </tbody>
78 </table>
79 ```
80 ```javascript
81 var startDate = new Date(2012,1,20);
82 var endDate = new Date(2012,1,25);
83 $('#date-start')
84     .datepicker()
85     .on('changeDate', function(ev){
86         if (ev.date.valueOf() > endDate.valueOf()){
87             $('#alert').show().find('strong').text('The start date must be before the end date.');
88         } else {
89             $('#alert').hide();
90             startDate = new Date(ev.date);
91             $('#date-start-display').text($('#date-start').data('date'));
92         }
93         $('#date-start').datepicker('hide');
94     });
95 $('#date-end')
96     .datepicker()
97     .on('changeDate', function(ev){
98         if (ev.date.valueOf() < startDate.valueOf()){
99             $('#alert').show().find('strong').text('The end date must be after the start date.');
100         } else {
101             $('#alert').hide();
102             endDate = new Date(ev.date);
103             $('#date-end-display').text($('#date-end').data('date'));
104         }
105         $('#date-end').datepicker('hide');
106     });
107 ```
108
109 As inline datepicker:
110
111 ```html
112 <div class="datepicker"></div>
113 ```
114 ```javascript
115 $('.datepicker').datepicker();
116 ```
117
118
119 # Using bootstrap-datepicker.js
120
121 Call the datepicker via javascript:
122
123 ```javascript
124 $('.datepicker').datepicker()
125 ```
126
127 ## Dependencies
128
129 Requires bootstrap's dropdown component (`dropdowns.less`) for some styles.
130
131 A standalone .css file (including necessary dropdown styles) can be generated by running `build/build_standalone.less` through the `lessc` compiler:
132
133 ```bash
134 $ lessc build/build_standalone.less datepicker.css
135 ```
136
137 ## Data API
138
139 As with bootstrap's own plugins, datepicker provides a data-api that can be used to instantiate datepickers without the need for custom javascript.  For most datepickers, simply set `data-provide="datepicker"` on the element you want to initialize, and it will be intialized lazily, in true bootstrap fashion.  For inline datepickers, this can alternatively be `data-provide="datepicker-inline"`; these will be immediately initialized on page load, and cannot be lazily loaded.
140
141 You can disable datepicker's data-api in the same way as you would disable other bootstrap plugins:
142
143 ```javascript
144 $(document).off('.datepicker.data-api');
145 ```
146
147 ## No Conflict
148
149 ```javascript
150 var datepicker = $.fn.datepicker.noConflict(); // return $.fn.datepicker to previously assigned value
151 $.fn.bootstrapDP = datepicker;                 // give $().bootstrapDP the bootstrap-datepicker functionality
152 ```
153
154 ## Options
155
156 All options that take a "Date" can handle a `Date` object; 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).
157
158 Most options can be provided via data-attributes.  An option can be converted to a data-attribute by taking its name, replacing each uppercase letter with its lowercase equivalent preceded by a dash, and prepending "data-date-" to the result.  For example, `startDate` would be `data-date-start-date`, `format` would be `data-date-format`, and `daysOfWeekDisabled` would be `data-date-days-of-week-disabled`.
159
160 ### format
161
162 String.  Default: 'mm/dd/yyyy'
163
164 The date format, combination of d, dd, D, DD, m, mm, M, MM, yy, yyyy.
165
166 * d, dd: Numeric date, no leading zero and leading zero, respectively.  Eg, 5, 05.
167 * D, DD: Abbreviated and full weekday names, respectively.  Eg, Mon, Monday.
168 * m, mm: Numeric month, no leading zero and leading zero, respectively.  Eg, 7, 07.
169 * M, MM: Abbreviated and full month names, respectively.  Eg, Jan, January
170 * yy, yyyy: 2- and 4-digit years, respectively.  Eg, 12, 2012.
171
172 ### weekStart
173
174 Integer.  Default: 0
175
176 Day of the week start. 0 (Sunday) to 6 (Saturday)
177
178 ### calendarWeeks
179
180 Boolean. Default: false
181
182 Whether or not to show week numbers to the left of week rows.
183
184 ### startDate
185
186 Date.  Default: Beginning of time
187
188 The earliest date that may be selected; all earlier dates will be disabled.
189
190 ### endDate
191
192 Date.  Default: End of time
193
194 The latest date that may be selected; all later dates will be disabled.
195
196 ### daysOfWeekDisabled
197
198 String, Array.  Default: '', []
199
200 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]`.
201
202 ### autoclose
203
204 Boolean.  Default: false
205
206 Whether or not to close the datepicker immediately when a date is selected.
207
208 ### startView
209
210 Number, String.  Default: 0, 'month'
211
212 The view that the datepicker should show when it is opened.  Accepts values of 0 or 'month' for month view (the default), 1 or 'year' for the 12-month overview, and 2 or 'decade' for the 10-year overview.  Useful for date-of-birth datepickers.
213
214 ### minViewMode
215
216 Number, String.  Default: 0, 'days'
217
218 Set a limit for the view mode.  Accepts: 'days' or 0, 'months' or 1, and 'years' or 2.
219 Gives the ability to pick only a month or an year.  The day is set to the 1st for 'months', and the month is set to January for 'years'.
220
221 ### todayBtn
222
223 Boolean, "linked".  Default: false
224
225 If true or "linked", displays a "Today" button at the bottom of the datepicker to select the current date.  If true, the "Today" button will only move the current date into view; if "linked", the current date will also be selected.
226
227 ### todayHighlight
228
229 Boolean.  Default: false
230
231 If true, highlights the current date.
232
233 ### clearBtn
234
235 Boolean.  Default: false
236
237 If true, displays a "Clear" button at the bottom of the datepicker to clear the input value. If "autoclose" is also set to true, this button will also close the datepicker.
238
239 ### keyboardNavigation
240
241 Boolean.  Default: true
242
243 Whether or not to allow date navigation by arrow keys.
244
245 ### language
246
247 String.  Default: 'en'
248
249 The IETF code (eg  "en" for English, "pt-BR" for Brazilian Portuguese) 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).  If a full code (eg "de-DE") is supplied the picker will first check for an "de-DE" language and if not found will fallback and check for a "de" language.  If an unknown language code is given, English will be used.  See I18N below.
250
251 ### forceParse
252
253 Boolean.  Default: true
254
255 Whether or not to force parsing of the input value when the picker is closed.  That is, when an invalid date is left in the input field by the user, the picker will forcibly parse that value, and set the input's value to the new, valid date, conforming to the given `format`.
256
257 ### inputs
258
259 Array.  Default: None
260
261 A list of inputs to be used in a range picker, which will be attached to the selected element.  Allows for explicitly creating a range picker on a non-standard element.
262
263 ### beforeShowDay
264
265 Function(Date).  Default: $.noop
266
267 A function that takes a date as a parameter and returns one of the following values:
268
269  * undefined to have no effect
270  * A Boolean, indicating whether or not this date is selectable
271  * A String representing additional CSS classes to apply to the date's cell
272  * An object with the following properties:
273    * `enabled`: same as the Boolean value above
274    * `classes`: same as the String value above
275    * `tooltip`: a tooltip to apply to this date, via the `title` HTML attribute
276
277 ### orientation
278
279 String.  Default: "auto"
280
281 A space-separated string consisting of one or two of "left" or "right", "top" or "bottom", and "auto" (may be omitted); for example, "top left", "bottom" (horizontal orientation will default to "auto"), "right" (vertical orientation will default to "auto"), "auto top".  Allows for fixed placement of the picker popup.
282
283 "orientation" refers to the location of the picker popup's "anchor"; you can also think of it as the location of the trigger element (input, component, etc) relative to the picker.
284
285 "auto" triggers "smart orientation" of the picker.  Horizontal orientation will default to "left" and left offset will be tweaked to keep the picker inside the browser viewport; vertical orientation will simply choose "top" or "bottom", whichever will show more of the picker in the viewport.
286
287 ## Markup
288
289 Format a component.
290
291 ```html
292 <div class="input-append date datepicker" data-date="12-02-2012" data-date-format="dd-mm-yyyy">
293     <input class="span2" size="16" type="text" value="12-02-2012"><span class="add-on"><i class="icon-th"></i></span>
294 </div>
295 ```
296
297 Create a date-range picker:
298
299 ```html
300 <div class="input-daterange" id="datepicker">
301     <input class="input-small" name="start" value="2012-04-05" />
302     <span class="add-on">to</span>
303     <input class="input-small" name="end" value="2012-04-07" />
304 </div>
305 ```
306
307 ## Methods
308
309 ### .datepicker(options)
310
311 Initializes an datepicker.
312
313 ### remove
314
315 Arguments: None
316
317 Remove the datepicker.  Removes attached events, internal attached objects, and
318 added HTML elements.
319
320 ```javascript
321 $('.datepicker').datepicker('remove');
322 ```
323
324 ### show
325
326 Arguments: None
327
328 Show the datepicker.
329
330 ```javascript
331 $('.datepicker').datepicker('show');
332 ```
333
334 ### hide
335
336 Arguments: None
337
338 Hide the datepicker.
339
340 ```javascript
341 $('.datepicker').datepicker('hide');
342 ```
343
344 ### update
345
346 Arguments:
347
348 * date (String|Date)
349
350 Update the datepicker with given argument or the current input value.
351
352 If `date` is provided and is a Date objects, it is assumed to be a "local" date object, and will be converted to UTC for internal use.
353
354 ```javascript
355 $('.datepicker').datepicker('update');
356 $('.datepicker').datepicker('update', '2011-03-05');
357 $('.datepicker').datepicker('update', new Date(2011, 2, 5));
358 ```
359
360 ### setDate
361
362 Arguments:
363
364 * date (Date)
365
366 Sets the internal date.  `date` is assumed to be a "local" date object, and will be converted to UTC for internal use.
367
368 ### setUTCDate
369
370 Arguments:
371
372 * date (Date)
373
374 Sets the internal date.  `date` is assumed to be a UTC date object, and will not be converted.
375
376 ### getDate
377
378 Arguments: None
379
380 Returns a localized date object representing the internal date object of the first datepicker in the selection.
381
382 ### setUTCDate
383
384 Arguments: None
385
386 Returns the internal UTC date object, as-is and unconverted to local time, of the first datepicker in the selection.
387
388 ### setStartDate
389
390 Arguments:
391
392 * startDate (Date)
393
394 Sets a new lower date limit on the datepicker.
395
396 ```javascript
397 $('.datepicker').datepicker('setStartDate', '2012-01-01');
398 ```
399
400 Omit startDate (or provide an otherwise falsey value) to unset the limit.
401
402 ```javascript
403 $('.datepicker').datepicker('setStartDate');
404 $('.datepicker').datepicker('setStartDate', null);
405 ```
406
407 ### setEndDate
408
409 Arguments:
410
411 * endDate (Date)
412
413 Sets a new upper date limit on the datepicker.
414
415 ```javascript
416 $('.datepicker').datepicker('setEndDate', '2012-12-31');
417 ```
418
419 Omit endDate (or provide an otherwise falsey value) to unset the limit.
420
421 ```javascript
422 $('.datepicker').datepicker('setEndDate');
423 $('.datepicker').datepicker('setEndDate', null);
424 ```
425
426 ### setDaysOfWeekDisabled
427
428 Arguments:
429
430 * daysOfWeekDisabled (String|Array)
431
432 Sets the days of week that should be disabled.
433
434 ```javascript
435 $('.datepicker').datepicker('setDaysOfWeekDisabled', [0,6]);
436 ```
437
438 Omit daysOfWeekDisabled (or provide an otherwise falsey value) to unset the disabled days.
439
440 ```javascript
441 $('.datepicker').datepicker('setDaysOfWeekDisabled');
442 $('.datepicker').datepicker('setDaysOfWeekDisabled', null);
443 ```
444
445 ## Events
446
447 Datepicker triggers a number of events in certain circumstances.  All events have extra data attached to the event object that is passed to any event handlers:
448
449 ```javascript
450 $('.datepicker').datepicker()
451     .on(picker_event, function(e){
452         # `e` here contains the extra attributes
453     });
454 ```
455
456 * `date`: the relevant Date object, in local timezone.
457 * `format([format])`: a function to make formatting `date` easier.  `format` can be any format string that datepicker supports.  If `format` is not given, the format set on the datepicker will be used.
458
459 ### show
460
461 Fired when the date picker is displayed.
462
463 ### hide
464
465 Fired when the date picker is hidden.
466
467 ### clearDate
468
469 Fired when the date is cleared, normally when the "clear" button (enabled with the `clearBtn` option) is pressed.
470
471 ### changeDate
472
473 Fired when the date is changed.
474
475 ### changeYear
476
477 Fired when the *view* year is changed from decade view.
478
479 ### changeMonth
480
481 Fired when the *view* month is changed from year view.
482
483 ## Keyboard support
484
485 The datepicker includes some keyboard navigation:
486
487 ### up, down, left, right arrow keys
488
489 By themselves, left/right will move backward/forward one day, up/down will move back/forward one week.
490
491 With the shift key, up/left will move backward one month, down/right will move forward one month.
492
493 With the ctrl key, up/left will move backward one year, down/right will move forward oone year.
494
495 Shift+ctrl behaves the same as ctrl -- that is, it does not change both month and year simultaneously, only the year.
496
497 ### escape
498
499 The escape key can be used to hide and re-show the datepicker; this is necessary if the user wants to manually edit the value.
500
501 ### enter
502
503 When the picker is visible, enter will simply hide it.  When the picker is not visible, enter will have normal effects -- submitting the current form, etc.
504
505 ## I18N
506
507 The plugin supports i18n for the month and weekday names and the `weekStart` option.  The default is English ('en'); other available translations are avilable in the `js/locales/` directory, simply include your desired locale after the plugin.  To add more languages, simply add a key to `$.fn.datepicker.dates`, before calling `.datepicker()`.  Example:
508
509 ```javascript
510 $.fn.datepicker.dates['en'] = {
511     days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
512     daysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
513     daysMin: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"],
514     months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
515     monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
516     today: "Today"
517 };
518 ```
519
520 Right-to-left languages may also include `rtl: true` to make the calendar display appropriately.
521
522 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:
523
524 ```html
525 <script type="text/javascript" src="bootstrap-datepicker.XX.js" charset="UTF-8"></script>
526 ```
527
528 ```javascript
529 $('.datepicker').datepicker({
530     language: XX    //as you defined in bootstrap-datepicker.XX.js
531 });
532 ```