表单时间选择器

<b-form-timepicker> 是一个 BootstrapVue 自定义时间选择器输入表单控件,它提供完全的 WAI-ARIA 合规性和国际化支持。

v2.6.0 起在 BootstrapVue 中提供

概述

作为 <b-time> 组件的表单控件包装器组件,它提供了额外的验证状态表示和紧凑的界面。原生 HTML5 时间输入在表示、无障碍方面各不相同,并且在某些情况下不受所有浏览器支持。 <b-form-timepicker> 在所有浏览器平台和设备上提供一致且无障碍的界面。

<template>
  <div>
    <b-form-timepicker v-model="value" locale="en"></b-form-timepicker>
    <div class="mt-2">Value: '{{ value }}'</div>
  </div>
</template>

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

<!-- b-form-timepicker.vue -->

v-model 返回值

<b-form-timepicker> 始终返回 'HH:mm:ss' 格式的字符串,这是原生浏览器 <input type="time"> 控件返回的相同格式。该值将介于 '00:00:00''23:59:59' 之间(24 小时制,使用 'h23' 小时周期语法)。

如果未选择时间,则 <b-form-timepicker> 返回一个空字符串 ('')。

禁用和只读状态

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

设置 readonly 属性将禁用时间选择,但会保持组件交互性,允许在自旋按钮之间使用制表符。在只读状态下,v-model 不会更新。

<template>
  <div>
    <b-form-group
      label="Select time picker interactive state"
      v-slot="{ ariaDescribedby }"
    >
      <b-form-radio-group
        v-model="state"
        :aria-describedby="ariaDescribedby"
        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-timepicker
      id="ex-disabled-readonly"
      :disabled="disabled"
      :readonly="readonly"
    ></b-form-timepicker>
  </div>
</template>

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

<!-- b-form-timepicker-disabled-readonly.vue -->

验证状态

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

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

    <label for="timepicker-valid">Choose a time (valid style)</label>
    <b-form-timepicker id="datepicker-valid" :state="true"></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-validation.vue -->

请注意,<b-form-timepicker> 不支持本机浏览器验证。

样式

启用秒自旋按钮

默认情况下,不显示秒自旋按钮。要启用秒部分,请将 show-seconds 属性设置为 true 以启用秒选择自旋按钮。当 show-seconds 为 false(或未提供)时,返回的值始终将时间字符串的秒部分设置为 00

<template>
  <div>
    <b-form-timepicker v-model="value" show-seconds locale="en"></b-form-timepicker>
    <div class="mt-2">Value: '{{ value }}'</div>
  </div>
</template>

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

<!-- b-form-timepicker-show-seconds.vue -->

控件大小

想要一个更小或更大的 <b-form-timepicker> 控件?将 size 属性设置为 'sm' 以获得更小的表单控件,或 'lg' 以获得更大的表单控件。请注意,这不会影响弹出时间选择对话框的大小。

<template>
  <div>
    <label for="timepicker-sm">Small time picker</label>
    <b-form-timepicker id="timepicker-sm" size="sm" locale="en" class="mb-2"></b-form-timepicker>

    <label for="timepicker-lg">Large time picker</label>
    <b-form-timepicker id="timepicker-lg" size="lg" locale="en"></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-control-size.vue -->

占位符

当未选择日期时,通过 placeholder 属性向控件添加自定义占位符文本。如果未提供占位符,则使用 label-no-time-selected 属性的值。

<template>
  <div>
    <label for="timepicker-placeholder">Time picker with placeholder</label>
    <b-form-timepicker id="timepicker-placeholder" placeholder="Choose a time" locale="en"></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-placeholder.vue -->

可选控件

通过属性 now-buttonreset-button 向日历弹出窗口底部添加可选控件按钮。可以通过 no-close-button 属性移除默认关闭按钮。

  • 现在按钮选择当前时间
  • 重置按钮清除所选时间,或将时间设置为属性 reset-value 的值(如果提供了该值)
  • 关闭按钮关闭时间弹出窗口
<template>
  <div>
    <label for="timepicker-buttons">Time picker with optional footer buttons</label>
    <b-form-timepicker
      id="timepicker-buttons"
      now-button
      reset-button
      locale="en"
    ></b-form-timepicker>
  </div>
</template>

<!-- b-form-timepicker-footer-buttons.vue -->

可以通过 label-now-buttonlabel-reset-buttonlabel-close-button 属性设置可选按钮的文本。由于页脚部分的宽度有限,建议将这些标签保持简短。

使用下拉菜单属性 rightdropupdroprightdropleftno-flipoffset 控制弹出日历的位置。

请参阅 <b-dropdown> 定位部分 了解这些属性的效果和用法。

仅按钮模式

v2.7.0+

仅仅想要一个启动时间选择器对话框的按钮,或者想要提供您自己的可选文本输入字段?使用 button-only 属性将时间选择器呈现为下拉按钮。格式化的时间标签将使用类 sr-only 呈现(仅对屏幕阅读器可用)。

在以下简单示例中,我们将时间选择器(仅按钮模式)放置为 <b-input-group> 的附加项

<template>
  <div>
    <label for="example-input">Choose a time</label>
    <b-input-group class="mb-3">
      <b-form-input
        id="example-input"
        v-model="value"
        type="text"
        placeholder="HH:mm:ss"
      ></b-form-input>
      <b-input-group-append>
        <b-form-timepicker
          v-model="value"
          button-only
          right
          show-seconds
          locale="en"
          aria-controls="example-input"
        ></b-form-timepicker>
      </b-input-group-append>
    </b-input-group>
    <p>Value: '{{ value }}'</p>
  </div>
</template>

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

<!-- b-form-timepicker-button-only.vue -->

通过 size 属性控制按钮的大小,通过 button-variant 属性控制按钮变体。

国际化

时间的界面国际化通过 Intl.DateTimeFormatIntl.NumberFormat 提供,时间控件元素的标签除外(aria 标签、已选择状态等)。您必须为这些标签提供自己的翻译。可用的语言环境取决于浏览器(并非所有浏览器都支持所有语言环境)。

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

发出的 'context' 事件将包括时间控件已解析到的语言环境(可能与请求的语言环境不同,具体取决于 Intl 支持的语言环境)。

对于使用 Node.js 的服务器端渲染 (SSR),请确保您使用的 Node.js 运行时支持 Intl 和您将要使用的语言环境。有关详细信息,请参阅 Node Intl 支持文档

<template>
  <b-row>
    <b-col cols="12" class="mb-3">
      <label for="example-locales">Locale:</label>
      <b-form-select id="example-locales" v-model="locale" :options="locales"></b-form-select>
    </b-col>
    <b-col md="6">
      <b-form-timepicker
        v-model="value"
        v-bind="labels[locale] || {}"
        :locale="locale"
        show-seconds
        @context="onContext"
      ></b-form-timepicker>
    </b-col>
    <b-col>
      <p>Value: <b>'{{ value }}'</b></p>
      <p class="mb-0">Context:</p>
      <pre class="small">{{ context }}</pre>
   </b-col>
  </b-row>
</template>

<script>
  export default {
    data() {
      return {
        value: '',
        context: null,
        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)' }
        ],
        labels: {
          de: {
            labelHours: 'Stunden',
            labelMinutes: 'Minuten',
            labelSeconds: 'Sekunden',
            labelIncrement: 'Erhöhen',
            labelDecrement: 'Verringern',
            labelSelected: 'Ausgewählte Zeit',
            labelNoTimeSelected: 'Keine Zeit ausgewählt',
            labelCloseButton: 'Schließen'
          },
          'ar-EG': {
            labelHours: 'ساعات',
            labelMinutes: 'الدقائق',
            labelSeconds: 'ثواني',
            labelAmpm: 'صباحا مساء',
            labelAm: 'ص',
            labelPm: 'م',
            labelIncrement: 'زيادة',
            labelDecrement: 'إنقاص',
            labelSelected: 'الوقت المحدد',
            labelNoTimeSelected: 'لا وقت المختار',
            labelCloseButton: 'قريب'
          },
          zh: {
            labelHours: '小时',
            labelMinutes: '分钟',
            labelSeconds: '秒',
            labelAmpm: '上午下午',
            labelAm: '上午',
            labelPm: '下午',
            labelIncrement: '增量',
            labelDecrement: '减量',
            labelSelected: '选定时间',
            labelNoTimeSelected: '没有选择时间',
            labelCloseButton: '关'
          }
        }
      }
    },
    methods: {
      onContext(ctx) {
        this.context = ctx
      }
    }
  }
</script>

<!-- b-form-time-i18n.vue -->

了解 hourCycle

全世界有两种主要的计时惯例(时钟):12 小时制和 24 小时制。 hourCycle 属性允许您访问特定语言环境使用的时钟类型。小时周期类型可以有几个不同的值,这些值在下面的表格中列出。 hourCycle 表示时间 '00:00:00'(一天的开始)应如何向特定语言环境的用户显示/格式化。 'context' 事件包括已解析的 hourCycle 值。

hourCycle 描述
'h12' 使用 112 的小时系统。12 小时制,午夜从 12:00 am 开始
'h23' 使用 023 的小时系统。24 小时制,午夜从 0:00 开始
'h11' 使用 011 的小时系统。12 小时制,午夜从 0:00 am 开始
'h24' 使用 124 的小时制。24 小时制,午夜从 24:00 开始

原生 HTML5 <input type="date">'h23' 格式返回时间值,<b-form-timepicker> 也以 'h23' 格式返回 v-model。此值可能与通过 <b-form-timepicker> 组件的 GUI(旋转按钮)向用户显示的值不同,具体取决于 所选区域设置

注意: IE 11 不支持解析区域设置的 hourCycle 值,因此我们根据解析的 hour12 值假设 h12h23

强制使用 12 或 24 小时界面

12 小时制与 24 小时制输入由客户端浏览器的默认区域设置(或从 locale 属性解析的区域设置)确定。要强制使用 12 小时制用户界面,请将属性 hour12 设置为 true。要强制使用 24 小时制用户界面,请将属性 hour12 设置为 false。属性 hour12 的默认值为 null,它使用解析的区域设置来确定使用哪个界面。

设置 hour12 属性将影响为格式化小时旋转按钮解析哪个 hourCycle。请注意,虽然这可能会影响小时旋转按钮的格式,但格式化的时间字符串结果可能会显示 'h12'h23' 格式,这是因为客户端 Intl.DateTimeFormat 对特定区域设置的支持存在限制。因此,建议将 hour12 属性设置为 null(默认值),以便显示区域设置默认时间/小时格式。

辅助功能

弹出时间支持与 <b-time> 相同的键盘控件,以及以下控件

  • Esc 将关闭弹出时间而不选择时间

在对时间选择器进行国际化时,同样重要的是使用适当的翻译字符串更新 label-* 属性,以便国际屏幕阅读器用户听到正确的提示和说明。

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

实施说明

<b-form-timepicker> 基于组件 <b-time><b-dropdown>

<b-form-timepicker> 使用 Bootstrap 的边框和 flex 实用程序类,以及按钮 (btn-*) 类、下拉 (dropdown*) 类和 form-control*(以及验证)类。BootstrapVue 的自定义 SCSS/CSS 也是时间选择器和弹出窗口正确设置样式所必需的。

另请参阅

组件参考

<b-form-timepicker>

v2.6.0+

组件别名

<b-form-timepicker> 还可以通过以下别名使用

  • <b-timepicker>

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

属性

所有属性默认值均可 全局配置

属性
(单击按升序排列)
类型
(单击按升序排列)
默认值
描述
aria-labelledby
字符串提供此组件标签的元素的 ID。用作 `aria-labelledby` 属性的值
boundary
HTMLElementString'scrollParent'菜单的边界约束:`'scrollParent'`, `'window'`, `'viewport'`, 或对 `HTMLElement` 的引用
button-only
v2.7.0+
布尔值false将日期选择器渲染为下拉按钮,而不是表单控件
button-variant
v2.7.0+
字符串'secondary'在 `button-only` 模式下使用的按钮变体。如果未设置 prop `button-only`,则无效
close-button-variant
字符串'outline-secondary'可选的 `close` 按钮使用的按钮变体
disabled
布尔值false将时间选择器置于不可交互的禁用状态
dropleft
布尔值false设置后,将菜单定位在按钮的左侧
dropright
布尔值false设置后,将菜单定位在按钮的右侧
dropup
布尔值false设置后,将菜单定位在按钮的顶部
footer-tag
字符串'footer'指定要渲染的 HTML 标签,而不是页脚的默认标签
form
字符串表单控件所属的表单的 ID。在控件上设置 `form` 属性
header-tag
字符串'header'指定要渲染的 HTML 标签,而不是页眉的默认标签
hide-header
布尔值false设置后,在视觉上隐藏选定的时间页眉
hour12
布尔值null三态 prop。如果为 `true`,则强制界面采用 12 小时制。如果为 `false`,则强制界面采用 24 小时制。如果为 `null`,则当前语言环境将确定 12 小时或 24 小时界面(默认)
id
字符串用于设置已渲染内容的 `id` 属性,并用作根据需要生成任何其他元素 ID 的基础
label-am
字符串'AM'选择“AM”时在 AM/PM 旋转按钮中显示的文本
label-ampm
字符串'AM/PM'`AM/PM` 旋转按钮上 `aria-label` 属性的值
label-close-button
字符串'关闭'`关闭` 按钮的内容
label-decrement
字符串'递减'旋转按钮 `-` 按钮上 `aria-label` 属性的值
label-hours
字符串'小时'`Hours` 旋钮上的 `aria-label` 属性的值
label-increment
字符串'增量'旋钮 `+` 按钮上的 `aria-label` 属性的值
label-minutes
字符串'分钟'`Minutes` 旋钮上的 `aria-label` 属性的值
label-no-time-selected
字符串'未选择时间'未选择时间时显示的字符串
label-now-button
字符串'立即选择'可选的 `立即选择` 按钮的内容
label-pm
字符串'下午'选择“下午”时在 AM/PM 旋钮中显示的文本
label-reset-button
字符串'重置'可选的 `重置` 按钮的内容
label-seconds
字符串'秒'`Seconds` 旋钮上的 `aria-label` 属性的值
label-selected
字符串选择时间时隐藏的 sr-only 字符串
locale
数组字符串组件使用的语言环境(或语言环境)。传入语言环境数组时,语言环境的顺序从最优到最差。如果未提供,则默认为客户端的默认语言环境
menu-class
数组对象字符串应用于弹出菜单包装器的类(或类)
minutes-step
数字字符串1分钟旋钮的步长值。应为 60 的均匀除数
name
字符串设置表单控件上 `name` 属性的值
no-close-button
布尔值false设置后,禁用显示关闭按钮
no-flip
布尔值false防止菜单自动翻转位置
now-button
布尔值false设置后,显示可选的 `立即选择` 按钮
now-button-variant
字符串'outline-primary'用于可选的 `立即选择` 按钮的按钮变体
offset
数字字符串0指定菜单移动的像素数。支持负值
placeholder
字符串未选择日期时在表单控件中显示的文本。默认为 `label-no-date-selected` 道具值
popper-opts
对象{}传递给 Popper.js 的附加配置
readonly
布尔值false将时间选择器置于交互式只读状态。禁用更新 v-model,但仍允许聚焦自旋按钮
required
布尔值false设置后,在组件上添加 `aria-required="true"` 属性。必需验证需要由应用程序处理
reset-button
布尔值false设置后,显示可选的 `reset` 按钮
reset-button-variant
字符串'outline-danger'用于可选 `reset` 按钮的按钮变体
reset-value
DateString当单击可选的 `reset` 按钮时,所选时间将设置为该值。默认清除所选值
right
布尔值false将菜单的右边缘与按钮的右边缘对齐
seconds-step
数字字符串1自旋按钮的步长值。应为可均匀除以 60 的值
show-seconds
布尔值false如果为 true,则显示自旋按钮。如果为 `false`,则不会显示自旋按钮,并且时间的秒部分始终为 `0`
size
字符串设置组件外观的大小。'sm'、'md'(默认)或 'lg'
state
布尔值null控制组件的验证状态外观。`true` 表示有效,`false` 表示无效,`null` 表示无验证状态
value
v-model
字符串''最初选中的时间值。接受 `HH:mm:ss` 字符串。有效值范围为 `00:00:00` 至 `23:59:59`

v-model

属性
事件
valueinput

插槽

名称
作用域
描述
button-content 放置在时间选择器图标按钮中的内容

事件

事件
参数
描述
context
  1. context - `b-time` 上下文对象。有关详细信息,请参阅 `b-time` 文档
`b-time` 上下文事件。当用户通过鼠标或光标控件更改任何自旋按钮值时发出。组件首次实例化或语言环境更改时也会发出
hidden v2.9.0+当选择器弹出窗口隐藏时发出
input
  1. time - `HH:mm:ss` 格式的字符串(24 小时制)
更新 v-model 时发出
shown v2.9.0+当选择器弹出窗口显示时发出

导入单个组件

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

组件
命名导出
导入路径
<b-form-timepicker>BFormTimepickerbootstrap-vue

示例

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

作为 Vue.js 插件导入

此插件包含上述所有列出的单个组件。插件还包括任何组件别名。

命名导出
导入路径
FormTimepickerPluginbootstrap-vue

示例

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