表单时间选择器(Form Datepicker)

<b-form-datepicker> 是 BootstrapVue 定制日期选择器输入表单控件,它提供完整的WAI-ARIA合规性和国际化支持。

作为 <b-calendar> 组件的表单控件包装器组件,它提供了附加的验证状态表示形式和紧凑的接口。原始 HTML5 日期输入在表示形式,可访问性方面有所不同,并且在某些情况下并非所有浏览器都支持。<b-form-datepicker> 在所有浏览器平台和设备上提供一致且可访问的界面。

<b-form-datepicker> 组件在 BootstrapVue 发行版 v2.5.0 中引入。

Value: ''

<template>
  <div>
    <label for="example-datepicker">Choose a date</label>
    <b-form-datepicker id="example-datepicker" v-model="value" class="mb-2"></b-form-datepicker>
    <p>Value: '{{ value }}'</p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: ''
      }
    }
  }
</script>

<b-form-datepicker> 支持 <b-calendar> 上可用的许多道具,以及 <b-dropdown> 上可用的一些属性 。

v-model 返回值

默认情况下,<b-form-datepicker>YYYY-MM-DD 格式返回日期作为字符串,该格式与本机浏览器 <input type="date"> 控件返回的格式相同。您可以让 <b-form-datepicker> 返回 Date 对象(没有时间部分)作为 v-model 值,而不是通过设置 value-as-date 属性。

如果未选择任何日期,则 <b-form-datepicker> 返回空字符串 '' ,如果设置了 value-as-date 属性,则返回 null

请注意,设置了 value-as-date 属性后,返回的 Date 对象将位于浏览器的默认时区。

如果 <b-form-datepicker>name 属性设置了值,则将创建一个隐藏的输入,其名称属性设置为 name 属性的值,并且value属性将设置为所选日期,例如 YYYY-MM-DD 字符串。这将允许 <b-form-datepicker> 选择的值通过本机浏览器表单提交来提交。

禁用和只读状态

设置 disabled 属性将删除 <b-form-datepicker> 组件的所有交互性。

设置 readonly 道具将禁用选择日期,但将保持组件的交互性,允许日期导航。v-model 不会以只读状态更新。

要禁用特定日期或设置最小和最大日期限制,请参阅 Date constraints【日期限制】部分。

Select date picker interactive state
<template>
  <div>
    <b-form-group label="Select date picker interactive state">
      <b-form-radio-group v-model="state" aria-controls="ex-disabled-readonly">
        <b-form-radio value="disabled">Disabled</b-form-radio>
        <b-form-radio value="readonly">Readonly</b-form-radio>
        <b-form-radio value="normal">Normal</b-form-radio>
      </b-form-radio-group>
    </b-form-group>
    <b-form-datepicker id="ex-disabled-readonly" :disabled="disabled" :readonly="readonly"></b-form-datepicker>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        state: 'disabled'
      }
    },
    computed: {
      disabled() {
        return this.state === 'disabled'
      },
      readonly() {
        return this.state === 'readonly'
      }
    }
  }
</script>

日期限制

最小和最大日期

通过 minmax 属性限制日历范围。 道具接受 YYYY-MM-DD 格式的日期字符串或 Date 对象。

<template>
  <div>
    <b-form-datepicker v-model="value" :min="min" :max="max" locale="en"></b-form-datepicker>
  </div>
</template>

<script>
  export default {
    data() {
      const now = new Date()
      const today = new Date(now.getFullYear(), now.getMonth(), now.getDate())
      // 15th two months prior
      const minDate = new Date(today)
      minDate.setMonth(minDate.getMonth() - 2)
      minDate.setDate(15)
      // 15th in two months
      const maxDate = new Date(today)
      maxDate.setMonth(maxDate.getMonth() + 2)
      maxDate.setDate(15)

      return {
        value: '',
        min: minDate,
        max: maxDate
      }
    }
  }
</script>

禁用日期

如果需要在日期选择器中禁用特定日期,请指定对 date-disabled-fn 道具的函数引用。该函数传递两个参数:

  • ymd 日期为 YYYY-MM-DD 字符串
  • date 日期作为 Date 对象

如果 不能 选择(禁用)日期,则该函数应返回 true ;如果可以选择(启用)日期,则该函数应返回 false 。请注意, 函数 不能 是异步的,应该尽快返回一个值。

<template>
  <div>
    <b-form-datepicker v-model="value" :date-disabled-fn="dateDisabled" locale="en"></b-form-datepicker>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: ''
      }
    },
    methods: {
      dateDisabled(ymd, date) {
        // Disable weekends (Sunday = `0`, Saturday = `6`) and
        // disable days that fall on the 13th of the month
        const weekday = date.getDay()
        const day = date.getDate()
        // Return `true` if the date should be disabled
        return weekday === 0 || weekday === 6 || day === 13
      }
    }
  }
</script>

请注意,在 date-disabled-fn 之前,首先评估 minmax 日期约束。

验证状态

<b-form-datepicker> 通过布尔 state 属性支持无效和有效的样式。将 state 设置为 boolean false 会将输入设置为无效,而将其设置为 boolean true 会将其设置为有效。将 state 设置为 null 不会显示任何验证状态样式(默认)。

<template>
  <div>
    <label for="datepicker-invalid">Choose a date (invalid style)</label>
    <b-form-datepicker id="datepicker-invalid" :state="false" class="mb-2"></b-form-datepicker>
    <label for="datepicker-valid">Choose a date (valid style)</label>
    <b-form-datepicker id="datepicker-valid" :state="true"></b-form-datepicker>
  </div>
</template>

请注意,本机浏览器验证 适用于 <b-form-datepicker>

式样

变量

选定的日期按钮(背景颜色)默认为 'primary' 主题变量。您可以通过 selected-variant 属性将其更改为任何 Bootstrap v4 主题变量颜色:'secondary''success''danger''warning''info' 等等。

默认情况下,今天的日期也将使用与所选日期相同的变体突出显示(文本颜色)。若要指定用于今天日期的其他主题颜色,请使用 today-variant 道具。

要完全禁用对今天日期的突出显示,请设置 no-highlight-today 属性。

控制尺寸

喜欢更大或更小的 <b-form-datepicker> 控件吗?对于较小的表单控件,将 size 属性设置为 'sm' ,对于较大的表单控件,将大小属性设置为 'lg' 。请注意,这不会影响弹出日历对话框的大小。

<template>
  <div>
    <label for="datepicker-sm">Small date picker</label>
    <b-form-datepicker id="datepicker-sm" size="sm" local="en" class="mb-2"></b-form-datepicker>
    <label for="datepicker-lg">Large date picker</label>
    <b-form-datepicker id="datepicker-lg" size="lg" local="en"></b-form-datepicker>
  </div>
</template>

占位符

如果未选择日期,则通过 placeholder【占位符】属性将自定义占位符文本添加到控件中。如果未提供占位符,则使用 label-no-date-selected 属性的值。

<template>
  <div>
    <label for="datepicker-placeholder">Date picker with placeholder</label>
    <b-form-datepicker id="datepicker-placeholder" placeholder="Choose a date" local="en"></b-form-datepicker>
  </div>
</template>

可选控件

通过 today-buttonreset-buttonclose-button ,将可选的控制按钮添加到日历弹出窗口的底部。

  • today button 选择今天的日期
  • 重置按钮将清除所选日期,或将日期设置为 reset-value 属性的值(如果提供)
  • close button 关闭日历弹出窗口

默认情况下,单击 “today” 或 “reset” 按钮也将关闭日历弹出窗口,除非设置了 no-close-on-select 属性选项。

<template>
  <div>
    <label for="datepicker-buttons">Date picker with optional footer buttons</label>
    <b-form-datepicker
      id="datepicker-buttons"
      today-button
      reset-button
      close-button
      locale="en"
    ></b-form-datepicker>
  </div>
</template>

可选按钮的文本可以通过 label-today-buttonlabel-reset-button ,和 label-close-button 道具进行设置。由于页脚部分的宽度有限,建议使这些标签简短。

使用下拉属性 rightdropupdroprightdropleftno-flip ,和 offset 来控制弹出日历的位置。

有关这些道具的效果和用法的详细信息,请参考 <b-dropdown> documentation 【文档】。

暗模式

想要带有深色背景而非浅色背景的精美弹出窗口?将 dark 属性设置为 true 以启用深色背景。

国际化

通过 Intl.DateTimeFormat 提供日期选择器日历的国际化,但应用于日历控件元素的标签(aria标签,所选状态和帮助文本)除外。您必须为这些标签提供自己的翻译。可用的语言环境取决于浏览器(并非所有浏览器都支持所有语言环境)

默认情况下,<b-form-datepicker> 将使用浏览器的默认语言环境,但是您可以通过 locale【地区】属性指定要使用的语言环境。该道具接受单个语言环境字符串或语言环境字符串数组(按首选语言环境的顺序列出)。

日历从星期天开始。可以通过将 start-weekday 属性设置为 06 之间的数字来更改此值,其中 0 代表星期日,星期一代表 1 ,星期六代表 6

Value: ''

<template>
  <div>
    <label for="example-locales">Locale:</label>
    <b-form-select id="example-locales" v-model="locale" :options="locales" class="mb-2"></b-form-select>

    <label for="example-weekdays">Start weekday:</label>
    <b-form-select id="example-weekdays" v-model="weekday" :options="weekdays" class="mb-2"></b-form-select>

    <label for="example-i18n-picker">Date picker:</label>
    <b-form-datepicker
      id="example-i18n-picker"
      v-model="value"
      v-bind="labels[locale] || {}"
      :locale="locale"
      :start-weekday="weekday"
      class="mb-2"
     ></b-form-datepicker>
     <p>Value: <b>'{{ value }}'</b></p>
   </div>
</template>

<script>
  export default {
    data() {
      return {
        value: '',
        locale: 'en-US',
        locales: [
          { value: 'en-US', text: 'English US (en-US)' },
          { value: 'de', text: 'German (de)' },
          { value: 'ar-EG', text: 'Arabic Egyptian (ar-EG)' },
          { value: 'zh', text: 'Chinese (zh)' }
        ],
        weekday: 0,
        weekdays: [
          { value: 0, text: 'Sunday' },
          { value: 1, text: 'Monday' },
          { value: 6, text: 'Saturday' }
        ],
        labels: {
          de: {
            labelPrevYear: 'Vorheriges Jahr',
            labelPrevMonth: 'Vorheriger Monat',
            labelCurrentMonth: 'Aktueller Monat',
            labelNextMonth: 'Nächster Monat',
            labelNextYear: 'Nächstes Jahr',
            labelToday: 'Heute',
            labelSelected: 'Ausgewähltes Datum',
            labelNoDateSelected: 'Kein Datum gewählt',
            labelCalendar: 'Kalender',
            labelNav: 'Kalendernavigation',
            labelHelp: 'Mit den Pfeiltasten durch den Kalender navigieren'
          },
          'ar-EG': {
            labelPrevYear: 'العام السابق',
            labelPrevMonth: 'الشهر السابق',
            labelCurrentMonth: 'الشهر الحالي',
            labelNextMonth: 'الشهر المقبل',
            labelNextYear: 'العام المقبل',
            labelToday: 'اليوم',
            labelSelected: 'التاريخ المحدد',
            labelNoDateSelected: 'لم يتم اختيار تاريخ',
            labelCalendar: 'التقويم',
            labelNav: 'الملاحة التقويم',
            labelHelp: 'استخدم مفاتيح المؤشر للتنقل في التواريخ'
          },
          zh: {
            labelPrevYear: '上一年',
            labelPrevMonth: '上个月',
            labelCurrentMonth: '当前月份',
            labelNextMonth: '下个月',
            labelNextYear: '明年',
            labelToday: '今天',
            labelSelected: '选定日期',
            labelNoDateSelected: '未选择日期',
            labelCalendar: '日历',
            labelNav: '日历导航',
            labelHelp: '使用光标键浏览日期'
          }
        }
      }
    }
  }
</script>

您可以侦听 context 事件,以确定日历已解决的语言环境和方向性。

有关更多详细信息,请参考 <b-calendar> 文档。

辅助功能

弹出日历支持与 <b-calendar> 相同的键盘控件 ,以及以下内容:

  • ESC 将关闭弹出日历而不选择日期

在对日期选择器进行国际化时,还必须使用适当的翻译字符串更新 label-* 属性,以便国际屏幕阅读器用户能够听到正确的提示和描述。

有关更多详细信息,请参考 <b-calendar> 文档。

实施说明

<b-form-datepicker> 基于组件 <b-calendar><b-dropdown>

<b-form-datepicker> 使用 Bootstrap 的 margin ,padding ,border 和 flex 实用程序类,以及按钮(btn-*)类和 form-control*(加验证)类。

日期选择器和日历的正确样式也需要 BootstrapVue 的自定义 SCSS / CSS。

另请参阅

组件参考

<b-form-datepicker>

v2.5.0+

组件别名

<b-form-datepicker> 也可以通过以下别名使用:

  • <b-datepicker>

注意:组件别名仅在导入所有 BootstrapVue 或使用组件组插件时可用。

属性

属性 (Click to sort Ascending) 类型 默认值 描述
id String 用于在渲染的内容上设置“ id”属性,并用作根据需要生成任何其他元素ID的基础
value v-model String or Date 最初选择的日期值。接受“YYYY-MM-DD”字符串或“Date”对象
value-as-date Boolean false 返回 v-model 的 Date 对象而不是 YYYY-MM-DD 字符串
reset-value String or Date 单击可选的“reset”按钮时,所选日期将设置为此值。默认是清除选择的值
placeholder String 当未选择日期时,文本将显示在表单控件中。默认为“label-no-date-selected”属性值
size String 设置组件外观的大小。 'sm','md'(默认)或'lg'
min String or Date 日历显示的最短日期
max String or Date 日历显示的最长时间
disabled Boolean false 将日历置于非交互式禁用状态
readonly Boolean false 将日历置于交互式只读状态。 禁用更新 v-model ,同时仍允许日期导航
required Boolean false 设置后,在组件上添加 aria-required = “true”属性。 所需的验证需要由您的应用程序处理
name String 设置表单控件上“name”属性的值
form String 表单控件所属的表单的 ID。在控件上设置“form”属性
state Boolean 控制组件的验证状态外观。“true”表示有效,“false”表示无效”,“null”表示无验证状态
date-disabled-fn Function 设置为一个函数引用,如果禁用了日期,则返回“true”,如果应启用日期,则返回“false”。有关详细信息,请参见文档
no-close-on-select Boolean false 单击/选择日期时,禁用关闭弹出日期选择器
hide-header Boolean false 设置后,可视地隐藏选定的日期标题
locale String or Array 日历要使用的语言环境。 传递语言环境数组时,语言环境的顺序从最优选到最不喜欢
start-weekday Number or String 0 星期几开始日历。星期日为0,星期一为1,星期六为6,依此类推。
direction String 设置为字符串“rtl”或“ltr”以显式强制日历以从右到左或从左向右(分别)的方式渲染。默认为解析的语言环境的方向性
selected-variant String 'primary' 用于所选日期按钮的主题颜色变量
today-variant String 主题颜色变体,用于突出显示 todays date 按钮。默认为`variant`属性
no-highlight-today Boolean false 禁用日历中今天日期的突出显示
today-button Boolean false 设置后,显示可选的 `select today` 按钮
label-today-button String 'Select today' 可选的 `Select today` 按钮的内容
today-button-variant String 'outline-primary' 用于可选的 `select today` 按钮的按钮变量
reset-button Boolean false 设置后,显示可选的 `reset` 按钮
label-reset-button String 'Reset' 可选的 `Reset` 按钮的内容
reset-button-variant String 'outline-danger' 用于可选的 `reset` 按钮的按钮变量
close-button Boolean false 设置后,显示可选的关闭按钮
label-close-button String 'Close' 可选的“Close”【关闭】按钮的内容
close-button-variant String 'outline-secondary' 用于可选的“Close”【关闭】按钮的按钮变量
label-prev-year String 'Previous year' “Previous Year”【上一年】导航按钮上的“aria-label”和“title”属性的值
label-prev-month String 'Previous month' “Previous Month”【上个月】导航按钮上的“aria-label”和“title”属性的值
label-current-month String 'Current month' “Current Month”【当前月】导航按钮上的“aria-label”和“title”属性的值
label-next-month String 'Next month' “Next Month”【下个月】导航按钮上的“aria-label”和“title”属性的值
label-next-year String 'Next year' “Next year”【下一年】导航按钮上的“ aria-label”和“ title”属性的值
label-today String 'Today' 日历网格日期按钮的“aria-label”属性的值,表示该日期为今天的日期
label-selected String 'Selected date' 在选定的日历网格日期按钮上设置的“aria-label”属性的值
label-no-date-selected String 'No date selected' 当前未选择日期时要使用的标签
label-calendar String 'Calendar' “aria-label”和“role-description”属性的值应用于日历网格
label-nav String 'Calendar navigation' 日历导航按钮包装上的 aria-label 属性的值
label-help String 'Use cursor keys to navigate calendar dates' 出现在日历网格底部的帮助文本
dark Boolean false 设置后,为弹出日历对话框提供深色背景
dropup Boolean false 设置后,将菜单置于按钮顶部
dropright Boolean false 设置后,将菜单置于按钮右侧
dropleft Boolean false 设置后,将菜单置于按钮左侧
right Boolean false 将菜单的右边与按钮的右边对齐
offset Number or String 0 指定要移动菜单的像素数。 支持负值
no-flip Boolean false 防止菜单自动翻转位置
popper-opts Any 传递给 Popper.js 的其他配置
boundary String or HTMLElement 'scrollParent' 菜单的边界约束:'scrollParent','window','viewport'或对 HTMLElement 的引用

v-model

属性 事件
value input

事件

事件 参数 描述
input
  1. date - 格式为 YYYY-MM-DD 的字符串或日期对象(如果 value-as-date 属性为 true)。
更新 v-model 时发出
context
  1. context - `b-calendar` 上下文对象。有关详细信息,请参见 “b-calendar” 文档
`b-calendar`上下文事件。当用户通过日期导航按钮或光标控件更改活动日期时发出

导入单个组件

您可以通过以下命名的导出将单个组件导入到项目中:

组件 命名输出 导入路径
<b-form-datepicker> BFormDatepicker bootstrap-vue

示例:

import { BFormDatepicker } from 'bootstrap-vue'
Vue.component('b-form-datepicker', BFormDatepicker)

导入为Vue.js插件

该插件包括上面列出的所有单个组件。插件还包括任何组件别名。

命名输出 导入路径
FormDatepickerPlugin bootstrap-vue

示例:

import { FormDatepickerPlugin } from 'bootstrap-vue'
Vue.use(FormDatepickerPlugin)