表單群組

<template>
  <div>
    <b-form-group
      id="fieldset-1"
      description="Let us know your name."
      label="Enter your name"
      label-for="input-1"
      valid-feedback="Thank you!"
      :invalid-feedback="invalidFeedback"
      :state="state"
    >
      <b-form-input id="input-1" v-model="name" :state="state" trim></b-form-input>
    </b-form-group>
  </div>
</template>

<script>
  export default {
    computed: {
      state() {
        return this.name.length >= 4
      },
      invalidFeedback() {
        if (this.name.length > 0) {
          return 'Enter at least 4 characters.'
        }
        return 'Please enter something.'
      }
    },
    data() {
      return {
        name: ''
      }
    }
  }
</script>

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

標籤

使用道具 label 設定產生的 <legend> 或 <label> 元素的內容，或使用命名槽位 label，您可以選擇透過設定道具 label-sr-only 在視覺上隱藏標籤文字，同時仍然讓螢幕朗讀程式可以使用。

如果未設定 label-for 道具，<b-form-group> 將會使用 <legend> 呈現 <fieldset>。如果傳遞輸入 ID 給 label-for 道具，系統將呈現包含 <label> 的 <div>。

如果您提供id值至label-for prop (此id一定會存在<b-form-group>內含的輸入元件中)，<label>元素將會用於呈現並會取代<legend>元素，且會將for屬性設為指定的id。指定id時，不要前置#。只要您在<b-form-group>元件中具有一個單一表單輸入時，才能使用label-for prop。使用<b-form-radio-group>、<b-form-checkbox-group>、<b-form-radio>、<b-form-checkbox>或<b-form-file>元件時請勿設定label-for prop（或在同一表單群組中放置多個輸入時），因為這些輸入已包含整合的標籤元素且<legend>元素較為合適。

您也可以透過label-class prop為標籤套用額外類別，例如具有回應式內距和文字對齊的工具程式類別。label-class prop可以接受字串或字串陣列。

橫向配置

標籤在預設情況下會顯示在輸入元素的上方，但您也可以選擇在各種標準的 Bootstrap 斷點中垂直排列（標籤在輸入的左方）。

具有label-cols和label-cols-{斷點}的 prop 讓您可以指定標籤在列中應佔用的欄位數。輸入會填滿行列的剩餘寬度。此數值必須為大於0的數字。或者您可以將此 prop 設為true，以讓標籤和輸入各佔據呈現列的一半寬度（如果您自訂的 Bootstrap 中欄位數為奇數時會很方便），或者將此數值設為'auto'，以讓標籤僅佔用所需的寬度。

自 BootstrapVue v2.21.0 開始，您也可以透過content-cols和content-cols-{斷點} prop 來指定內容在列中應佔用的欄位數。

同時使用label-cols和content-cols prop 時，請確認總欄位數不會超過12。

請參閱配置和柵格系統文件，取得更多資訊。

<div>
  <div>
    <b-form-group
      id="fieldset-horizontal"
      label-cols-sm="4"
      label-cols-lg="3"
      content-cols-sm
      content-cols-lg="7"
      description="Let us know your name."
      label="Enter your name"
      label-for="input-horizontal"
    >
      <b-form-input id="input-horizontal"></b-form-input>
    </b-form-group>
  </div>
</div>

<!-- b-form-group-horizontal.vue -->

設定 label cols 為 'auto' 的功能已加入在 BootstrapVue 版本 v2.1.0 中。

標籤大小

你可以透過選配的 label-size prop 控制標籤文字大小以搭配你的輸入表單大小。值可以是 'sm' 或 'lg'，分別表示小或大標籤。大小適用於水平和非水平表單群組。

<div>
  <b-form-group label-cols="4" label-cols-lg="2" label-size="sm" label="Small" label-for="input-sm">
    <b-form-input id="input-sm" size="sm"></b-form-input>
  </b-form-group>

  <b-form-group label-cols="4" label-cols-lg="2" label="Default" label-for="input-default">
    <b-form-input id="input-default"></b-form-input>
  </b-form-group>

  <b-form-group label-cols="4" label-cols-lg="2" label-size="lg" label="Large" label-for="input-lg">
    <b-form-input id="input-lg" size="lg"></b-form-input>
  </b-form-group>
</div>

<!-- b-form-group-label-size.vue -->

標籤文字對齊

標籤文字也可以選擇對齊為 left、center 或 right，方法是設定 prop label-text-align 和/或 label-align-{breakpoint} 的對應值。

如果已設定 label-sr-only prop，則對齊不會有作用。

描述

選擇性描述文字，設定 description prop 或使用命名插槽 description 時，始終以 .text-muted 類別顯示。說明文字使用 <b-form-text> 表單子元件來呈現。

巢狀表單群組

請隨時巢狀 <b-form-group> 元件以產生進階表單配置和關聯表單控制項的語意群組

<div>
  <b-card bg-variant="light">
    <b-form-group
      label-cols-lg="3"
      label="Shipping Address"
      label-size="lg"
      label-class="font-weight-bold pt-0"
      class="mb-0"
    >
      <b-form-group
        label="Street:"
        label-for="nested-street"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-street"></b-form-input>
      </b-form-group>

      <b-form-group
        label="City:"
        label-for="nested-city"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-city"></b-form-input>
      </b-form-group>

      <b-form-group
        label="State:"
        label-for="nested-state"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-state"></b-form-input>
      </b-form-group>

      <b-form-group
        label="Country:"
        label-for="nested-country"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-country"></b-form-input>
      </b-form-group>

      <b-form-group
        label="Ship via:"
        label-cols-sm="3"
        label-align-sm="right"
        class="mb-0"
        v-slot="{ ariaDescribedby }"
      >
        <b-form-radio-group
          class="pt-2"
          :options="['Air', 'Courier', 'Mail']"
          :aria-describedby="ariaDescribedby"
        ></b-form-radio-group>
      </b-form-group>
    </b-form-group>
  </b-card>
</div>

<!-- b-form-group-nested.vue -->

停用的表單群組

設定 disabled prop 會停用顯示的 <fieldset>，而且在大部分瀏覽器上，還會停用包含在欄位組內的全部輸入元素。

當設定 label-for 時，disabled 不會有作用（由於並未顯示 <fieldset> 元素）。

驗證狀態回饋

Bootstrap 在許多表單控制項包含 valid 和 invalid 狀態的驗證樣式。

一般來說，你會想要針對特定類型的回饋使用特定的狀態

• false（表示無效狀態）適用於有區塊或必填欄位時。使用者必須正確填寫此欄位才能提交表單。
• true（表示有效狀態）適用於在整個表單都有逐欄位驗證，而且希望引導使用者完成其他欄位的情況。
• null 不顯示驗證狀態（既非有效亦非無效）

要在 <b-form-group> 中套用其中一個背景狀態圖示，請將 state prop 設定為 false（無效）、true（有效）或 null（無驗證狀態）。

Bootstrap v4 使用 :invalid 或 :valid 輸入的同層級 CSS 選擇器來顯示回饋文字。某些表單控制項（例如核取方塊、選項按鈕和檔案輸入，或輸入群組內的輸入）會包含在額外標記中，這樣回饋文字不再會是輸入的同層級，因此回饋不會顯示。在這些情況下，您需要在 <b-form-group> 及輸入上設定驗證 狀態。

如果父 <b-form> 元件沒有設定 novalidate 屬性（或設定為 false），而且設定 validated 屬性（且輸入失敗或通過原生瀏覽器驗證約束，例如 required），則會顯示回饋。有關驗證方式的詳細資訊，請參閱 Bootstrap v4 的 表單元件 說明文件。

您應始終透過 invalid-feedback 屬性（或區段）提供內容，以協助使用輔助技術的使用者在設定上下文 invalid 狀態時。

無效回饋

透過設定屬性 invalid-feedback 或使用命名區段 invalid-feedback，顯示可選的無效狀態回饋文字，以提供文字狀態回饋（支援 html）。

使用 <b-form-invalid-feedback> 表單子元件呈現無效回饋。

有效回饋

透過設定屬性 valid-feedback 或使用命名區段 valid-feedback，顯示可選的有效狀態回饋文字，以提供文字狀態回饋（支援 html）。

使用 <b-form-valid-feedback> 表單子元件呈現有效回饋。

回饋樣式

預設情況下，當回饋（有效或無效）顯示時會顯示為文字區塊。您可以變更回饋，讓它在顯示時顯示為靜態工具提示，方法是將屬性 tooltip 設定為 true。

回饋限制

注意：當在 <b-form-group> 內使用 <b-input-group>、<b-form-file>、<b-form-radio-group>、<b-form-radio>、<b-form-checkbox-group> 或 <b-form-checkbox>時，僅在 input 上設定無效（或有效）狀態 不會觸發無效（或有效）回饋顯示（這是因為 Bootstrap v4 驗證 CSS 的限制）。為了解決這個問題，您還必須在 <b-form-group> 上設定無效/有效 狀態。使用上述其中一個表單控制項時，原生瀏覽器驗證 不會觸發無效回饋顯示。

協助工具

預設情況下，當未提供 label-for 值時，<b-form-group> 會在一個 HTML <fieldset> 元素內呈現輸入控制項，其中標籤內容置於欄位集的 <legend> 元素內。根據此標記的特性，標題內容會自動與包含的輸入控制項關聯。

強烈建議在 <b-form-group> 中只有一個輸入元件時，提供您的輸入元件一個唯一的 id props，並將 label-for props 設定為此 ID。

當多個表單控制項放置在 <b-form-group> 內部時（例如一系列或單選或核取方塊輸入，或一系列相關輸入），請勿設定 label-for 的 props，因為一個標籤只能與一個輸入關聯。最理想的情況是使用預設的呈現標記，產生一個 <fieldset> + <legend> 來描述輸入群組。

當在 <b-form-group> 內放置多個表單控制項時（而且您不會巢狀 <b-form-group> 元件），建議為每個控制項提供自己關聯的 <label>（可以使用 .sr-only 類別，並在視覺上隱藏）並將標籤的 for 屬性設定為關聯輸入控制項的 id。或者，您可以設定每個輸入控制項的 aria-label 屬性，而不使用 <label>。針對 <b-form-radio> 和 <b-form-checkbox>（或群組版本），您不需要設定個別標籤，因為這些類型輸入的呈現標記已經包含一個 <label> 元件。

當 <b-form-group> 設定了 label-for 的 props，aria-describedby 屬性將自動指派給輸入。當表單群組有多個表單控制項時，請務必透過使用 ariaDescribedby 的 props，從選擇性範圍的 default 槽設定屬性，來設定每个控制项的属性。