表单内时间控件(Form Timepicker)

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

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

<b-form-timepicker> 组件在 BootstrapVue 版本 v2.6.0 中引入。

Value: ''
<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>

v-model 返回值

<b-form-timepicker> 始终以 'HH:mm:ss' 的格式返回字符串,该字符串与本机浏览器 <input type="time"> 控件返回的格式相同。该值的范围是从 '00:00:00''23:59:59'(使用 'h23' 小时周期语法的24小时制)。

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

禁用和只读状态

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

设置 readonly 属性将禁用选择时间,但将保持组件的交互性,从而允许在旋转按钮之间进行切换。v-model 不会以只读状态更新。

Select time picker interactive state
<template>
  <div>
    <b-form-group label="Select time 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-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> 通过布尔 state 属性支持无效和有效的样式。将 state 设置为 boolean false 会将输入设置为无效,而将其设置为 boolean true 会将其设置为有效。 将 state 设置为 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>

样式

启用秒旋转按钮

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

Value: ''
<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> 控件吗?对于较小的表单控件,将 size 属性设置为 'sm' ,对于较大的表单控件,将 size 属性设置为 'lg' 。请注意,这不会影响弹出时间选择对话框的大小。

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

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

占位符

如果未选择日期,则通过 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" local="en"></b-form-timepicker>
  </div>
</template>

可选控件

通过 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>

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

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

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

国际化

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

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

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

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

Value: ''

Context:

{
  "locale": "en-US",
  "isRTL": false,
  "hourCycle": "h12",
  "hour12": true,
  "hours": null,
  "minutes": null,
  "seconds": null,
  "value": "",
  "formatted": "No time selected"
}
<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>

理解 hourCycle

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

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

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

注意: IE 11 不支持 解析语言环境的 hourCycle 值,因此我们基于解析的 hour12 值假设 h12h23

强制 12 或 24 小时界面

12小时还是24小时输入是由客户端浏览器的默认语言环境(或从 locale 属性解析的语言环境)确定的。要强制使用12小时的用户界面,请将 hour12 属性设置为 true 。要强制使用24小时用户界面,请将 hour12 属性设置为 falsehour12 属性的默认值为 null ,它使用解析的语言环境来确定要使用的接口。

hour12 属性的设置将影响解析哪个 hourCycle 以格式化小时数调节按钮。请注意,尽管这 可能 会影响小时按钮的格式,但是由于客户端 Intl.DateTimeFormat 对特定语言环境的支持的限制,格式化的时间字符串结果可能会显示 'h12'h23' 格式。因此,建议将 hour12 属性设置为 null(默认值),以便显示语言环境默认的时间/小时格式。

辅助功能

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

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

在国际化时间选择器时,同样重要的是,还要使用适当的翻译字符串来更新 label-* 道具,以便国际屏幕阅读器用户能够听到正确的提示和描述。

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

实施说明

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

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

正确选择时间选择器和弹出窗口的样式也需要 BootstrapVue 的自定义 SCSS / CSS。

另请参阅

组件引用

<b-form-timepicker>

v2.6.0+

组件别名

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

  • <b-timepicker>

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

属性

属性 (Click to sort Ascending) 类型 默认值 描述
id String 用于在渲染的内容上设置“id”属性,并用作根据需要生成任何其他元素ID的基础
value v-model String 最初选择的时间值。接受“HH:mm:ss”字符串。 有效值范围是从“00:00:00”到“23:59:59”
reset-value String 单击可选的“reset”按钮时,所选时间将设置为此值。默认是清除选择的值
placeholder String 当未选择日期时,文本将显示在表单控件中。默认为“label-no-date-selected”属性值
size String 设置组件外观的大小。'sm','md'(默认)或'lg'
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”表示无验证状态
hour12 Boolean Tri-state 属性。如果为true,则强制接口为12小时格式。如果为false,则将界面强制设置为24小时格式。如果为null,则当前语言环境将确定12或24小时界面(默认)
locale String or Array 要使用的组件的语言环境。当传递语言环境数组时,语言环境的顺序从最优选到最不优选。如果未提供,则默认为客户端默认语言环境
show-seconds Boolean false 如果为true,则显示秒旋转按钮。如果为false,则不会显示秒旋转按钮,并且时间的秒部分将始终为0。
hide-header Boolean false 设置后,可视地隐藏选定的日期标题
seconds-step Number or String 1 秒旋钮的步长值。应该将一个值平均分为60
minutes-step Number or String 1 分钟旋钮的步长值。应该将一个值平均分为60
now-button Boolean false 设置后,显示可选的“select now”按钮
label-now-button String 'Select now' 可选“select now”按钮的内容
now-button-variant String 'outline-primary' 用于可选的“select now”按钮的按钮变量
reset-button Boolean false 设置后,显示可选的“reset”按钮
label-reset-button String 'Reset' 可选的“reset”按钮的内容
reset-button-variant String 'outline-danger' 用于可选的“reset”按钮的按钮变量
no-close-button Boolean false 设置后,禁用显示关闭按钮
label-close-button String 'Close' “Close”按钮的内容
close-button-variant String 'outline-secondary' 用于可选的“close”按钮的按钮变量
label-selected String 'Selected time' 选择时间时隐藏的 sr-only 字符串
label-no-time-selected String 'No time selected' 未选择时间时显示的字符串
label-hours String 'Hours' Hours 旋钮上的 aria-label 属性的值
label-minutes String 'Minutes' “Minutes”微调按钮上“aria-label”属性的值
label-seconds String 'Seconds' Seconds 标签上的“ aria-label”属性的值
label-ampm String 'AM/PM' “AM / PM”按钮上的“aria-label”属性的值
label-am String 'AM' 选择“AM”时在AM / PM旋转按钮中显示的文本
label-pm String 'PM' 选择“PM”时在AM / PM旋转按钮中显示的文本
label-increment String 'Increment' 旋转按钮“+”按钮上的“ aria-label”属性的值
label-decrement String 'Decrement' 旋转按钮“-”按钮上的“aria-label”属性的值
menu-class String or Array or Object 应用于弹出菜单包装的一个或多个类
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

插槽

插槽名称 描述 范围
button-content 放置在时间选择器图标按钮中的内容

事件

事件 参数 描述
input
  1. time - 以HH:mm:ss格式(24小时格式)的字符串
更新 v-model 时发出
context
  1. context - `b-time`上下文对象。有关详细信息,请参见`b-time`文档。
上下文事件。当用户通过鼠标或光标控件更改任何 Spinbutton【旋转按钮】值时发出。在首次实例化组件或更改语言环境时也发出

导入单个组件

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

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

示例:

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

导入为Vue.js插件

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

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

示例:

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