解决90%日期选择难题：bootstrap-datepicker完全指南
项目地址: https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker 你是否还在为Web项目中的日期选择功能头疼？从格式验证到跨浏览器兼容性，从多语言支持到日期范围限制，这些问题耗费了开发者大量时间。本文将系统讲解bootstrap-datepicker的核心功能与高级用法，帮助你在30分钟内构建专业级日期选择组件。
读完本文你将掌握：
- 5种基础初始化方式与国内CDN配置
- 18个核心选项的实战配置（含代码示例）
- 日期范围选择与多日期选择实现方案
- 8个常用事件处理与回调函数应用
- 多语言本地化与自定义样式技巧
- 性能优化与常见问题解决方案
快速上手：5分钟集成日期选择器
bootstrap-datepicker是一款基于jQuery的轻量级日期选择插件，专为Bootstrap框架设计，压缩后仅20KB，支持IE8+及所有现代浏览器。
基础环境配置
使用国内CDN加速资源加载，确保在稳定网络环境下的稳定性：
<!-- 引入依赖 -->
<link href="https://cdn.bootcdn.net/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.bootcdn.net/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="https://cdn.bootcdn.net/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js"></script>
<!-- 引入日期选择器 -->
<link href="https://cdn.bootcdn.net/ajax/libs/bootstrap-datepicker/1.9.0/css/bootstrap-datepicker.min.css" rel="stylesheet">
<script src="https://cdn.bootcdn.net/ajax/libs/bootstrap-datepicker/1.9.0/js/bootstrap-datepicker.min.js"></script>
<!-- 中文语言包 -->
<script src="https://cdn.bootcdn.net/ajax/libs/bootstrap-datepicker/1.9.0/locales/bootstrap-datepicker.zh-CN.min.js"></script>
五种初始化方式
根据不同场景需求，选择最合适的初始化方式：
1. 输入框模式（最常用）
<input type="text" class="form-control" id="datepicker">
<script>
$('#datepicker').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
autoclose: true
});
</script>
2. 组件模式（带图标触发）
<div class="input-group date" id="datepicker-component">
<input type="text" class="form-control">
<span class="input-group-addon">
<span class="glyphicon glyphicon-calendar"></span>
</span>
</div>
<script>
$('#datepicker-component').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
</script>
3. 内联模式（始终显示）
<div id="datepicker-inline"></div>
<script>
$('#datepicker-inline').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
todayHighlight: true
});
</script>
4. 日期范围选择
<div class="input-daterange input-group" id="datepicker-range">
<input type="text" class="input form-control" name="start">
<span class="input-group-addon">至</span>
<input type="text" class="input form-control" name="end">
</div>
<script>
$('#datepicker-range').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
</script>
5. 数据属性初始化（无需JavaScript）
<input type="text" class="form-control"
data-date-format="yyyy-mm-dd"
data-date-language="zh-CN"
data-date-autoclose="true">
核心选项配置详解
bootstrap-datepicker提供了丰富的配置选项，满足各种业务需求。以下是18个最常用选项的详细说明和代码示例：
日期格式设置（format）
支持多种日期格式组合，满足不同地区和业务需求：
// 常用格式配置
$('#datepicker').datepicker({
format: 'yyyy-mm-dd', // 2023-10-25
// format: 'yyyy年mm月dd日', // 2023年10月25日
// format: 'dd/mm/yyyy', // 25/10/2023
// format: 'yyyy-mm', // 仅年月选择
language: 'zh-CN'
});
// 自定义格式化函数（高级用法）
$('#datepicker').datepicker({
format: {
toDisplay: function(date, format, language) {
var d = new Date(date);
return d.getFullYear() + '年' + (d.getMonth()+1) + '月' + d.getDate() + '日';
},
toValue: function(dateStr, format, language) {
var parts = dateStr.split('年');
var year = parseInt(parts[0]);
var month = parseInt(parts[1].split('月')[0]) - 1;
var day = parseInt(parts[1].split('月')[1].split('日')[0]);
return new Date(year, month, day);
}
},
language: 'zh-CN'
});
日期范围限制（startDate/endDate）
限制可选日期范围，支持相对日期和绝对日期：
// 绝对日期限制
$('#datepicker').datepicker({
startDate: '2023-01-01', // 开始日期
endDate: '2023-12-31', // 结束日期
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
// 相对日期限制（推荐）
$('#datepicker').datepicker({
startDate: '-30d', // 30天前
endDate: '+30d', // 30天后
// startDate: '0d', // 今天开始
// endDate: 'today', // 今天结束
// startDate: 'yesterday', // 昨天开始
// endDate: 'tomorrow', // 明天结束
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
多日期选择（multidate）
允许用户选择多个日期，支持数量限制：
// 无限制多选
$('#datepicker').datepicker({
multidate: true, // 启用多日期选择
multidateSeparator: ', ', // 日期分隔符
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
// 限制最多选择3个日期
$('#datepicker').datepicker({
multidate: 3, // 最多选择3个日期
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
周起始日设置（weekStart）
自定义周起始日，支持从周日（0）到周六（6）：
// 设置周一为周起始日（中国习惯）
$('#datepicker').datepicker({
weekStart: 1, // 1=周一，0=周日（默认）
calendarWeeks: true, // 显示周数
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
特殊日期处理
禁用特定日期（datesDisabled）
$('#datepicker').datepicker({
datesDisabled: ['2023-10-01', '2023-10-02', '2023-10-03'], // 禁用特定日期
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
禁用特定星期几（daysOfWeekDisabled）
// 禁用周末（周六和周日）
$('#datepicker').datepicker({
daysOfWeekDisabled: [0, 6], // 0=周日，6=周六
// daysOfWeekDisabled: '0,6', // 字符串格式也支持
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
显示增强选项
$('#datepicker').datepicker({
todayBtn: true, // 显示"今天"按钮
todayHighlight: true, // 高亮今天
clearBtn: true, // 显示"清除"按钮
calendarWeeks: true, // 显示周数
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
视图模式控制
控制日期选择器的初始视图和可切换的视图级别：
// 初始显示月视图，只能选择到月份
$('#datepicker').datepicker({
startView: 1, // 0=日视图，1=月视图，2=年视图
minViewMode: 1, // 最小视图模式（1=月视图，不能再往下到日）
format: 'yyyy-mm', // 只显示年月
language: 'zh-CN'
});
// 初始显示年视图，只能选择到年份
$('#datepicker').datepicker({
startView: 2, // 初始显示年视图
minViewMode: 2, // 最小视图模式为年
format: 'yyyy', // 只显示年份
language: 'zh-CN'
});
事件处理与回调函数
bootstrap-datepicker提供了丰富的事件接口，用于处理用户交互：
常用事件示例
$('#datepicker').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN'
})
.on('changeDate', function(e) {
// 日期改变事件（选择日期时触发）
console.log('选择的日期: ' + e.format());
console.log('原始Date对象: ' + e.date);
})
.on('show', function(e) {
// 日期选择器显示时触发
console.log('日期选择器已显示');
})
.on('hide', function(e) {
// 日期选择器隐藏时触发
console.log('日期选择器已隐藏');
})
.on('clearDate', function(e) {
// 清除日期时触发
console.log('日期已清除');
})
.on('changeMonth', function(e) {
// 月份改变时触发
console.log('月份改变: ' + (e.date.getMonth() + 1) + '月');
})
.on('changeYear', function(e) {
// 年份改变时触发
console.log('年份改变: ' + e.date.getFullYear() + '年');
});
日期验证回调（beforeShowDay）
自定义日期是否可选，并可添加样式和提示：
// 自定义可选日期逻辑
$('#datepicker').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
beforeShowDay: function(date) {
// 禁用所有偶数日期
if (date.getDate() % 2 === 0) {
return {
enabled: false, // 禁用日期
classes: 'even-day', // 添加自定义CSS类
tooltip: '偶数日期不可选' // 提示文本
};
}
// 高亮显示10号
if (date.getDate() === 10) {
return {
enabled: true,
classes: 'highlight-day',
tooltip: '这是10号'
};
}
return true; // 其他日期正常显示
}
});
高级应用场景
日期范围选择器（带联动效果）
实现开始日期和结束日期的联动限制：
<div class="input-group input-daterange">
<input type="text" class="form-control" id="startDate" placeholder="开始日期">
<span class="input-group-addon">至</span>
<input type="text" class="form-control" id="endDate" placeholder="结束日期">
</div>
<script>
// 初始化开始日期选择器
$('#startDate').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
todayHighlight: true,
autoclose: true
}).on('changeDate', function(e) {
// 开始日期改变时，更新结束日期的最小日期
$('#endDate').datepicker('setStartDate', e.date);
});
// 初始化结束日期选择器
$('#endDate').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
todayHighlight: true,
autoclose: true
}).on('changeDate', function(e) {
// 结束日期改变时，更新开始日期的最大日期
$('#startDate').datepicker('setEndDate', e.date);
});
</script>
内联日期选择器（日历组件）
创建一个始终显示的内联日历，适合酒店预订等场景：
<div id="inlineCalendar"></div>
<div id="selectedDates"></div>
<script>
$('#inlineCalendar').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
inline: true, // 内联显示
multidate: true, // 允许多选
todayHighlight: true,
calendarWeeks: true,
weekStart: 1
}).on('changeDate', function(e) {
// 显示选中的日期
var dates = e.dates.map(function(date) {
return date.getFullYear() + '-' +
(date.getMonth() + 1).toString().padStart(2, '0') + '-' +
date.getDate().toString().padStart(2, '0');
});
$('#selectedDates').html('已选择: ' + dates.join(', '));
});
</script>
多语言支持与本地化
bootstrap-datepicker内置多种语言支持，轻松实现国际化：
// 中文（默认）
$('#datepicker').datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN' // 中文
});
// 英文
$('#datepicker-en').datepicker({
format: 'mm/dd/yyyy',
language: 'en' // 英文
});
// 日文
$('#datepicker-ja').datepicker({
format: 'yyyy/mm/dd',
language: 'ja' // 日文
});
// 自定义语言（扩展）
$.fn.datepicker.dates['custom'] = {
days: ["星期日", "星期一", "星期二", "星期三", "星期四", "星期五", "星期六"],
daysShort: ["日", "一", "二", "三", "四", "五", "六"],
daysMin: ["日", "一", "二", "三", "四", "五", "六"],
months: ["一月", "二月", "三月", "四月", "五月", "六月", "七月", "八月", "九月", "十月", "十一月", "十二月"],
monthsShort: ["一", "二", "三", "四", "五", "六", "七", "八", "九", "十", "十一", "十二"],
today: "今天",
clear: "清除",
format: "yyyy-mm-dd",
titleFormat: "yyyy年MM月",
weekStart: 1
};
// 使用自定义语言
$('#datepicker-custom').datepicker({
language: 'custom',
format: 'yyyy-mm-dd'
});
方法与API
bootstrap-datepicker提供了丰富的方法，用于通过代码控制日期选择器：
常用方法示例
// 设置日期
$('#datepicker').datepicker('setDate', '2023-10-25');
// 获取当前选择的日期
var selectedDate = $('#datepicker').datepicker('getDate');
console.log(selectedDate); // Date对象
// 获取格式化的日期字符串
var formattedDate = $('#datepicker').datepicker('getFormattedDate');
console.log(formattedDate); // "2023-10-25"
// 设置日期范围
$('#datepicker').datepicker('setStartDate', '2023-10-01');
$('#datepicker').datepicker('setEndDate', '2023-10-31');
// 清除日期
$('#datepicker').datepicker('clearDates');
// 显示/隐藏日期选择器
$('#datepicker').datepicker('show');
$('#datepicker').datepicker('hide');
// 销毁日期选择器
$('#datepicker').datepicker('destroy');
样式自定义
通过CSS自定义日期选择器的外观：
/* 自定义日期选择器样式 */
.datepicker {
border: 1px solid #ddd;
border-radius: 4px;
}
/* 自定义头部样式 */
.datepicker thead tr:first-child th {
background-color: #337ab7;
color: white;
border-radius: 0;
}
/* 自定义选中日期样式 */
.datepicker table tr td.active {
background-color: #5cb85c;
border-color: #4cae4c;
}
/* 自定义今天日期样式 */
.datepicker table tr td.today {
background-color: #f0ad4e;
color: white;
}
/* 自定义禁用日期样式 */
.datepicker table tr td.disabled {
background-color: #f9f9f9;
color: #ccc;
cursor: not-allowed;
}
/* 自定义高亮日期样式 */
.datepicker table tr td.highlight-day {
background-color: #d9edf7;
color: #31708f;
}
性能优化与常见问题
性能优化建议
- 延迟初始化：对于不在首屏的日期选择器，使用滚动监听延迟初始化
// 延迟初始化示例
$(window).scroll(function() {
var datepicker = $('#delayedDatepicker');
if (datepicker.length && isElementInViewport(datepicker[0])) {
datepicker.datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
$(window).off('scroll', arguments.callee);
}
});
// 判断元素是否在视口中
function isElementInViewport(el) {
var rect = el.getBoundingClientRect();
return (
rect.top >= 0 &&
rect.left >= 0 &&
rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) &&
rect.right <= (window.innerWidth || document.documentElement.clientWidth)
);
}
- 事件委托：对于动态生成的元素，使用事件委托初始化
// 事件委托方式初始化
$(document).on('focus', '.dynamic-datepicker', function() {
$(this).datepicker({
format: 'yyyy-mm-dd',
language: 'zh-CN',
autoclose: true
}).focus();
});
常见问题解决方案
问题1：日期选择器显示位置不正确
// 解决方案：指定容器或调整定位
$('#datepicker').datepicker({
container: '#parentContainer', // 将日期选择器附加到指定容器
orientation: 'bottom auto', // 强制底部对齐
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
问题2：在模态框中无法正常显示
// 解决方案：将日期选择器附加到模态框内
$('#datepicker').datepicker({
container: '#myModal', // 附加到模态框
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
// 或者使用z-index调整
.datepicker {
z-index: 2050 !important; // 确保高于模态框的z-index(通常是1050)
}
问题3：输入框手动输入日期不生效
// 解决方案：启用强制解析
$('#datepicker').datepicker({
forceParse: true, // 强制解析输入值
format: 'yyyy-mm-dd',
language: 'zh-CN'
});
// 或者手动触发更新
$('#datepicker').on('change', function() {
$(this).datepicker('update'); // 手动触发更新
});
总结与资源
bootstrap-datepicker作为一款轻量级且功能丰富的日期选择插件，通过灵活的配置选项和丰富的API，能够满足大多数Web项目的日期选择需求。无论是简单的单日期选择，还是复杂的日期范围限制、多日期选择，都能通过本文介绍的方法轻松实现。
学习资源
- 官方仓库：https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker
- 完整文档：项目内docs目录包含详细文档
- 示例代码：项目tests目录包含各种使用示例
最佳实践清单
- ✅ 始终使用国内CDN加速资源加载
- ✅ 根据业务需求合理配置日期格式和范围
- ✅ 使用事件回调处理日期选择后的逻辑
- ✅ 对特殊日期场景使用beforeShowDay自定义
- ✅ 注意在模态框中使用时的容器设置
- ✅ 移动端考虑禁用触摸键盘提升体验
掌握这些技能后，你将能够构建出既美观又实用的日期选择功能，为用户提供流畅的交互体验。如有任何问题，欢迎在评论区留言讨论！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
