表單

BootstrapVue 表單元件和輔助元件,可選擇支援表格內嵌樣式和驗證狀態。將它們與其他 BootstrapVue 表單控制元件配對,即可輕鬆自訂且靈活的版面,並具有相容的外觀和感覺。

表單和控制項簡介

請務必對所有輸入欄位使用一個適當的 type(例如,對電子郵件地址使用 email 或對數值資訊使用 number)以利用更新的輸入控制項,如電子郵件驗證、數字選取等。

下面有一個快速範例,示範 BootstrapVue 的表單樣式。繼續閱讀以取得受支援元件、表單版面等的說明文件。

<template>
  <div>
    <b-form @submit="onSubmit" @reset="onReset" v-if="show">
      <b-form-group
        id="input-group-1"
        label="Email address:"
        label-for="input-1"
        description="We'll never share your email with anyone else."
      >
        <b-form-input
          id="input-1"
          v-model="form.email"
          type="email"
          placeholder="Enter email"
          required
        ></b-form-input>
      </b-form-group>

      <b-form-group id="input-group-2" label="Your Name:" label-for="input-2">
        <b-form-input
          id="input-2"
          v-model="form.name"
          placeholder="Enter name"
          required
        ></b-form-input>
      </b-form-group>

      <b-form-group id="input-group-3" label="Food:" label-for="input-3">
        <b-form-select
          id="input-3"
          v-model="form.food"
          :options="foods"
          required
        ></b-form-select>
      </b-form-group>

      <b-form-group id="input-group-4" v-slot="{ ariaDescribedby }">
        <b-form-checkbox-group
          v-model="form.checked"
          id="checkboxes-4"
          :aria-describedby="ariaDescribedby"
        >
          <b-form-checkbox value="me">Check me out</b-form-checkbox>
          <b-form-checkbox value="that">Check that out</b-form-checkbox>
        </b-form-checkbox-group>
      </b-form-group>

      <b-button type="submit" variant="primary">Submit</b-button>
      <b-button type="reset" variant="danger">Reset</b-button>
    </b-form>
    <b-card class="mt-3" header="Form Data Result">
      <pre class="m-0">{{ form }}</pre>
    </b-card>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        form: {
          email: '',
          name: '',
          food: null,
          checked: []
        },
        foods: [{ text: 'Select One', value: null }, 'Carrots', 'Beans', 'Tomatoes', 'Corn'],
        show: true
      }
    },
    methods: {
      onSubmit(event) {
        event.preventDefault()
        alert(JSON.stringify(this.form))
      },
      onReset(event) {
        event.preventDefault()
        // Reset our form values
        this.form.email = ''
        this.form.name = ''
        this.form.food = null
        this.form.checked = []
        // Trick to reset/clear native browser form validation state
        this.show = false
        this.$nextTick(() => {
          this.show = true
        })
      }
    }
  }
</script>

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

內嵌表單

<b-form> 中使用 inline 屬性,在單行的水平列上顯示一系列標籤、表單控制和按鈕。內嵌表單的控制與其預設狀態略有不同。

  • 控制項為 display: flex,會折疊任何 HTML 的空白,並允許您使用間距和 flexbox 工具提供對齊控制。
  • 控制項和輸入組會接收 width: auto 來覆寫啟動 Bootstrap 的預設寬度:100%。
  • 控制項僅出現在視窗至少寬 576 像素的視窗中,以考慮行動裝置上較窄的視窗。

您可能需要使用 間隔工具 手動調整各個表單控制項的寬度和對齊方式(如下所示)。最後,請務必為每個表單控制項包含 <label>,即使您需要使用 .sr-only 類別隱藏非螢幕閱讀器訪客。

<div>
  <b-form inline>
    <label class="sr-only" for="inline-form-input-name">Name</label>
    <b-form-input
      id="inline-form-input-name"
      class="mb-2 mr-sm-2 mb-sm-0"
      placeholder="Jane Doe"
    ></b-form-input>

    <label class="sr-only" for="inline-form-input-username">Username</label>
    <b-input-group prepend="@" class="mb-2 mr-sm-2 mb-sm-0">
      <b-form-input id="inline-form-input-username" placeholder="Username"></b-form-input>
    </b-input-group>

    <b-form-checkbox class="mb-2 mr-sm-2 mb-sm-0">Remember me</b-form-checkbox>

    <b-button variant="primary">Save</b-button>
  </b-form>
</div>

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

還支援自訂表單控制項和選擇器。

<div>
  <b-form inline>
    <label class="mr-sm-2" for="inline-form-custom-select-pref">Preference</label>
    <b-form-select
      id="inline-form-custom-select-pref"
      class="mb-2 mr-sm-2 mb-sm-0"
      :options="[{ text: 'Choose...', value: null }, 'One', 'Two', 'Three']"
      :value="null"
    ></b-form-select>

    <b-form-checkbox class="mb-2 mr-sm-2 mb-sm-0">Remember my preference</b-form-checkbox>

    <b-button variant="primary">Save</b-button>
  </b-form>
</div>

<!-- b-form-inline-custom.vue -->

注意:<b-form-group> 在 inline 表單中不受支援,因為這會導致配置衝突。

使用隱藏標籤的其他方法

螢幕閱讀器等協助技術如果不為每個輸入加入一個標籤,那麼您的表單可能無法正常運作。對於這些內嵌式表單,您可以使用 .sr-only 這個類別來隱藏標籤。還有其他方法可以為協助技術提供標籤,例如 aria-labelaria-labelledbytitle 屬性。如果這些屬性都不存在,協助技術可能會使用 placeholder 屬性(如果存在)作為標籤。不過請注意,不建議使用 placeholder 來取代其他標示方法。

另見

表單輔助元件

Form 外掛中提供下列輔助元件

  • <b-form-text> 輸入的輔助文字區塊
  • <b-form-invalid-feedback> 輸入 invalid 狀態下的無效回饋文字區塊
  • <b-form-valid-feedback> 輸入 valid 狀態下的有效回饋文字區塊
  • <b-form-datalist> 輕鬆為 <b-form-input> 或純文字 <input> 建立 <datalist>

表單文字輔助

使用 <b-form-text> 輔助元件,在輸入下方顯示一區塊輔助文字。文字使用灰階色顯示,字級大小稍小。

提示:輔助文字應該使用 aria-describedby 屬性與它所對應的表單控制項明確相關聯。這將確保輔助技術(例如螢幕閱讀器)在使用者對控制項進行焦點或輸入時,會宣告這段輔助文字。

<div>
  <b-form @submit.stop.prevent>
    <label for="text-password">Password</label>
    <b-form-input type="password" id="text-password" aria-describedby="password-help-block"></b-form-input>
    <b-form-text id="password-help-block">
      Your password must be 8-20 characters long, contain letters and numbers, and must not
      contain spaces, special characters, or emoji.
    </b-form-text>
   </b-form>
</div>

<!-- b-form-help-text.vue -->

回饋輔助

輔助元件 <b-form-valid-feedback><b-form-invalid-feedback> 會顯示回饋(依據輸入狀態),作為一個色塊文字。它們仰賴在輸入之後(同層級)放置,並會依據輸入的瀏覽器原生驗證狀態顯示。若要強制它們顯示,請設定 force-show 屬性為 true,或將控制項 state 連結至回饋輔助元件的 state 屬性,或在父層元素(例如表單)中設定 was-validated 類別。請參閱以下的 **驗證** 區段,以取得更多詳情。

使用選用布林屬性 tooltip,可將顯示方式從塊狀切換成靜態提示工具樣式。回饋通常會顯示在表單控制項下方。當啟用此模式,父層容器必須有 position: relative: 的 CSS 樣式或 position-relative 類別非常重要。請注意,由於提示工具樣式的回饋定位是靜態的,可能會遮蔽其他輸入、標籤等部分。

**注意事項:**有些表單控制項,例如 <b-form-radio><b-form-checkbox>、以及 <b-form-file>,有包裝元素,可能會阻止回饋文字自動顯示(因回饋元件並非表單控制項輸入項目的直接同層級)。請使用回饋元件的 state 屬性(連結至表單控制項的狀態)或 force-show 屬性,來顯示回饋。

<template>
  <div>
    <b-form  @submit.stop.prevent>
      <label for="feedback-user">User ID</label>
      <b-form-input v-model="userId" :state="validation" id="feedback-user"></b-form-input>
      <b-form-invalid-feedback :state="validation">
        Your user ID must be 5-12 characters long.
      </b-form-invalid-feedback>
      <b-form-valid-feedback :state="validation">
        Looks Good.
      </b-form-valid-feedback>
     </b-form>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        userId: ''
      }
    },
    computed: {
      validation() {
        return this.userId.length > 4 && this.userId.length < 13
      }
    }
  }
</script>

<!-- b-form-feedback-example.vue -->

資料清單輔助

對於支援 <datalist> 元素的瀏覽器,<b-form-datalist> 輔助元件允許您快速地透過傳遞至 options 屬性的陣列,來建立 <datalist> 和子層 <option> 元素。

您也可以在 <b-form-datalist> 內部手動提供 <option> 元素。它們會顯示在任何由 options 屬性產生 <option> 元素下方。

<template>
  <div>
    <label for="input-with-list">Input with datalist</label>
    <b-form-input list="input-list" id="input-with-list"></b-form-input>
    <b-form-datalist id="input-list" :options="options"></b-form-datalist>
  </div>
</template>

<script>
export default {
  data() {
    return {
      options: ['Apple', 'Banana', 'Grape', 'Kiwi', 'Orange']
    }
  }
}
</script>

<!-- b-form-datalist-example.vue -->

<b-form-datalist> 也可透過較短的別名 <b-datalist> 取用。

另見

驗證

<b-form> 上設定 novalidate 屬性為 true,以停用瀏覽器原生 HTML5 驗證。

<b-form> 上設定 validated 屬性為 true,以新增 Bootstrap v4 .was-validated 類別到表單,觸發驗證狀態

所有表單控制都支援 state 屬性,可將表單控制設定為三種內容狀態之一

  • false(表示無效狀態)非常適合在有封鎖或必填欄位時使用。使用者必須正確填寫此欄位才能提交表單。
  • true(表示有效狀態)非常適合在於在整個表單中進行逐欄位驗證,並希望引導使用者完成其餘欄位的情況。
  • null 沒有顯示驗證狀態(無論是有效還是無效)

請參閱 Bootstrap v4 表單驗證文件 以了解有關新的 Bootstrap v4 驗證狀態的詳細資訊。

驗證機制

同時使用第三方基於 Vue 的驗證函式庫和 BootstrapVue

額外資源

元件參考

<b-form>

函式元件

屬性

所有屬性預設值都可 全域設定

屬性
類型
預設值
說明
id
字串用於在呈現的內容上設定 `id` 屬性,並用作根據需要產生任何其他元素 ID 的基礎
內嵌
布林false設定後,表格將處於內嵌模式,在單一水平列中顯示標籤、表格控制和按鈕
無驗證
布林false設定時,將停用表格控制上的瀏覽器原生 HTML5 驗證
已驗證
布林false設定時,將在表格上新增 Bootstrap 類別「已驗證」,觸發原生瀏覽器驗證狀態

插槽

名稱
說明
預設值 置於表格內的內容

事件

事件
參數
說明
提交
  1. event - 原生提交事件
在提交表格時發出

<b-form-text>

函式元件

屬性

所有屬性預設值都可 全域設定

屬性
類型
預設值
說明
id
字串用於在呈現的內容上設定 `id` 屬性,並用作根據需要產生任何其他元素 ID 的基礎
內嵌
布林false設定時,將說明文字呈現為內嵌元素,而非區塊元素
標記
字串'small'指定要呈現的 HTML 標記,而非預設標記
文字變異
字串'muted'對文字套用 Bootstrap 主題顏色變異之一

插槽

名稱
說明
預設值 置於表格文字內的內容

<b-form-invalid-feedback>

函式元件

屬性

所有屬性預設值都可 全域設定

屬性
類型
預設值
說明
aria-live
字串當呈現的元素為「aria-live」區域(供螢幕朗讀機使用者使用)時,設定為「禮貌」或「主動」
強制顯示
布林false顯示說明文字,不論「狀態」屬性的值為何
id
字串用於在呈現的內容上設定 `id` 屬性,並用作根據需要產生任何其他元素 ID 的基礎
角色
字串將 ARIA 屬性「角色」設定為特定值
狀態
布林null當明確為「false」,將強制顯示說明
標記
字串'div'指定要呈現的 HTML 標記,而非預設標記
工具提示
布林false以基本的 tooltip 樣式呈現反饋文字

插槽

名稱
說明
預設值 要放置於表單無效反饋中的內容

<b-form-valid-feedback>

函式元件

屬性

所有屬性預設值都可 全域設定

屬性
類型
預設值
說明
aria-live
字串當呈現的元素為「aria-live」區域(供螢幕朗讀機使用者使用)時,設定為「禮貌」或「主動」
強制顯示
布林false顯示說明文字,不論「狀態」屬性的值為何
id
字串用於在呈現的內容上設定 `id` 屬性,並用作根據需要產生任何其他元素 ID 的基礎
角色
字串將 ARIA 屬性「角色」設定為特定值
狀態
布林null明確為「true」時,強制顯示反饋
標記
字串'div'指定要呈現的 HTML 標記,而非預設標記
工具提示
布林false以基本的 tooltip 樣式呈現反饋文字

插槽

名稱
說明
預設值 要放置於表單有效反饋元素中的內容

<b-form-datalist>

元件別名

<b-form-datalist> 也可用以下別名使用

  • <b-datalist>

注意:僅當導入 BootstrapVue 的所有部分或使用元件群組外掛程式時,才可以使用元件別名。

屬性

所有屬性預設值都可 全域設定

屬性
類型
預設值
說明
disabled-field
字串'disabled'應使用於停用狀態的 `options` 陣列中的欄位名稱
html-field
請小心使用
字串'html'替代文字欄位,應使用於 `options` 陣列中的欄位名稱,以產生 HTML 標籤
id
必填
字串用於在呈現的內容上設定 `id` 屬性,並用作根據需要產生任何其他元素 ID 的基礎
options
陣列物件[]要在元件中呈式的項目陣列
text-field
字串'text'應使用於文字標籤的 `options` 陣列中的欄位名稱
value-field
字串'value'應使用於值的 `options` 陣列中的欄位名稱

注意: 支援 HTML 字串的屬性(*-html)在傳遞使用者提供原始值時,可能會易於遭受 跨網站指令碼 (XSS) 攻擊。您必須先適當 清除 使用者輸入值!

插槽

名稱
說明
預設值 要放入資料清單的內容

導入個別元件

透過下列有命名的匯出,你可以將個別元件導入專案

元件
命名匯出
匯入路徑
<b-form>BFormbootstrap-vue
<b-form-text>BFormTextbootstrap-vue
<b-form-invalid-feedback>BFormInvalidFeedbackbootstrap-vue
<b-form-valid-feedback>BFormValidFeedbackbootstrap-vue
<b-form-datalist>BFormDatalistbootstrap-vue

範例

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

以 Vue.js 外掛程式方式導入

此外掛程式包含上方所列的所有個別元件. 外掛程式也包含所有元件別名。

命名匯出
匯入路徑
FormPluginbootstrap-vue

範例

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