表單輸入

建立不同類型的輸入，例如： text, password, number, url, email, search, range, date 等。

<template>
  <div>
    <b-form-input v-model="text" placeholder="Enter your name"></b-form-input>
    <div class="mt-2">Value: {{ text }}</div>
  </div>
</template>

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

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

輸入類型

<b-form-input> 預設為 text 輸入，但是你可以設定 type 道具為下列所支援的原生瀏覽器 HTML5 類型： text, password, email, number, url, tel, search, date, datetime, datetime-local, month, week, time, range 或 color。

<template>
  <b-container fluid>
    <b-row class="my-1" v-for="type in types" :key="type">
      <b-col sm="3">
        <label :for="`type-${type}`">Type <code>{{ type }}</code>:</label>
      </b-col>
      <b-col sm="9">
        <b-form-input :id="`type-${type}`" :type="type"></b-form-input>
      </b-col>
    </b-row>
  </b-container>
</template>

<script>
  export default {
    data() {
      return {
        types: [
          'text',
          'number',
          'email',
          'password',
          'search',
          'url',
          'tel',
          'date',
          'time',
          'range',
          'color'
        ]
      }
    }
  }
</script>

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

如果將 type 道具設定為非受支援的輸入類型（見上），將會呈現 text 輸入，並在主控台發出警告訊息。

輸入類型注意事項

並非所有瀏覽器都支援所有輸入類型，有些類型在不同種類／版本的瀏覽器中，呈現的格式也不同。請參閱 Can I use。
不支援特定類型的瀏覽器會改用 text 輸入類型（即使呈現的 type 屬性標記顯示要求的類型）。
系統並未測試要求的輸入類型是否受瀏覽器支援。
Chrome在26版本、Opera在15版本、Safari在iOS 7中，均停止支援datetime。由於應不建議使用datetime，改為使用兩個獨立的輸入欄位date及time。
date及time輸入欄位屬於原生的瀏覽器類型，並非自訂日期/時間選擇器。
在支援日期和時間樣式輸入欄位的情況，GUI中顯示的值可能與其值傳回的值不同（即：年-月-日的順序）。
無論採用何種類型的輸入欄位，值永遠都會傳回成字串形式。
v-model.lazy不受到<b-form-input>（或任何自訂的Vue元件）支援。請改用lazy屬性。
v-model修改器.number及.trim可能會在使用者輸入時導致游標跳動（這是Vue在自訂元件上使用v-model時所發生的問題）。請避免使用這些修改器。改用number或trim屬性。
較舊版的Firefox可能不支援對range類型輸入欄位使用readonly。
不支援min、max及step（例如：text、password、tel、email、url等）的輸入類型，如果提供這些值，系統會默默忽略（不過仍然會呈現在輸入標記上）。

預測文字輸入和IME組成輸入的注意事項

當使用預測文字自動建議單字，v-model不會更新，直到選取自動建議的單字（或輸入一個空格）。如果未選取自動建議的單字，當失去輸入欄位焦點時，v-model會更新為輸入欄位中目前顯示的文字。
當使用IME組成（例如：中文、日文等），v-model不會更新，直到IME組成完成。

範圍類型輸入欄位

使用range輸入類型，會以Bootstrap v4的.custom-range類別進行渲染。在各種瀏覽器上，進度條（背景）和滑塊（值）的樣式都會相同。

範圍輸入欄位對於min和max的內含值分別為0和100。你可以使用min和max屬性來指定新的值。

<template>
  <div>
    <label for="range-1">Example range with min and max</label>
    <b-form-input id="range-1" v-model="value" type="range" min="0" max="5"></b-form-input>
    <div class="mt-2">Value: {{ value }}</div>
  </div>
</template>

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

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

預設情況下，範圍輸入欄位會「吸附」到整數值。如要變更這個設定，你可以指定一個step值。在下方的範例中，我們使用step="0.5"將步驟數加倍。

<template>
  <div>
    <label for="range-2">Example range with step value</label>
    <b-form-input id="range-2" v-model="value" type="range" min="0" max="5" step="0.5"></b-form-input>
    <div class="mt-2">Value: {{ value }}</div>
  </div>
</template>

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

<!-- b-form-input-range-step.vue -->

注意：範圍輸入欄位（與所有輸入類型相同）會傳回其值為字串。你可能需要使用Number(value)、parseInt(value, 10)、parseFloat(value)將值轉換成原生數字，或使用number屬性。

注意：Bootstrap v4 CSS未包含輸入群組中範圍輸入欄位的樣式，或範圍輸入欄位的驗證樣式。然而，BootstrapVue會包含自訂樣式，以便在Bootstrap v4加入樣式前，來處理這些情況。

控制大小

使用 size prop 將高度設為 sm 或 lg，分別表示小或大。

要控制寬度，將輸入欄位置入標準 Bootstrap 網格欄位中。

<b-container fluid>
  <b-row class="my-1">
    <b-col sm="2">
      <label for="input-small">Small:</label>
    </b-col>
    <b-col sm="10">
      <b-form-input id="input-small" size="sm" placeholder="Enter your name"></b-form-input>
    </b-col>
  </b-row>

  <b-row class="my-1">
    <b-col sm="2">
      <label for="input-default">Default:</label>
    </b-col>
    <b-col sm="10">
      <b-form-input id="input-default" placeholder="Enter your name"></b-form-input>
    </b-col>
  </b-row>

  <b-row class="my-1">
    <b-col sm="2">
      <label for="input-large">Large:</label>
    </b-col>
    <b-col sm="10">
      <b-form-input id="input-large" size="lg" placeholder="Enter your name"></b-form-input>
    </b-col>
  </b-row>
</b-container>

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

注意： 除非將輸入類型 range 置入具有已設定 size prop 的 <b-input-group> 內，否則目前不支援控制大小。

注意：原生 HTML <input> 屬性 size（以字元在 <input> 中設定水平寬度）不受支援。請使用樣式、工具類別或版面列 (<b-row>) 和欄位 (<b-col>) 來設定所需寬度。

情境狀態

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

一般來說，您會希望對特定類型的回饋使用特定狀態

false（表示無效狀態）非常適合在欄位遭封鎖或為必填欄位時使用。使用者必須妥善填寫此欄位才能提交表單。
true（表示有效狀態）在您於表單中進行每個欄位的驗證，並希望引導使用者完成其餘欄位時，是理想的選擇。
null 不顯示驗證狀態（既非有效也非無效）

若要將情境狀態圖示套用至 <b-form-input>，請將 state prop 設定為 false（無效）、true（有效）或 null（無驗證狀態）。

<b-container fluid>
  <b-row class="my-1">
    <b-col sm="3">
      <label for="input-none">No State:</label>
    </b-col>
    <b-col sm="9">
      <b-form-input id="input-none" :state="null" placeholder="No validation"></b-form-input>
    </b-col>
  </b-row>

  <b-row class="my-1">
    <b-col sm="3">
      <label for="input-valid">Valid State:</label>
    </b-col>
    <b-col sm="9">
      <b-form-input id="input-valid" :state="true" placeholder="Valid input"></b-form-input>
    </b-col>
  </b-row>

  <b-row class="my-1">
    <b-col sm="3">
      <label for="input-invalid">Invalid State:</label>
    </b-col>
    <b-col sm="9">
      <b-form-input id="input-invalid" :state="false" placeholder="Invalid input"></b-form-input>
    </b-col>
  </b-row>
</b-container>

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

實際範例

<template>
  <div role="group">
    <label for="input-live">Name:</label>
    <b-form-input
      id="input-live"
      v-model="name"
      :state="nameState"
      aria-describedby="input-live-help input-live-feedback"
      placeholder="Enter your name"
      trim
    ></b-form-input>

    <!-- This will only be shown if the preceding input has an invalid state -->
    <b-form-invalid-feedback id="input-live-feedback">
      Enter at least 3 letters
    </b-form-invalid-feedback>

    <!-- This is a form text block (formerly known as help block) -->
    <b-form-text id="input-live-help">Your full name.</b-form-text>
  </div>
</template>

<script>
  export default {
    computed: {
      nameState() {
        return this.name.length > 2 ? true : false
      }
    },
    data() {
      return {
        name: ''
      }
    }
  }
</script>

<!-- b-form-input-states-feedback.vue -->

提示：使用 <b-form-group> 组件可自動產生類似上面的標記。

向輔助科技和色盲使用者傳達情境狀態

僅使用這些情境狀態表示表單控制項的狀態，只會提供一個視覺的、基於顏色的指示，這不會傳達給輔助技術（例如螢幕閱讀器）的用戶或色盲用戶。

請確保也提供了狀態的替代指示。例如，您可以在表單控制項的 <label> 文字中包含有關狀態的提示，或提供額外說明文字方塊。

ARIA `aria-invalid` 屬性

特別對於輔助技術，無效的表單控制項也可以指派 aria-invalid="true" 屬性。

當 <b-form-input> 具有無效的情境狀態（即狀態為 false）時，您可能還希望將 <b-form-input> prop aria-invalid 設定為 true，或設定為下列其中一個支援的值

false：傳達未偵測到錯誤（預設值）
true（或 'true'）：傳達該值未通過驗證。
'grammar' 傳達已偵測到語法錯誤。
'spelling' 傳達已偵測到拼字錯誤。

如果 aria-invalid 沒有明確設定，且 state 已設定為 false，則輸入欄位上的 aria-invalid 屬性會自動設定為 'true'；

格式器支援

<b-form-input> 可選擇支援格式設定，方法是傳遞函式參考至 formatter 屬性。

格式設定（當提供格式器函式時）會在控制項的原生 input 和 change 事件觸發時發生。你可以使用布林屬性 lazy-formatter 將格式器函式限制為只能在控制項的原生 blur 事件中呼叫。

formatter 函式接收兩個引數：輸入元素的原始 value 和觸發格式設定的原生 event 物件（如果有的話）。

formatter 函式應該傳回經過格式化的值，這個值必須是字串。

如果沒有提供 formatter，則不會進行格式設定。

<template>
  <div>
    <b-form-group
      label="Text input with formatter (on input)"
      label-for="input-formatter"
      description="We will convert your name to lowercase instantly"
      class="mb-0"
    >
      <b-form-input
        id="input-formatter"
        v-model="text1"
        placeholder="Enter your name"
        :formatter="formatter"
      ></b-form-input>
    </b-form-group>
    <p><b>Value:</b> {{ text1 }}</p>

    <b-form-group
      label="Text input with lazy formatter (on blur)"
      label-for="input-lazy"
      description="This one is a little lazy!"
      class="mb-0"
    >
      <b-form-input
        id="input-lazy"
        v-model="text2"
        placeholder="Enter your name"
        lazy-formatter
        :formatter="formatter"
      ></b-form-input>
    </b-form-group>
    <p class="mb-0"><b>Value:</b> {{ text2 }}</p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        text1: '',
        text2: ''
      }
    },
    methods: {
      formatter(value) {
        return value.toLowerCase()
      }
    }
  }
</script>

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

注意：當使用非文字類型的輸入（例如 color、range、date、number、email 等）時，請確定你的格式器函式傳回的是預期格式（date -> '2000-06-01'、color -> '#ff0000' 等）的輸入類型。格式器必須傳回的值是字串。

注意：對於非延遲格式設定，如果游標不在輸入值尾端，則在字元輸入後游標可能會跳到尾端。你可以使用提供的事件物件和 event.target 存取原生輸入的選擇方法和屬性，以控制插入點的位置。這部分請讀者自行練習。

只讀純文字

如果你希望讓你的表單中 <b-form-input readonly> 元素呈現純文字樣式，請設定 plaintext 屬性（不需要設定 readonly），以移除預設表單欄位樣式並保留正確的外邊距和內邊距。

plaintext 選項不支援 color 或 range 輸入類型。

停用數值類別輸入的滑鼠滾輪事件

在某些瀏覽器上，當數值類別的輸入獲得焦點時，滾動滑鼠滾輪將會增加或減少輸入的值。若要停用此瀏覽器功能，只需要將 no-wheel 屬性設定為 true 即可。

資料清單支援

資料清單是一種原生 HTML 標籤 <datalist>，包含一列 <option> 標籤。透過賦予資料清單標籤一個 ID，可以透過新增 list 屬性，從文字輸入參照此清單。

這會讓輸入欄位擁有組合方塊或自動完成的功能，讓你可以選擇現有的值或是輸入新值。

<template>
  <div>
    <b-form-input list="my-list-id"></b-form-input>

    <datalist id="my-list-id">
      <option>Manual Option</option>
      <option v-for="size in sizes">{{ size }}</option>
    </datalist>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        sizes: ['Small', 'Medium', 'Large', 'Extra Large']
      }
    }
  }
</script>

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

BootstrapVue 提供表單輔助元件 <b-form-datalist> 方便使用一組選項，快速建立 <datalist>。

注意事項

Datalist 配合瀏覽器內建的自動完成功能運作，會先顯示 datalist 選項，再顯示自動完成選項。若要只顯示 datalist 選項，請在 <b-form-input> 中設定 autocomplete="off"。
Datalist 無法套用在有下列輸入類型的輸入欄位上：password、range 或 color。
並非所有瀏覽器都完全支援 <datalist>，而且實作可能會有漏洞。建議將 datalist 視為一種加值功能，目前不宜依賴它。請查看 Can I use，了解所有瀏覽器對它的完整支援詳細資料。

`v-model` 修飾詞

Vue 沒有正式支援自訂元件輸入的 v-model 上的 .lazy、.trim 和 .number 修飾詞，而且可能會產生不良的使用者體驗。請避免使用 Vue 的原生修飾詞。

為了解決這個問題，<b-form-input> 有三個布林值 prop：trim、number 和 lazy，分別模擬原生 Vue v-model 修飾詞 .trim 和 .number，以及 .lazy。 lazy prop 會在 change/blur 事件中更新 v-model。

注意事項

number prop 的優先順序高於 trim prop（也就是說，當設定 number 時，trim 不會產生任何效應）。
在使用 number prop 時，如果可以將該值解析成數字（透過 parseFloat），它會傳回 Number 類型的值傳回 v-model，否則傳回原始輸入值，類型為 String。這與原生 .number 修飾詞的行為相同。
trim 和 number 修飾詞 prop 不會影響 input 或 change 事件傳回的值。這些事件將會在選用格式化處理後（可能會與透過 v-model update 事件傳回的值不同，而後者會處理修飾詞）傳回 <textarea> 內容的字串值。

防呆支援

除了 lazy 修飾詞 prop，<b-form-input> 還支援使用者輸入的防呆功能，當使用者輸入最後一個字元後經過一段閒置時間（或發生 change 事件），即可更新 v-model。如果使用者在閒置時間超時前輸入新的字元（或刪除字元），超時時間將會重新開始計算。

要啟用防呆功能，請將 prop debounce 設定為大於 0 的任何整數。這個值以毫秒為單位。將 debounce 設定為 0 會停用防呆功能。

備註：如果設定 lazy 屬性，則不會發生延遲。

<template>
  <div>
    <b-form-input v-model="value" type="text" debounce="500"></b-form-input>
    <div class="mt-2">Value: "{{ value }}"</div>
  </div>
</template>

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

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

自動對焦

當設定 autofocus 屬性時，在插入 (即掛載) 到文件或在 Vue <keep-alive> 元件內部重新啟用時，輸入會自動對焦。請注意，此屬性未設定輸入的 autofocus 屬性，也無法判斷輸入何時會可見。

原生和自訂事件

支援所有原生事件 (除了自訂 input 和 change 事件)，毋須使用 .native 修飾詞。

自訂 input 和 change 事件會接收一個當前 value (套用任何格式化之後) 的單一引數，並由使用者的互動觸發。

自訂 update 事件會傳入輸入值，並在 v-model 需要更新時發出 (它會在 input、change 和 blur 之後視需要發出)。

使用 .native 修飾詞，你總是可以存取原生 input 和 change 事件。

公開的輸入屬性和方法

<b-form-input> 在元件參考上公開一些原生輸入元素的屬性和方法 (即，將 ref 指派給 <b-form-input ref="foo" ...>，並使用 this.$refs['foo'].propertyName 或 this.$refs['foo'].methodName(...))。

輸入屬性

屬性	注意事項
`.selectionStart`	讀取/寫入
`.selectionEnd`	讀取/寫入
`.selectionDirection`	讀取/寫入
`.validity`	唯讀
`.validationMessage`	唯讀
`.willValidate`	唯讀

輸入方法

方法	注意事項
`.focus()`	將輸入對焦
`.blur()`	移除輸入的對焦
`.select()`	選取輸入內的全部文字
`.setSelectionRange()`
`.setRangeText()`
`.setCustomValidity()`
`.checkValidity()`
`.reportValidity()`

請參閱 https://developer.mozilla.org/zh-TW/docs/Web/API/HTMLInputElement 以了解這些方法和屬性的更多資訊。支援度會依據輸入類型而有所不同。

改用 HTML5 `<input>` 作為替代方案

如果你只需要具有基本 Bootstrap 造型的簡單輸入，你可以簡單地使用以下方式

<template>
  <div>
    <input v-model="value" type="text" class="form-control">
    <br>
    <p>Value: "{{ value }}"</p>
  </div>
</template>

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

<!-- native-input.vue -->

元件參考

`<b-form-input>`

查看原始碼

<b-form-input> 元件別名
<b-form-input> 屬性
<b-form-input> v-model
<b-form-input> 事件

元件別名

<b-form-input> 也可以透過以下別名使用

<b-input>

注意：僅在匯入所有 BootstrapVue 或使用組件群組外掛程式時，才提供組件別名。

屬性

所有預設屬性值可以在全域設定。

屬性 (按一下以由小至大排序)	類型 (按一下以由小至大排序)	預設值	說明
`aria-invalid`	`布林值` 或 `字串`	`false`	設定「aria-invalid」屬性，並指定值
`autocomplete`	`字串`		設定表單控制項上的「autocomplete」屬性值
`autofocus`	`布林值`	`false`	設為「true」時，將嘗試在裝載控制項時自動為其對焦，或者在處於 keep-alive 中時重新啟用。不會在控制項上設定「autofocus」屬性
`debounce` v2.1.0+	`數字` 或 `字串`	`0`	將其設為大於零的毫秒數時，將暫緩使用者輸入。如果設定「lazy」屬性，則不會產生作用
`disabled`	`布林值`	`false`	將其設為「true」時，會停用組件功能，使其處於停用狀態
`form`	`字串`		表單控制項所屬的表單 ID。會在控制項上設定「form」屬性
`formatter`	`函式`		用於格式化輸入的函式參考
`id`	`字串`		用於設定已呈現內容上的「id」屬性，並用作在需要時產生任何額外元素 ID 的基礎
`lazy` v2.1.0+	`布林值`	`false`	設定時，將在「change」/「blur」事件（而非「input」）上更新 v-model。模擬 Vue「.lazy」v-model 修改器
`lazy-formatter`	`布林值`	`false`	設定時，會在失去焦點時（而不是每次鍵盤輸入時）格式化輸入（如果已指定格式化器）
`list`	`字串`		關聯 datalist 元素或組件的 ID
`max`	`數字` 或 `字串`		用於設定輸入上「max」屬性的值。數字型輸入會使用
`min`	`數字` 或 `字串`		用於設定輸入上「min」屬性的值。數字型輸入會使用
`name`	`字串`		設定表單控制項上「name」屬性的值
`no-wheel`	`布林值`	`false`	對於數字型輸入，停用滑鼠滾輪增量或遞減數值
`number`	`布林值`	`false`	設定時，會嘗試將輸入值轉換為原生數字。模擬 Vue「.number」v-model 修改器
`placeholder`	`字串`		設定表單控制項上「placeholder」屬性。
`plaintext`	`布林值`	`false`	設定表單控制項為唯讀，並將控制項呈現為純文字（無邊框）
`readonly`	`布林值`	`false`	在表單控制項上設定「readonly」屬性
`required`	`布林值`	`false`	將「required」屬性新增到表單控制項
`size`	`字串`		設定組件外觀的大小。「sm」、「md」（預設）或「lg」
`state`	`布林值`	`null`	控制組件的驗證狀態外觀。有效為「true」、無效為「false」、無驗證狀態為「null」
`step`	`數字` 或 `字串`		用於設定輸入上「step」屬性的值。數字型輸入會使用
`trim`	`布林值`	`false`	設定時，會將輸入值中開頭和結尾的空白字元刪除。模擬 Vue「.trim」v-model 修改器
`type`	`字串`	`'text'`	要呈現的輸入類型。請參閱文件，了解支援的類型
`value` v-model	`數字` 或 `字串`	`''`	輸入的目前值。結果永遠會是字串，除非使用「number」屬性

`v-model`

屬性	事件
`value`	`更新`

事件

事件	參數	說明
`模糊`	`事件` - 原生模糊事件（在任何格式化操作前）	在輸入失去焦點後發出
`變更`	`值` - 輸入的當前值	由使用者互動觸發的變更事件。在任何格式化操作（不包括「修剪」或「數字」屬性）後，以及在更新 v-model 之後發出
`輸入`	`值` - 輸入的當前值	由使用者互動觸發的輸入事件。在任何格式化操作（不包括「修剪」或「數字」屬性）後，以及在更新 v-model 之後發出
`更新`	`值` - 輸入的值，經過任何格式化操作後。若值未變更則不會發出	針對更新 v-model 而發出

導入個別元件

你可以透過下列指定匯出將個別元件導入到你的專案中

元件	指定匯出	導入路徑
`<b-form-input>`	`BFormInput`	`bootstrap-vue`

範例

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

作為 Vue.js 外掛程式導入

此外掛程式包含上述列出的所有個別元件. 外掛程式也會包含任何元件別名。

指定匯出	導入路徑
`FormInputPlugin`	`bootstrap-vue`

範例

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