日期选择器 · Bootstrap 6.0 中文文档

概览

Bootstrap 日期选择器是一个围绕 Vanilla Calendar Pro的包装器，提供一致且可访问的日期选择体验。它支持浅色/深色主题、输入绑定，并通过数据属性或 JavaScript 提供灵活配置。

日期选择器

HTML

<label for="datepicker1" class="form-label">Datepicker</label>
<input type="text" class="form-control w-12" id="datepicker1" data-bs-toggle="datepicker" autocomplete="off" placeholder="Choose date…">

请注意，我们使用了宽度工具 .w-12 来确保输入足够宽，以容纳日期格式，并暗示预期输入类型的一些提示。

它是如何工作的

添加 data-bs-toggle="datepicker" 到任何 <input> 用于启用日期选择器的元素
使用 type="text" 以避免与浏览器原生日历选择器发生冲突
当聚焦时，日历弹出窗口出现在输入框下方
选择日期会更新输入值并关闭选择器
当点击它外部时，选择器也会关闭， Escape，或者当焦点移动到其外的元素时
选择器支持 Bootstrap 的颜色模式（data-bs-theme)
可与任何配置 Vanilla Calendar Pro选项通过 vcpOptions 使用 JavaScript 初始化时

示例

带表单字段

使用表单字段组件，将输入与标签、描述和验证反馈信息以垂直堆叠的方式布局和包裹。

日期选择器字段

我们绝不会将你的电子邮件与其他人分享。

HTML

<div class="form-field">
  <label for="datepicker2" class="form-label">Datepicker field</label>
  <input type="text" class="form-control w-12" id="datepicker2" data-bs-toggle="datepicker" autocomplete="off" placeholder="Choose date…">
  <div class="form-text">
    We’ll never share your email with anyone else.
  </div>
</div>

带图标

使用表单装饰组件在日期选择器输入框旁添加日历图标。当输入框位于 .form-adorn 包裹器内时，日历会自动相对于包裹器而不是输入框定位。

选择日期

HTML

<label for="datepickerIconStart" class="form-label">Select date</label>
<div class="form-control form-adorn w-12">
  <div class="form-adorn-icon">
    <svg class="bi" width="16" height="16"><use href="#calendar-week" /></svg>
  </div>
    <input type="text" class="form-ghost" id="datepickerIconStart" data-bs-toggle="datepicker" autocomplete="off" placeholder="Choose date…">
</div>

最小和最大日期

使用data-bs-date-min和data-bs-date-max限制可选择的日期范围。

活动日期（仅限2026年）

HTML

<label for="datepickerMinMax" class="form-label">Event date (2026 only)</label>
<input type="text" class="form-control w-12" id="datepickerMinMax" data-bs-toggle="datepicker" autocomplete="off" data-bs-date-min="2026-01-01" data-bs-date-max="2026-12-31" placeholder="Select a date in 2026">

多个日期

使用 data-bs-selection-mode="multiple" 启用多日期选择。

选择多个日期

HTML

<label for="datepicker3" class="form-label">Select multiple dates</label>
<input type="text" class="form-control" id="datepicker3" data-bs-toggle="datepicker" autocomplete="off" data-bs-selection-mode="multiple" placeholder="Select date range…">

多个月

使用 displayMonthsCount 选项并排显示多个月份。这对于需要查看更多上下文的日期范围选择非常有用。

选择日期范围

HTML

<label for="datepickerMultiMonth" class="form-label">Select date range</label>
<input type="text" class="form-control" id="datepickerMultiMonth" data-bs-toggle="datepicker" autocomplete="off" data-bs-selection-mode="multiple-ranged" data-bs-display-months-count="2" placeholder="Select start and end dates">

日期范围

使用 data-bs-selection-mode="multiple-ranged" 选择一个日期范围。使用 data-bs-selected-dates 预先选择一个日期范围。

选择日期范围

HTML

<label for="datepicker4" class="form-label">Select date range</label>
<input type="text" class="form-control" id="datepicker4" data-bs-toggle="datepicker" autocomplete="off" data-bs-selection-mode="multiple-ranged" data-bs-selected-dates='["2026-06-10", "2026-06-18"]' placeholder="Select start and end dates…">

多月日期范围

对于选择跨越多个月的日期范围，将 data-bs-selection-mode="multiple-ranged" 与 data-bs-display-months-count="2" 结合使用以并排显示两个月，使用户更容易跨月份进行选择。

选择日期范围

HTML

<label for="datepickerRangeTwoMonths" class="form-label">Select date range</label>
<input type="text" class="form-control" id="datepickerRangeTwoMonths" data-bs-toggle="datepicker" autocomplete="off" data-bs-selection-mode="multiple-ranged" data-bs-display-months-count="2" data-bs-selected-dates='["2026-06-25", "2026-07-08"]' placeholder="Select start and end dates…">

选项

一周的第一天

使用 data-bs-first-weekday 设置一周的第一天（0 = 星期日，1 = 星期一，依此类推）。

星期从星期日开始

HTML

<label for="datepicker6" class="form-label">Week starts on Sunday</label>
<input type="text" class="form-control w-12" id="datepicker6" data-bs-toggle="datepicker" autocomplete="off" data-bs-first-weekday="0" placeholder="Select a date">

职位安排

使用 data-bs-placement 控制日历相对于输入框显示的位置。选项有 left（默认）、center、right 和 auto。

左对齐

居中对齐

右对齐

HTML

<div class="d-flex gap-3">
  <div>
    <label for="datepickerLeft" class="form-label">Left aligned</label>
    <input type="text" class="form-control" id="datepickerLeft" data-bs-toggle="datepicker" autocomplete="off" data-bs-placement="left" placeholder="Left">
  </div>
  <div>
    <label for="datepickerCenter" class="form-label">Center aligned</label>
    <input type="text" class="form-control" id="datepickerCenter" data-bs-toggle="datepicker" autocomplete="off" data-bs-placement="center" placeholder="Center">
  </div>
  <div>
    <label for="datepickerRight" class="form-label">Right aligned</label>
    <input type="text" class="form-control" id="datepickerRight" data-bs-toggle="datepicker" autocomplete="off" data-bs-placement="right" placeholder="Right">
  </div>
</div>

按钮触发器

对于仪表板日期筛选等使用场景，请使用按钮而不是输入框。向文本元素添加 data-bs-datepicker-display 以在日期更新时保留图标。

HTML

<button type="button" class="btn-outline theme-secondary" data-bs-toggle="datepicker">
<svg class="bi" width="16" height="16"><use href="#calendar-week" /></svg>
<span data-bs-datepicker-display>Select date</span>
</button>

对于日期范围选择（例如，仪表板时间过滤器），请使用 data-bs-selection-mode="multiple-ranged"。在选择了开始日期和结束日期后，日历将关闭。

HTML

<button type="button" class="btn-outline theme-secondary" data-bs-toggle="datepicker" data-bs-selection-mode="multiple-ranged">
  <svg class="bi" width="16" height="16"><use href="#calendar-week" /></svg>
  <span data-bs-datepicker-display>Last 7 days</span>
</button>

你也可以通过 JavaScript 使用 displayElement 选项在单独的元素中显示所选日期：

JavaScript

          const datepicker = new bootstrap.Datepicker(buttonElement, {
  selectionMode: 'multiple-ranged',
  displayElement: '#date-display' // Selector or element
})

内联模式

使用 data-bs-inline="true" 内联渲染日历（始终可见，无弹出窗口）。这对于直接在页面中嵌入日历非常有用。

HTML

<div data-bs-toggle="datepicker" data-bs-inline="true"></div>

内联日期选择器，可选择日期范围：

HTML

<div data-bs-toggle="datepicker" data-bs-inline="true" data-bs-selection-mode="multiple-ranged"></div>

多个月连续排列：

HTML

<div data-bs-toggle="datepicker" data-bs-inline="true" data-bs-display-months-count="2"></div>

要绑定到表单字段，请在容器内包含一个隐藏的输入。其值将以 YYYY-MM-DD 格式更新为所选日期：

HTML

<form>
<div data-bs-toggle="datepicker" data-bs-inline="true">
  <input type="hidden" name="selected_date">
</div>
<button type="submit" class="btn-solid theme-primary mt-3">Submit</button>
</form>

自定义日期格式

使用 dateFormat 选项控制日期的显示方式。传入 Intl.DateTimeFormat 选项对象或自定义函数。

JavaScript

          // Using Intl.DateTimeFormat options
const datepicker = new bootstrap.Datepicker(element, {
  dateFormat: { month: 'short', day: 'numeric', year: 'numeric' }
  // Output: "Dec 23, 2026 – Dec 28, 2026"
})

// Using a custom function
const datepicker = new bootstrap.Datepicker(element, {
  dateFormat: (date, locale) => {
    return date.toLocaleDateString(locale, { month: 'short', day: 'numeric' })
  }
  // Output: "Dec 23 – Dec 28"
})

深色模式

日期选择器会自动适应 Bootstrap 的颜色模式。当在父元素上设置 data-bs-theme="dark" 或使用 <html> 标签时，日历弹出窗口会继承该主题。

继承自父项

当父元素有主题时，输入框和日历弹出窗口都会继承该主题：

深色模式日期选择器

HTML

<div data-bs-theme="dark" class="p-3 bg-body fg-body rounded">
<label for="datepickerDark" class="form-label">Dark mode datepicker</label>
<input type="text" class="form-control" id="datepickerDark" data-bs-toggle="datepicker" autocomplete="off" placeholder="Select a date">
</div>

仅日期选择器主题

使用 data-bs-datepicker-theme 可以独立于输入框设置日期选择器弹出窗口的主题。当你想要浅色输入框配深色日期选择器，或反之时，这非常有用：

浅色输入，深色日期选择器

HTML

<label for="datepickerTheme" class="form-label">Light input, dark datepicker</label>
<input type="text" class="form-control w-12" id="datepickerTheme" data-bs-toggle="datepicker" autocomplete="off" data-bs-datepicker-theme="dark" placeholder="Select a date">

Shadow DOM

日历在 shadow root 内呈现，这对于封装的网页组件很有用。有两点与正常使用不同：

使用 JavaScript 初始化日期选择器。委托事件会在 shadow 边界重新定位，因此 data-bs-toggle="datepicker" 无法触及 shadow root 内的元素。
将 Bootstrap 的样式表引入到 shadow root 中。文档样式不会跨越边界，因此没有它，日历将无法渲染样式。

JavaScript

          const sheet = new CSSStyleSheet()
sheet.replaceSync(await (await fetch('/path/to/bootstrap.min.css')).text())

const root = host.attachShadow({ mode: 'open' })
root.adoptedStyleSheets = [sheet]
root.innerHTML = '<input type="text" id="shadowDatepicker">'

new bootstrap.Datepicker(root.getElementById('shadowDatepicker'))

CSS

变量

scss/_日期选择器.scss

// stylelint-disable-next-line scss/dollar-variable-default
$datepicker-tokens: defaults(
  (
    --datepicker-padding: 1rem,
    --datepicker-bg: var(--bg-body),
    --datepicker-color: var(--fg-body),
    --datepicker-border-color: var(--border-color-translucent),
    --datepicker-border-width: var(--border-width),
    --datepicker-border-radius: var(--radius-7),
    --datepicker-box-shadow: var(--box-shadow),
    --datepicker-font-size: var(--font-size-sm),
    --datepicker-min-width: 280px,
    --datepicker-zindex: var(--z-menu),
    --datepicker-header-font-weight: 600,
    --datepicker-weekday-color: var(--fg-3),
    --datepicker-day-hover-bg: var(--bg-1),
    --datepicker-day-selected-bg: var(--primary-bg),
    --datepicker-day-selected-color: var(--primary-contrast),
    --datepicker-day-today-bg: var(--bg-2),
    --datepicker-day-today-color: var(--fg-1),
    --datepicker-day-disabled-color: var(--fg-4),
  ),
  $datepicker-tokens
);

用法

通过数据属性

向任何输入元素添加data-bs-toggle="datepicker"以将其初始化为日期选择器。

属性	描述
`data-bs-toggle="datepicker"`	在输入框（或按钮）元素上初始化日期选择器。
`data-bs-inline`	当 `true` 时，将日历以内嵌方式呈现，而不是弹出。

HTML

          <input type="text" class="form-control" data-bs-toggle="datepicker">

通过 JavaScript

以编程方式初始化日期选择器：

JavaScript

          const datepickerEl = document.getElementById('myDatepicker')
const datepicker = new bootstrap.Datepicker(datepickerEl, {
  selectionMode: 'single',
  firstWeekday: 1
})

依赖项

如果你从源代码构建 Bootstrap 的 JS，日期选择器插件需要以下 JavaScript 文件：

文件	描述
`js/src/datepicker.ts`	主日期选择器组件
`js/src/base-component.ts`	基础组件类
`js/src/dom/data.ts`	元素数据存储
`js/src/dom/event-handler.ts`	事件处理工具
`js/src/dom/manipulator.ts`	数据属性操作
`js/src/util/config.ts`	配置基类
`js/src/util/index.ts`	核心实用功能
`vanilla-calendar-pro`	第三方日历库

选项

名称	类型	默认	描述
`dateMin`	字符串，数字，日期	`null`	可选择的最小日期。格式： `YYYY-MM-DD`
`dateMax`	字符串，数字，日期	`null`	可选择的最大日期。格式： `YYYY-MM-DD`
`dateFormat`	对象，函数	`null`	日期格式化。通过 `Intl.DateTimeFormat` 选项或一个 `function(date, locale)`.
`displayElement`	字符串，元素，布尔值	`null`	显示格式化日期的元素。对于按钮，默认为按钮本身。设置为 `false` 禁用。
`displayMonthsCount`	number	`1`	日历中并排显示的月份数量。
`firstWeekday`	number	`1`	一周的第一天（0 = 星期日，1 = 星期一，依此类推）
`inline`	boolean	`false`	内联显示日历（始终可见，无弹出）。
`locale`	string	`'default'`	日期格式的区域设置（例如， `'en-US'`, `'de-DE'`)
`positionElement`	字符串，元素	`null`	用于定位日历的元素。自动检测 `.form-adorn` 如果存在，则为包装器。
`selectedDates`	array	`[]`	预先选择的日期在 `YYYY-MM-DD` 格式
`selectionMode`	string	`'single'`	选择模式： `'single'`, `'multiple'`，或者 `'multiple-ranged'`
`placement`	string	`'left'`	日历相对于输入的位置： `'left'`, `'center'`, `'right'`, `'auto'`
`datepickerTheme`	string	`null`	强制日期选择器弹出主题： `'light'`, `'dark'`, `'auto'`，或者 `null` 继承祖先 `[data-bs-theme]`
`vcpOptions`	object	`{}`	用于任何的直通对象 Vanilla Calendar Pro选项

高级配置

对于 Bootstrap 选项未直接提供的功能，使用 vcpOptions 来传递任何 Vanilla Calendar Pro 设置：

JavaScript

          const datepicker = new bootstrap.Datepicker(element, {
  vcpOptions: {
    disableDatesPast: true,                     // Disable past dates
    disableWeekdays: [0, 6],                    // Disable weekends
    disableDates: ['2026-12-25', '2026-12-26'], // Disable specific dates
    selectedHolidays: ['2026-01-01']            // Highlight holidays
  }
})

请参阅Vanilla Calendar Pro 文档了解所有可用选项。

Vanilla Calendar Pro 将其可选功能作为扩展提供。Bootstrap 仅使用 months 扩展，这是 displayMonthsCount 所需的。不支持其他扩展中的选项，当你设置这些选项时，Vanilla Calendar Pro 会抛出错误。这些选项包括 animation、enableSwipe、selectionTimeMode、popups 以及周视图选项。

方法

方法	描述
`show()`	显示日期选择器日历
`hide()`	隐藏日期选择器日历
`toggle()`	切换日期选择器的可见性
`getSelectedDates()`	返回所选日期的数组于 `YYYY-MM-DD` 格式
`setSelectedDates(dates)`	设置所选日期。期望一个数组 `YYYY-MM-DD` 字符串
`dispose()`	销毁日期选择器实例
`getInstance(element)`	从 DOM 元素获取日期选择器实例的静态方法
`getOrCreateInstance(element)`	获取或创建日期选择器实例的静态方法

事件

事件	描述
`show.bs.datepicker`	当调用 `show` 方法时立即触发
`shown.bs.datepicker`	当日期选择器显示时触发
`hide.bs.datepicker`	当调用 `hide` 方法时立即触发
`hidden.bs.datepicker`	当日期选择器隐藏时触发
`change.bs.datepicker`	当选择日期时触发。事件包含 `dates`（数组）和 `event` 属性

JavaScript

          const datepickerEl = document.getElementById('myDatepicker')
datepickerEl.addEventListener('change.bs.datepicker', event => {
  console.log('Selected dates:', event.dates)
})