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

前端UI组件【免费下载链接】bootstrap-datepickerA datepicker for twitter bootstrap (twbs)项目地址https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker点击查看免费下载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 classdatepicker>// 方式三修改全局默认值对所有实例生效 $.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.jsautoclose: true时点击某个日期后断言面板is(:not(:visible))。multidate 与 multidateSeparatormultidateBoolean 或 Number默认值false。开启后月视图中每个日期变为「切换按钮」按顺序记录用户选中的日期传入数字时限制可选数量超出后从最旧日期开始丢弃true表示不限制。输入框的值由所有选中日期按format格式化后用multidateSeparator拼接而成。如需用多选实现「选两个日期作为范围」见 docs/markup.rst 中的 daterange 部分。multidateSeparatorString默认值,。拼接/拆分多选日期字符串的分隔符。解析输入值时同样用它拆分字符串因此强烈建议不要使用可能成为日期格式子串的字符做分隔符例如format为yyyy-mm-dd时不应使用-。源码中multidate会被归一化js/bootstrap-datepicker.jsif (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_multidatejs/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 / endDatestartDateDate 或 String默认值-Infinity时间起点。可选的最早日期更早的日期全部禁用。endDateDate 或 String默认值Infinity时间终点。可选的最晚日期更晚的日期全部禁用。两者均可直接用 data 属性配置例如「禁用今天之后的所有日期」input typetext classform-control />datesDisabled类型String 或 Array默认值[]。作用按给定format格式化的一组日期字符串或单个字符串这些日期将被禁用。源码处理js/bootstrap-datepicker.js非数组时先按逗号split成数组再逐项parseDateo.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]。两者的解析共用_resolveDaysOfWeekjs/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 的界面分为五个视图层级数字与名称均可作为视图标识由_resolveViewNamejs/bootstrap-datepicker.js统一解析数值名称视图内容0days/month月日视图1months/year年月视图2years/decade十年年视图3decades/century世纪十年视图4centuries/millennium千年世纪视图startView类型Number 或 String默认值0days即当月。作用面板打开时展示的初始视图。对「出生日期」这类只要求年份/月份的选择场景很实用。minViewMode / maxViewModeminViewModeNumber 或 String默认值0days。允许的最细粒度视图。maxViewModeNumber 或 String默认值4centuries。允许的最大最粗视图。两者共同约束可停留的视图范围minViewMode设得越高用户越早停止下钻例如设为1后只能选到月选月时日期自动置为当月 1 日maxViewMode设得越低翻页最多能到的层级越浅。源码中startView还会被夹在 min/max 之间js/bootstrap-datepicker.jso.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.jsDate应为本地时区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 与 calendarWeeksweekStartInteger默认值0周日。一周从星期几开始取值 0周日到 6周六。源码中会取模并同时推导出weekEndo.weekStart % 7; o.weekEnd (o.weekStart 6) % 7;js/bootstrap-datepicker.js。由于weekStart属于locale_opts它也可以由语言包提供。calendarWeeksBoolean默认值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 classfa fa-long-arrow-left/i, rightArrow: i classfa fa-long-arrow-right/i }源码中用_check_templatejs/bootstrap-datepicker.js校验模板空值直接拒绝不含/的纯文本直接通过含 HTML 的则用 jQuery 包裹后检查能否构造出有效 DOM非法模板不会生效。todayBtn / todayHighlight / clearBtntodayBtnBoolean 或linked默认值false。为true或linked时面板底部显示「Today」按钮。二者区别true只把当前日期滚入视野linked会同时选中今天。todayHighlightBoolean默认值false。为true时高亮面板中的今天。clearBtnBoolean默认值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/05D/DD星期名缩写 / 全称Mon/Mondaym/mm数字月份无前导零 / 有前导零7/07M/MM月份名缩写 / 全称Jan/Januaryyy/yyyy2 位 / 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_optionsjs/bootstrap-datepicker.js和opts_from_localejs/bootstrap-datepicker.js中均有实现。范围选择器专用选项inputs 与 keepEmptyValuesinputsArray 或 jQuery 集合默认值无。用于在非标准元素上显式构建范围选择器把一组输入框绑定到所选元素上。HTML 结构div idevent_period input typetext classactual_range input typetext classactual_range /div$(#event_period).datepicker({ inputs: $(.actual_range) });源码中当元素带有input-daterange类或显式传入inputs选项时会实例化DateRangePicker而非单个Datepickerjs/bootstrap-datepicker.js它内部为每个输入框各建一个 picker 并同步联动updateDates方法js/bootstrap-datepicker.js。keepEmptyValuesBoolean默认值false。仅在范围选择器中生效。为true时选中的值不会传播到范围内其他当前为空的 picker。选项快速参考表以下为 docs/options.rst 末尾「Quick reference」给出的全部选项与默认值速查表可作为日常配置的索引选项默认值autoclosefalseassumeNearbyYearfalsebeforeShowDay无beforeShowMonth无beforeShowYear无beforeShowDecade无beforeShowCentury无calendarWeeksfalseclearBtnfalsecontainerbodydatesDisabled[]daysOfWeekDisabled[]daysOfWeekHighlighted[]defaultViewDatetodaydisableTouchKeyboardfalseenableOnReadonlytrueendDateInfinityforceParsetrueformatmm/dd/yyyyimmediateUpdatesfalseinputs无keepEmptyValuesfalsekeyboardNavigationtruelanguageenmaxViewMode4centuriesminViewMode0daysmultidatefalsemultidateSeparator,orientationautoshowOnFocustruestartDate-InfinitystartView0days当月templates{leftArrow: laquo;, rightArrow: raquo;}titletodayBtnfalsetodayHighlightfalsetoggleActivefalseweekStart0周日zIndexOffset10以上默认值均可与 js/bootstrap-datepicker.js 中$.fn.datepicker.defaults的源码定义逐一对照验证。结合本文介绍的优先级链JS 参数 data 属性 语言包 全局默认值与 data 属性命名规则你可以在不写任何 JavaScript 的情况下仅通过 HTML 属性完成绝大多数常见日期选择场景的配置而涉及自定义格式化、复杂禁用逻辑或范围联动时则可通过选项对象与回调函数获得完全的控制力。赞分享前端UI组件【免费下载链接】bootstrap-datepickerA datepicker for twitter bootstrap (twbs)项目地址https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker点击查看免费下载相关推荐如何使用headless-cat-n-mouse5分钟快速上手浏览器指纹攻防实验如何使用headless cat n mouse5分钟快速上手浏览器指纹攻防实验 headless cat n mouse是一个专注于浏览器指纹检测与反检测技前端golangci-lint Linter Settings 配置指南从 linters.settings 到源码级默认值golangci lint Linter Settings 配置指南从 linters.settings 到源码级默认值 本文是 golangci lint开发工具代码质量Lint静态分析axios 配置默认值详解全局默认值、实例默认值与配置优先级附源码解析axios 配置默认值详解全局默认值、实例默认值与配置优先级附源码解析 axios 允许为每个请求指定配置默认值包括 baseURL 、 headers网络后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考