Datepicker 轻量级 jQuery 时间选择器插件

Question

一个简单的 jQuery Datepicker 时间日期插件。

Github 地址：https://github.com/fengyuanchen/datepicker

目录结构

dist/
├── datepicker.css
├── datepicker.min.css   (compressed)
├── datepicker.js        (UMD)
├── datepicker.min.js    (UMD, compressed)
├── datepicker.common.js (CommonJS, default)
└── datepicker.esm.js    (ES Module)

开始使用

安装

npm install @chenfengyuan/datepicker

包括档案：

<script src="/path/to/jquery.js"></script><!-- jQuery is required -->
<link  href="/path/to/datepicker.css" rel="stylesheet">
<script src="/path/to/datepicker.js"></script>

使用

用 $.fn.datepicker 方法。

<input data-toggle="datepicker">
<textarea data-toggle="datepicker"></textarea>
<div data-toggle="datepicker"></div>

$('[data-toggle="datepicker"]').datepicker();

可选参数

您可以使用$().datepicker(options)。如果要更改全局默认选项，可以使用$.fn.datepicker.setDefaults(options).

autoShow

• Type: Boolean
• Default: false

Show the datepicker automatically when initialized.

autoHide

• Type: Boolean
• Default: false

Hide the datepicker automatically when picked.

autoPick

• Type: Boolean
• Default: false

Pick the initial date automatically when initialized.

inline

• Type: Boolean
• Default: false

Enable inline mode.

If the element is not an input element, will append the datepicker to the element. If the container option is set, will append the datepicker to the container.

container

• Type: Element or String(selector)
• Default: null

A element for putting the datepicker. If not set, the datepicker will be appended to document.body by default.

Only works when the inline option set to true.

trigger

• Type: Element or String(selector)
• Default: null

A element for triggering the datepicker.

language

• Type: String
• Default: ''

The ISO language code. If not set, will use the built-in language (en-US) by default.

You should define the language first. View the I18n section for more information or check out the i18n folder for available languages.

$().datepicker({
  language: 'en-GB'
});

format

• Type: String
• Default: 'mm/dd/yyyy'
• Available date placeholders:
  • Year: yyyy, yy
  • Month: mm, m
  • Day: dd, d

The date string format.

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

date

• Type: Date or String
• Default: null

The initial date. If not set, will use the current date by default.

$().datepicker({
  date: new Date(2014, 1, 14) // Or '02/14/2014'
});

startDate

• Type: Date or String
• Default: null

The start view date. All the dates before this date will be disabled.

endDate

• Type: Date or String
• Default: null

The end view date. All the dates after this date will be disabled.

startView

• Type: Number
• Default: 0
• Options:
  • 0: days
  • 1: months
  • 2: years

The start view when initialized.

weekStart

• Type: Number
• Default: 0
• Options:
  • 0: Sunday
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday

The start day of the week.

yearFirst

• Type: Boolean
• Default: false

Show year before month on the datepicker header

yearSuffix

• Type: String
• Default: ''

A string suffix to the year number.

$().datepicker({
  yearSuffix: '年'
});

days

• Type: Array
• Default: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']

Days' name of the week.

daysShort

• Type: Array
• Default: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']

Shorter days' name.

daysMin

• Type: Array
• Default: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']

Shortest days' name.

months

• Type: Array
• Default: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

Months' name.

monthsShort

• Type: Array
• Default: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

Shorter months' name.

itemTag

• Type: String
• Default: 'li'

A element tag for each item of years, months and days.

mutedClass

• Type: String
• Default: 'muted'

A class (CSS) for muted item.

pickedClass

• Type: String
• Default: 'picked'

A class (CSS) for picked item.

disabledClass

• Type: String
• Default: 'disabled'

A class (CSS) for disabled item.

highlightedClass

• Type: String
• Default: 'highlighted'

A class (CSS) for highlight date item.

template

• Type: String
• Default:

<div class="datepicker-container">
  <div class="datepicker-panel" data-view="years picker">
    <ul>
      <li data-view="years prev">‹</li>
      <li data-view="years current"></li>
      <li data-view="years next">›</li>
    </ul>
    <ul data-view="years"></ul>
  </div>
  <div class="datepicker-panel" data-view="months picker">
    <ul>
      <li data-view="year prev">‹</li>
      <li data-view="year current"></li>
      <li data-view="year next">›</li>
    </ul>
    <ul data-view="months"></ul>
  </div>
  <div class="datepicker-panel" data-view="days picker">
    <ul>
      <li data-view="month prev">‹</li>
      <li data-view="month current"></li>
      <li data-view="month next">›</li>
    </ul>
    <ul data-view="week"></ul>
    <ul data-view="days"></ul>
  </div>
</div>

The template of the datepicker.

Note: All the data-view attributes must be set when you customize it.

offset

• Type: Number
• Default: 10

The offset top or bottom of the datepicker from the element.

zIndex

• Type: Number
• Default: 1

The CSS z-index style for the datepicker.

filter

• Type: Function
• Default: null
• Syntax: filter(date, view)
  • date: the date for checking.
  • view: the the current view, one of day, month or year.

Filter each date item. If return a false value, the related date will be disabled.

var now = Date.now();

$().datepicker({
  filter: function(date, view) {
    if (date.getDay() === 0 && view === 'day') {
      return false; // Disable all Sundays, but still leave months/years, whose first day is a Sunday, enabled.
    }
  }
});

show

• Type: Function
• Default: null

A shortcut of the "show.datepicker" event.

hide

• Type: Function
• Default: null

A shortcut of the "hide.datepicker" event.

pick

• Type: Function
• Default: null

A shortcut of the "pick.datepicker" event.

方法

Common usage:

$().datepicker('method', argument1, , argument2, ..., argumentN);

show()

Show the datepicker.

hide()

Hide the datepicker.

update()

Update the datepicker with the value or text of the current element.

pick()

Pick the current date to the element.

reset()

Reset the datepicker.

getMonthName([month[, short]])

• month (optional):
  • Type: Number
  • Default: the month of the current date
• short (optional):
  • Type: Boolean
  • Default: false
  • Get the shorter month name
• (return value):
  • Type: String

Get the month name with given argument or the current date.

$().datepicker('getMonthName'); // 'January'
$().datepicker('getMonthName', true); // 'Jan'
$().datepicker('getMonthName', 11); // 'December'
$().datepicker('getMonthName', 11, true); // 'Dec'

getDayName([day[, short[, min]])

• day (optional):
  • Type: Number
  • Default: the day of the current date
• short (optional):
  • Type: Boolean
  • Default: false
  • Get the shorter day name
• min (optional):
  • Type: Boolean
  • Default: false
  • Get the shortest day name
• (return value):
  • Type: String

Get the day name with given argument or the current date.

$().datepicker('getDayName'); // 'Sunday'
$().datepicker('getDayName', true); // 'Sun'
$().datepicker('getDayName', true, true); // 'Su'
$().datepicker('getDayName', 6); // 'Saturday'
$().datepicker('getDayName', 6, true); // 'Sat'
$().datepicker('getDayName', 6, true, true); // 'Sa'

getDate([formatted])

• formatted (optional):
  • Type: Boolean
  • Default: false
  • Get a formatted date string
• (return value):
  • Type: Date or String

Get the current date.

$().datepicker('getDate'); // date object
$().datepicker('getDate', true); // '02/14/2014'

setDate(date)

• date:
  • Type: Date or String

Set the current date with a new date.

$().datepicker('setDate', new Date(2014, 1, 14));
$().datepicker('setDate', '02/14/2014');

setStartDate(date)

• date:
  • Type: Date or String or null

Set the start view date with a new date.

setEndDate(date)

• date:
  • Type: Date or String or null

Set the end view date with a new date.

parseDate(date)

• date:
  • Type: String

Parse a date string with the set date format.

$().datepicker('parseDate', '02/14/2014'); // date object

formatDate(date)

• date:
  • Type: Date

Format a date object to a string with the set date format.

$().datepicker('formatDate', new Date(2014, 1, 14)); // '02/14/2014'

destroy()

Destroy the datepicker and remove the instance from the target element.

事件

show.datepicker

This event fires when starts to show the datepicker.

hide.datepicker

This event fires when starts to hide the datepicker.

pick.datepicker

• event.date:
  • Type: Date
  • The current date
• event.view:
  • Type: String
  • Default: ''
  • Options: 'year', 'month', 'day'
  • The current visible view

This event fires when start to pick a year, month or day.

$().on('pick.datepicker', function (e) {
  if (e.date < new Date()) {
    e.preventDefault(); // Prevent to pick the date
  }
});

I18n 国际化配置

// datepicker.zh-CN.js
$.fn.datepicker.languages['zh-CN'] = {
  format: 'yyyy年mm月dd日',
  days: ['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六'],
  daysShort: ['周日', '周一', '周二', '周三', '周四', '周五', '周六'],
  daysMin: ['日', '一', '二', '三', '四', '五', '六'],
  months: ['一月', '二月', '三月', '四月', '五月', '六月', '七月', '八月', '九月', '十月', '十一月', '十二月'],
  monthsShort: ['1月', '2月', '3月', '4月', '5月', '6月', '7月', '8月', '9月', '10月', '11月', '12月'],
  weekStart: 1,
  startView: 0,
  yearFirst: true,
  yearSuffix: '年'
};

<script src="/path/to/datepicker.js"></script>
<script src="/path/to/datepicker.zh-CN.js"></script>
<script>
  $().datepicker({
    language: 'zh-CN'
  });
</script>

No conflict

If you have to use other plugin with the same namespace, just call the $.fn.datepicker.noConflict method to revert to it.

<script src="other-plugin.js"></script>
<script src="datepicker.js"></script>
<script>
  $.fn.datepicker.noConflict();
  // Code that uses other plugin's "$().datepicker" can follow here.
</script>

浏览器兼容

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)
• Edge (latest)
• Internet Explorer 9+