bootstrap-datepicker 配置选项完全指南：从默认值到源码级实现

• 前端
• UI组件

bootstrap-datepicker 是一个基于 Twitter Bootstrap 风格、依赖 jQuery 的日期选择组件。本文以仓库内 docs/options.rst 为骨架，系统讲解该插件的全部配置选项——从三种配置方式、日期参数的统一约定，到每个选项的类型、默认值与真实行为，并结合 js/bootstrap-datepicker.js 中的默认值定义、选项解析流程（_process_options）与 tests/suites/options.js 中的单元测试逐一印证。读完本文，你将能独立配置出贴合业务场景的日期选择器，并理解这些选项在底层是如何被解析和生效的。

选项的三种配置方式与优先级

bootstrap-datepicker 的配置入口有三种：实例化时的 JavaScript 选项哈希、目标元素上的 data 属性，以及全局默认值哈希。

// 方式一：JS 选项哈希（优先级最高） $('.datepicker').datepicker({ format: 'mm/dd/yyyy', startDate: '-3d' });

<!-- 方式二：data 属性 --> <input class="datepicker">// 方式三：修改全局默认值（对所有实例生效） $.fn.datepicker.defaults.format = "mm/dd/yyyy";

从源码 js/bootstrap-datepicker.js 可以看到，实例化时选项的合并顺序是：

// Options priority: js args,>if (this.o.autoclose && (!which || which === 'date')){ this.hide(); }

即仅在选择了日期（而非仅切换视图）时触发关闭。对应测试见 tests/suites/options.js：autoclose: true时点击某个日期后，断言面板is(':not(:visible)')。

multidate 与 multidateSeparator

• multidate：Boolean 或 Number；默认值：false。开启后月视图中每个日期变为「切换按钮」，按顺序记录用户选中的日期；传入数字时限制可选数量，超出后从最旧日期开始丢弃；true表示不限制。输入框的值由所有选中日期按format格式化后，用multidateSeparator拼接而成。如需用多选实现「选两个日期作为范围」，见 docs/markup.rst 中的 daterange 部分。
• multidateSeparator：String；默认值：','。拼接/拆分多选日期字符串的分隔符。解析输入值时同样用它拆分字符串，因此强烈建议不要使用可能成为日期格式子串的字符做分隔符（例如format为'yyyy-mm-dd'时不应使用'-'）。

源码中multidate会被归一化（js/bootstrap-datepicker.js）：

if (o.multidate !== true){ o.multidate = Number(o.multidate) || false; if (o.multidate !== false) o.multidate = Math.max(0, o.multidate); } o.multidateSeparator = String(o.multidateSeparator);

多选的核心逻辑在_toggle_multidate（js/bootstrap-datepicker.js）：命中已选中日期则移除（相当于切换），否则追加，并依据数量上限丢弃最旧的。

toggleActive

• 类型：Boolean；默认值：false。
• 作用：为true时，再次点击当前已选中的日期会取消该日期。当multidate开启时此行为强制为true（见_toggle_multidate中的this.o.multidate === true || this.o.multidate > 1 || this.o.toggleActive判断，js/bootstrap-datepicker.js）。

immediateUpdates

• 类型：Boolean；默认值：false。
• 作用：为true时，在年月视图中选择年份或月份也会立即更新输入框的值；否则只有选择具体某一天才会立即更新输入框。

forceParse

• 类型：Boolean；默认值：true。
• 作用：为true时，面板关闭时会强制解析输入框中的内容：如果用户留下了一个无法按format解析的非法日期，插件会尝试重新解析并回写为符合格式的有效值；设为false则保留用户输入的原始文本。

日期范围与可用性限制

startDate / endDate

• startDate：Date 或 String；默认值：-Infinity（时间起点）。可选的最早日期，更早的日期全部禁用。
• endDate：Date 或 String；默认值：Infinity（时间终点）。可选的最晚日期，更晚的日期全部禁用。

两者均可直接用 data 属性配置，例如「禁用今天之后的所有日期」：

<input type="text" class="form-control" />
datesDisabled
类型：String 或 Array；默认值：[]。
作用：按给定format格式化的一组日期字符串（或单个字符串），这些日期将被禁用。
源码处理（js/bootstrap-datepicker.js）：非数组时先按逗号split成数组，再逐项parseDate：
o.datesDisabled = o.datesDisabled||[]; if (!Array.isArray(o.datesDisabled)) { o.datesDisabled = o.datesDisabled.split(','); } o.datesDisabled = $.map(o.datesDisabled, function(d){ return DPGlobal.parseDate(d, format, o.language, o.assumeNearbyYear); });
daysOfWeekDisabled / daysOfWeekHighlighted
类型：String 或 Array；默认值：[]。
daysOfWeekDisabled：禁用的星期几，取值 0（周日）到 6（周六），多个值用逗号分隔。例如禁用周末：'06'、'0,6'或[0,6]均可。
daysOfWeekHighlighted：需要高亮的星期几，取值规则与上相同。例如高亮周末：'06'、'0,6'或[0,6]。
两者的解析共用_resolveDaysOfWeek（js/bootstrap-datepicker.js）：非数组时按/[,\s]*/（逗号或空白）拆分，再逐个Number()转换为数值。
视图级回调：beforeShowDay / beforeShowMonth / beforeShowYear / beforeShowDecade / beforeShowCentury
这五个回调的类型均为Function(Date)，默认值均为$.noop（空操作，见默认值定义 js/bootstrap-datepicker.js）。它们分别在日、月、年、十年、世纪视图渲染时被调用，入参为对应的Date，返回值支持以下四种：
undefined：不做任何处理；
Boolean：该日期/月份/年份是否可选；
String：附加到对应单元格上的额外 CSS 类名；
对象，可含以下键：
enabled：同 Boolean 语义；
classes：同 String 语义；
tooltip：通过titleHTML 属性附加到该日期的提示文本（beforeShowDay等均支持；其中beforeShowDay还多一个content键）；
content：仅beforeShowDay支持，用于替换单元格默认内容（默认是日期数字文本）的 HTML 内容。
以beforeShowDay为例，源码在月视图逐日渲染时调用（js/bootstrap-datepicker.js），并把返回的enabled、classes、tooltip、content组合进<td>的 class 与title属性（js/bootstrap-datepicker.js）。
视图模式与初始视角
bootstrap-datepicker 的界面分为五个视图层级，数字与名称均可作为视图标识，由_resolveViewName（js/bootstrap-datepicker.js）统一解析：
数值
名称
视图内容
0
days/month
月（日）视图
1
months/year
年（月）视图
2
years/decade
十年（年）视图
3
decades/century
世纪（十年）视图
4
centuries/millennium
千年（世纪）视图
startView
类型：Number 或 String；默认值：0（"days"，即当月）。
作用：面板打开时展示的初始视图。对「出生日期」这类只要求年份/月份的选择场景很实用。
minViewMode / maxViewMode
minViewMode：Number 或 String；默认值：0（"days"）。允许的最细粒度视图。
maxViewMode：Number 或 String；默认值：4（"centuries"）。允许的最大（最粗）视图。
两者共同约束可停留的视图范围：minViewMode设得越高，用户越早停止下钻（例如设为1后只能选到月，选月时日期自动置为当月 1 日）；maxViewMode设得越低，翻页最多能到的层级越浅。源码中startView还会被夹在 min/max 之间（js/bootstrap-datepicker.js）：
o.startView = Math.max(this.o.minViewMode, Math.min(this.o.maxViewMode, o.startView));
选中年月时日期值的截断规则：选「月」时日期置为 1 日；选「年」时月份置为 1 月；选「十年」时年份置为该十年的第一年；选「世纪」时年份置为该千年的第一年。
defaultViewDate
类型：Date、String 或含year/month/day键的对象；默认值：今天。
作用：面板首次打开时定位到的日期。内部值（已选日期）默认仍是今天，但视图会先落到defaultViewDate而不是今天。
取值规则（源码见 js/bootstrap-datepicker.js）：
Date：应为本地时区；
String：必须能按format解析；
对象：键缺省时的默认值——year取当前年份、month取0（注意 1 月是0）、day取1。对象形式无法通过 data 属性设置。
updateViewDate
类型：Boolean；默认值：true。
作用：为false时，viewDate只在初始化时按value设定，之后仅在以下情况更新：选中了上/下月的某一天，或通过setDate、setDates、setUTCDate、setUTCDates方法修改了日期。当multidate为true时，使用最后选中的日期（或传入setDates/setUTCDates的数组中的最后一项）作为视图日期。相关方法见 docs/methods.rst。
assumeNearbyYear
类型：Boolean 或 Integer；默认值：false。
作用：控制手工输入两位数年份时的解析规则。为true时，'5/1/15'会解析为 2015 年而不是公元 15 年：如果年份在未来 10 年以内，使用当前世纪，否则使用上一世纪。因此'5/1/15'→ 2015-05-01，而'5/1/97'→ 1997-05-01。
进阶用法：传入整数可自定义「未来多少年内仍视为当前世纪」的阈值，例如assumeNearbyYear: 20。该选项会作为parseDate的最后一个参数，影响所有日期字符串的解析（见前文「所有接受日期的选项」一节）。
weekStart 与 calendarWeeks
weekStart：Integer；默认值：0（周日）。一周从星期几开始，取值 0（周日）到 6（周六）。源码中会取模并同时推导出weekEnd：o.weekStart %= 7; o.weekEnd = (o.weekStart + 6) % 7;（js/bootstrap-datepicker.js）。由于weekStart属于locale_opts，它也可以由语言包提供。
calendarWeeks：Boolean；默认值：false。为true时在每行日期左侧显示周数。
外观、定位与容器
orientation
类型：String；默认值："auto"。
作用：用空格分隔的一到两个方位词控制面板的固定位置，可组合"left"/"right"、"top"/"bottom"与"auto"（可省略）。例如"top left"、"bottom"（水平方向自动）、"right"（垂直方向自动）、"auto top"。
语义：orientation描述的是面板「锚点」的位置，也可以理解为触发元素（输入框/组件）相对于面板的位置。
"auto"的智能定位：水平方向默认"left"并微调左偏移以保证面板不超出浏览器视口；垂直方向则在"top"/"bottom"中选择能在视口中展示更多内容的一方。
源码在_process_options中对字符串做了严格的词法过滤——只接受auto|left|right|top|bottom，其余单词被丢弃，随后拆解为{x, y}两个方向（js/bootstrap-datepicker.js）。
container
类型：String（选择器）；默认值："body"。
作用：把日期面板挂载到指定元素下，例如container: '#picker-container'。默认挂到body。适合面板需要被包裹在特定容器（如被裁剪的弹层）内的场景。
zIndexOffset
类型：Integer；默认值：10。
作用：面板的 CSSz-index取「输入框及其所有 DOM 祖先的最大 z-index」加上zIndexOffset。默认10通常足以让面板盖过多数元素；当页面存在更高层级的浮层时，可相应调大。
showWeekDays
类型：Boolean；默认值：true。
作用：为false时不渲染表头的星期名称行；默认渲染星期名称。
title
类型：String；默认值：""。
作用：显示在面板顶部的标题文字；为空字符串时标题被隐藏。
templates
类型：Object；默认值：
{ leftArrow: '&laquo;', rightArrow: '&raquo;' }
作用：用于生成面板局部（如前/后翻页箭头）的模板。每个属性必须是纯文本或合法 HTML 字符串，便于接入自定义图标库，例如 Font Awesome：
{ leftArrow: '<i class="fa fa-long-arrow-left"></i>', rightArrow: '<i class="fa fa-long-arrow-right"></i>' }
源码中用_check_template（js/bootstrap-datepicker.js）校验模板：空值直接拒绝，不含</>的纯文本直接通过，含 HTML 的则用 jQuery 包裹后检查能否构造出有效 DOM，非法模板不会生效。
todayBtn / todayHighlight / clearBtn
todayBtn：Boolean 或"linked"；默认值：false。为true或"linked"时，面板底部显示「Today」按钮。二者区别：true只把当前日期滚入视野；"linked"会同时选中今天。
todayHighlight：Boolean；默认值：false。为true时高亮面板中的今天。
clearBtn：Boolean；默认值：false。为true时面板底部显示「Clear」按钮，用于清空输入框值；若同时开启了autoclose，点击 Clear 后还会关闭面板。
输入、键盘与移动端
showOnFocus
类型：Boolean；默认值：true。
作用：为false时，输入框获得焦点不再自动弹出面板（需通过方法或点击其他触发元素打开）。
enableOnReadonly
类型：Boolean；默认值：true。
作用：为false时，readonly输入框不会弹出面板。
disableTouchKeyboard
类型：Boolean；默认值：false。
作用：为true时，移动设备上不会弹出系统软键盘。
keyboardNavigation
类型：Boolean；默认值：true。
作用：是否允许用方向键在面板中导航日期。
限制：内嵌/内联（inline）模式完全不支持键盘导航；此外，输入框没有焦点时键盘导航不生效——这在组件模式下或通过show方法打开面板时可能成为问题。完整的按键说明见 docs/keyboard.rst。
格式与国际化
format
类型：String 或 Object；默认值："mm/dd/yyyy"。
字符串格式由d、dd、D、DD、m、mm、M、MM、yy、yyyy组合而成：
标记
含义
示例
d/dd
数字日期，无前导零 / 有前导零
5/05
D/DD
星期名缩写 / 全称
Mon/Monday
m/mm
数字月份，无前导零 / 有前导零
7/07
M/MM
月份名缩写 / 全称
Jan/January
yy/yyyy
2 位 / 4 位年份
12/2012
对象格式（自定义格式化）：提供toDisplay与toValue两个函数，分别负责「Date 对象 → 输入框显示的字符串」与「字符串 → 日期选择所用的 Date 对象」，签名均为(date, format, language)。典型场景是「界面上展示一周后的日期，但输入框存真实日期」——例如 UI 选择本地日期、存储用 UTC：
$('.datepicker').datepicker({ format: { /* * Say our UI should display a week ahead, * but textbox should store the actual date. * This is useful if we need UI to select local dates, * but store in UTC */ toDisplay: function (date, format, language) { var d = new Date(date); d.setDate(d.getDate() - 7); return d.toISOString(); }, toValue: function (date, format, language) { var d = new Date(date); d.setDate(d.getDate() + 7); return new Date(d); } } });
该场景在 tests/suites/options.js 中有完整测试：输入框的值为 ISO 字符串且比 UI 展示的日期早 7 天，选中界面上的 9 月 4 日后，输入框值变为 8 月 28 日的 ISO 字符串。
language
类型：String；默认值："en"。
作用：指定月份/星期名称所用的 IETF 语言码（如"en"、"pt-BR"）。这些本地化名称也会作为输入框的值，进而随表单提交到服务端。完整说明见 docs/i18n.rst。
回退规则：传入完整语言码（如"de-DE"）时，先尝试加载de-DE语言包，找不到再回退到两字母语言码de；如果仍不存在，则使用英文。该回退逻辑在_process_options（js/bootstrap-datepicker.js）和opts_from_locale（js/bootstrap-datepicker.js）中均有实现。
范围选择器专用选项
inputs 与 keepEmptyValues
inputs：Array 或 jQuery 集合；默认值：无。用于在非标准元素上显式构建范围选择器：把一组输入框绑定到所选元素上。HTML 结构：
<div id="event_period"> <input type="text" class="actual_range"> <input type="text" class="actual_range"> </div>
$('#event_period').datepicker({ inputs: $('.actual_range') });
源码中，当元素带有input-daterange类或显式传入inputs选项时，会实例化DateRangePicker而非单个Datepicker（js/bootstrap-datepicker.js），它内部为每个输入框各建一个 picker 并同步联动（updateDates方法，js/bootstrap-datepicker.js）。
keepEmptyValues：Boolean；默认值：false。仅在范围选择器中生效。为true时，选中的值不会传播到范围内其他当前为空的 picker。
选项快速参考表
以下为 docs/options.rst 末尾「Quick reference」给出的全部选项与默认值速查表，可作为日常配置的索引：
选项
默认值
autoclose
false
assumeNearbyYear
false
beforeShowDay
（无）
beforeShowMonth
（无）
beforeShowYear
（无）
beforeShowDecade
（无）
beforeShowCentury
（无）
calendarWeeks
false
clearBtn
false
container
'body'
datesDisabled
[]
daysOfWeekDisabled
[]
daysOfWeekHighlighted
[]
defaultViewDate
today
disableTouchKeyboard
false
enableOnReadonly
true
endDate
Infinity
forceParse
true
format
'mm/dd/yyyy'
immediateUpdates
false
inputs
（无）
keepEmptyValues
false
keyboardNavigation
true
language
'en'
maxViewMode
4（'centuries'）
minViewMode
0（'days'）
multidate
false
multidateSeparator
','
orientation
'auto'
showOnFocus
true
startDate
-Infinity
startView
0（'days'，当月）
templates
{leftArrow: '&laquo;', rightArrow: '&raquo;'}
title
''
todayBtn
false
todayHighlight
false
toggleActive
false
weekStart
0（周日）
zIndexOffset
10
以上默认值均可与 js/bootstrap-datepicker.js 中$.fn.datepicker.defaults的源码定义逐一对照验证。结合本文介绍的优先级链（JS 参数 > data 属性 > 语言包 > 全局默认值）与 data 属性命名规则，你可以在不写任何 JavaScript 的情况下，仅通过 HTML 属性完成绝大多数常见日期选择场景的配置；而涉及自定义格式化、复杂禁用逻辑或范围联动时，则可通过选项对象与回调函数获得完全的控制力。
赞分享
前端
UI组件
【免费下载链接】bootstrap-datepicker
A datepicker for twitter bootstrap (@twbs)
项目地址：https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker
点击查看免费下载
相关推荐
如何使用headless-cat-n-mouse：5分钟快速上手浏览器指纹攻防实验
如何使用headless cat n mouse：5分钟快速上手浏览器指纹攻防实验 headless cat n mouse是一个专注于浏览器指纹检测与反检测技
前端
golangci-lint Linter Settings 配置指南：从 `linters.settings` 到源码级默认值
golangci lint Linter Settings 配置指南：从 linters.settings 到源码级默认值 本文是 golangci lint
开发工具代码质量Lint静态分析
axios 配置默认值详解：全局默认值、实例默认值与配置优先级（附源码解析）
axios 配置默认值详解：全局默认值、实例默认值与配置优先级（附源码解析） axios 允许为每个请求指定配置默认值，包括 baseURL 、 headers
网络后端前端