表單時間選擇器

<b-form-timepicker> 是 BootstrapVue 自訂時間選擇器輸入表單控制項,提供完整的 WAI-ARIA 相容性和國際化支援。

BootstrapVue 自 v2.6.0 版本開始提供

概觀

作為 <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 道具將停用時間選取,但會保留元件互動功能,允許在自旋按鈕之間使用 tab 鍵切換。在唯讀狀態下,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 則會設為有效樣式。將 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-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-button,以及 label-close-button 設定。由於頁尾區寬度有限,建議這些標籤越簡短越好。

使用下拉式選單屬性 rightdropupdroprightdropleftno-flip,以及 offset 控制彈出式日曆的位置。

請參閱 <b-dropdown> 定位區段,深入了解這些屬性的效果和用法。

僅按鈕模式

v2.7.0+

想像僅有一個按鈕可以啟動時間選擇器對話框,或想要提供自己的選用文字輸入欄位?使用 button-only 屬性將時間選擇器呈現為下拉式按鈕。格式化時間標籤會用 class 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

全球使用 2 種主要的計時公約(時鐘):12 小時時鐘和 24 小時時鐘。hourCycle屬性讓你能夠存取特定語言環境所使用的時鐘類型。小時循環類型有幾個不同的值,會列在下方表格中。hourCycle指示時間'00:00:00'(一天的開始)應該如何呈現/格式化給特定語言環境中的使用者。'context'事件會包含已解析的hourCycle值。

小時循環 說明
'h12' 使用 112 的小時系統。12 小時時鐘,午夜從下午 12:00 開始
'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(旋轉按鈕)對使用者顯示的內容,具體取決於選定的語言環境

注意: 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 的邊框和彈性公用程式類別,以及按鈕 (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` 模式下使用的按鈕變體。如果 `button-only` 道具沒有設定,則不會產生效果
close-button-variant
字串'outline-secondary'要使用的按鈕變體適用於選擇性 `close` 按鈕
disabled
布林false讓時間選擇器處於非互動的停用狀態
dropleft
布林false如果設定為 true,則將功能表置於按鈕的左側
dropright
布林false設定時,將選單置於按鈕右方
dropup
布林false設定時,將選單置於按鈕上方
footer-tag
字串'footer'指定要呈現的 HTML 標籤,取代 footer 的預設標籤
form
字串表單控制項所屬的表單 ID。會在控制項上設定 `form` 屬性
header-tag
字串'header'指定要呈現的 HTML 標籤,取代 header 的預設標籤
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
字串'小時'`小時` 旋鈕按鈕的 `aria-label` 屬性值
label-increment
字串'遞增'旋鈕按鈕 `+` 按鈕的 `aria-label` 屬性值
label-minutes
字串'分鐘'`分鐘` 旋鈕按鈕的 `aria-label` 屬性值
label-no-time-selected
字串'未選取時間'未選取時間時要顯示的字串
label-now-button
字串'立即選取'用於選擇性的 `立即選取` 按鈕的內容
label-pm
字串'PM'當選取 'PM' 時,要在 AM/PM 旋鈕按鈕中顯示的文字
label-reset-button
字串'重設'用於選擇性的 `重設` 按鈕的內容
label-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-button-variant
字串'outline-danger'按鈕變型適用於選用的「重設」按鈕
reset-value
DateString按一下選用的「重設」按鈕時,選取的時間將設定為此值。預設值會清除選取的值
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` context 事件。當使用者透過滑鼠或游標控制變更任何旋鈕值時發出。元件初次實例化或變更區域設定時也會發出
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)