回報問題編輯此頁面

表單文本區域

建立多行文字輸入，支援自動高度調整、最小和最大行數、以及狀態色彩。

<template>
  <div>
    <b-form-textarea
      id="textarea"
      v-model="text"
      placeholder="Enter something..."
      rows="3"
      max-rows="6"
    ></b-form-textarea>

    <pre class="mt-3 mb-0">{{ text }}</pre>
  </div>
</template>

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

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

控制大小

使用 size props 設定文字高度為 sm 或 lg，分別代表小型或大型。

若要控制寬度，請將輸入置於標準的 Bootstrap 格線欄位中。

<b-container fluid>
  <b-row>
    <b-col sm="2">
      <label for="textarea-small">Small:</label>
    </b-col>
    <b-col sm="10">
      <b-form-textarea
        id="textarea-small"
        size="sm"
        placeholder="Small textarea"
      ></b-form-textarea>
    </b-col>
  </b-row>

  <b-row class="mt-2">
    <b-col sm="2">
      <label for="textarea-default">Default:</label>
    </b-col>
    <b-col sm="10">
      <b-form-textarea
        id="textarea-default"
        placeholder="Default textarea"
      ></b-form-textarea>
    </b-col>
  </b-row>

  <b-row class="mt-2">
    <b-col sm="2">
      <label for="textarea-large">Large:</label>
    </b-col>
    <b-col sm="10">
      <b-form-textarea
        id="textarea-large"
        size="lg"
        placeholder="Large textarea"
      ></b-form-textarea>
    </b-col>
  </b-row>
</b-container>

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

顯示行數

若要設定 <b-form-textarea> 的高度，請將 rows props 設定為期望的行數。如果未提供 rows 值，將會預設為 2（瀏覽器的預設和最小可接受值）。若設定為 null 或小於 2 的值，將會使用預設值 2。

<div>
  <b-form-textarea
    id="textarea-rows"
    placeholder="Tall textarea"
    rows="8"
  ></b-form-textarea>
</div>

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

停用調整大小控點

有些瀏覽器會允許使用者調整文字區域的高度。若要停用此功能，請將 no-resize props 設定為 true。

<div>
  <b-form-textarea
    id="textarea-no-resize"
    placeholder="Fixed height textarea"
    rows="3"
    no-resize
  ></b-form-textarea>
</div>

<!-- b-form-textarea-no-resize.vue -->

自動高度

<b-form-textarea> 也能自動調整其高度（文字列），以適應內容，即使使用者輸入或刪除文字。文字區域的高度將會隨著內容增長或縮小（最大為 max-rows，最小為 rows）。

若要設定初始最小高度（以列數表示），請將 rows 屬性設為您要顯示的行數（或讓它保留預設值 2）；接著，您可藉由將 max-rows 屬性設為最大文字行數，來設定文字區域成長達到的最大行數（在出現捲動列之前）。

若要令高度 sticky（即永遠不會縮小），請將 no-auto-shrink 屬性設為 true。如果未設定 max-rows 或小於或等於 rows，則 no-auto-shrink 屬性不會產生任何效果。

請注意，在自動高度模式下，文字區域的調整控制項（如果瀏覽器支援）會自動停用。

<b-container fluid>
  <b-row>
    <b-col sm="2">
      <label for="textarea-auto-height">Auto height:</label>
    </b-col>
    <b-col sm="10">
      <b-form-textarea
        id="textarea-auto-height"
        placeholder="Auto height textarea"
        rows="3"
        max-rows="8"
      ></b-form-textarea>
    </b-col>
  </b-row>

  <b-row class="mt-2">
    <b-col sm="2">
      <label for="textarea-no-auto-shrink">No auto-shrink:</label>
    </b-col>
    <b-col sm="10">
      <b-form-textarea
        id="textarea-no-auto-shrink"
        placeholder="Auto height (no-shrink) textarea"
        rows="3"
        max-rows="8"
        no-auto-shrink
      ></b-form-textarea>
    </b-col>
  </b-row>
</b-container>

<!-- b-form-textarea-auto-height.vue -->

自動高度實作註解

自動高度會透過 CSS 查詢來計算產生的高度，因此輸入資料必須出現在文件（DOM）中且可見（不能透過 display: none 隱藏）。系統會在掛載時計算初始高度。如果瀏覽器支援 IntersectionObserver（不論是原生或透過 polyfill），<b-form-textarea> 會利用此功能來判斷文字區域何時可見，然後計算高度。請參閱入門頁面中的 瀏覽器支援 區段。

脈絡狀態

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

一般來說，您會想要使用特定狀態來提供特定類型的回饋

  • false（表示無效狀態）非常適合用於有阻擋或必填欄位時。使用者必須正確填寫此欄位才能提交表單。
  • true（表示有效狀態）非常適合用於在整個表單中進行個別欄位驗證，且希望引導使用者完成其餘欄位的情況。
  • null 不顯示驗證狀態（既不是有效也不是無效）

若要於 <b-form-textarea> 中套用其中一個脈絡狀態圖示，請將 state 屬性設為 false（無效）、true（有效）或 null（無驗證狀態）。

<template>
  <div>
    <b-form-textarea
      id="textarea-state"
      v-model="text"
      :state="text.length >= 10"
      placeholder="Enter at least 10 characters"
      rows="3"
    ></b-form-textarea>
  </div>
</template>

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

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

傳遞脈絡狀態給輔助技術和色盲使用者

使用這些脈絡狀態來表示表單控制項狀態只會提供視覺化的、基於色彩的指示，這些指示不會傳遞給輔助技術的使用者（例如螢幕閱讀器）或色盲使用者。

請確保另外提供狀態的替代指示。例如，您可以在表單控制項 <label> 文字中加入關於狀態的提示，或提供額外的說明文字區塊。

aria-invalid 屬性

當 <b-form-textarea> 處於無效的脈絡狀態時（即 state 為 false），您可能還希望將 aria-invalid 屬性設為 true 或下列其中一個受支援的值

  • false：無錯誤（預設值）
  • true 或 'true'：值驗證失敗。
  • 'grammar'：偵測到文法錯誤。
  • 'spelling' 偵測到拼字錯誤。

如果將 state prop 設為 false，且未明確設定 aria-invalid prop，<b-form-textarea> 會自動將 aria-invalid 屬性設為 'true'。

支援格式化

<b-form-textarea> 選配支援格式化，方法是傳遞函式參照給 formatter prop。

發生格式化（提供格式化函式時）的時間為控制元件原生 input 和 change 事件觸發時。你可以使用布林 prop lazy-formatter 將格式化函式呼叫限制為控制元件原生 blur 事件。

格式化函式接收兩個引數：輸入元素的原始 value 以及觸發格式化的原生 event 物件（如可用）。

formatter 函式應回傳已格式化的值，類型為字串。

如果未提供 formatter，則不會執行格式化。

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

    <b-form-group
      label="Textarea with lazy formatter (on blur)"
      label-for="textarea-lazy"
      description="This one is a little lazy!"
      class="mb-0"
    >
      <b-form-textarea
        id="textarea-lazy"
        v-model="text2"
        placeholder="Enter your text"
        lazy-formatter
        :formatter="formatter"
      ></b-form-textarea>
    </b-form-group>
    <p class="mb-0" style="white-space: pre-line"><b>Value:</b> {{ text2 }}</p>
  </div>
</template>

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

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

注意：在非懶惰格式化下，如果游標未置於輸入值的尾端，則游標可能於輸入字元時跳到結尾。你可以使用提供的事件物件和 event.target 存取原生的輸入選取方法和屬性，以控制插入點。這留給讀者練習。

唯讀純文字

如果你希望表單中的 <b-form-textarea readonly> 元素以純文字樣式顯示，請設定 plaintext prop（無需設定 readonly，因為會自動設定），以移除預設的表單欄位樣式，並保留正確的文字大小、外框、內距和高度。

<template>
  <div>
    <b-form-textarea id="textarea-plaintext" plaintext :value="text"></b-form-textarea>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        text: "This is some text.\nIt is read only and doesn't look like an input."
      }
    }
  }
</script>

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

v-model 修改器

Vue 不正式支援 .lazy、.trim 和 .number 修改器用於自訂元件輸入的 v-model，並可能會產生不良的使用者體驗。請避免使用 Vue 的原生修改器。

為了解決此問題，<b-form-textarea> 有三個布林 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 事件回傳的值。這些事件會在 (選擇性地) 處理完格式後，回傳 <textarea> 內容的字串值 (可能與透過 v-model 的 update 事件回傳的值不同，該事件會處理修飾詞)。

防抖動支援

作為 lazy 修飾詞 prop 的替代方案，<b-form-textarea> 選擇性地支援防抖動使用者輸入，於使用者輸入最後一個字元後的一段閒置時間，或發生 change 事件更新 v-model。如果使用者在閒置時間到期前輸入一個新字元 (或刪除字元)，該時間將會重新開始。

若要啟用防抖動，請將 debounce prop 設為大於 0 的任意整數。該值以毫秒為單位。將 debounce 設為 0 將會停用防抖動。

注意：如果 lazy prop 已設定，則不會發生防抖動。

<template>
  <div>
    <b-form-textarea v-model="value" debounce="500" rows="3" max-rows="5"></b-form-textarea>
    <pre class="mt-2 mb-0">{{ value }}</pre>
  </div>
</template>

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

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

自動聚焦

當 autofocus prop 在 <b-form-textarea> 上設定時，在文檔中插入 (亦即掛載) 或於 Vue <keep-alive> 組件中重新激活 textarea 時，textarea 將會自動聚焦。注意：這個 prop 並未設定 textarea 上的 autofocus 屬性，它也不會知道 textarea 何時會變為可見。

原生和自訂事件

所有原生事件 (除了自訂 input 與 change 事件外) 都受支援，不需要 .native 修飾詞。

自訂 input 與 change 事件會收到當前 value 的單一引數 (經過任何格式處理後)，並由使用者的互動觸發。

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

你可以使用 .native 修飾詞隨時存取原生 input 與 change 事件。

公開的輸入屬性和方法

<b-form-textarea> 揭露元件參考上的幾個原生輸入元素屬性與方法（例：指定 ref 給您的 <b-form-textarea 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/en-US/docs/Web/API/HTMLInputElement 以進一步瞭解這些方法與屬性。支援度會依據輸入類型而有差異。

元件參考

<b-form-textarea>

查看原始碼

元件別名

<b-form-textarea> 可透過下列別名使用

  • <b-textarea>

注意：僅在匯入全套 BootstrapVue 或使用元件群組外掛時才可以使用元件別名。

屬性

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

屬性
（按一下以升冪排序）
類型
（按一下以升冪排序）
預設
描述
aria-invalid
Boolean 或 Stringfalse使用指定值設定 'aria-invalid' 屬性
autocomplete
字串設定表單控制項上的 'autocomplete' 屬性值
autofocus
布林值false設定為 `true` 時，會嘗試在元件掛載或在 keep-alive 中重新啟動時，自動對焦該控制項。不會對控制項設定 `autofocus` 屬性
debounce
v2.1.0+ 		數字 或 字串0設定為大於 0 毫秒的數字，可延遲使用者的輸入。如果 `lazy` 道具已設定，則不會生效
disabled
布林值false設定為 `true` 時，會停用元件功能並使其進入停用狀態
form
字串表單 ID，該表單控制項屬於該 ID。在控制項上設定 `form` 屬性
formatter
函式指向用於格式化文字區塊的函式的參考
id
字串用於設定已呈示內容的 `id` 屬性，並用作為基底以產生其他必要的元素 ID
lazy
v2.1.0+ 		布林值false設定時，將在 'change'/'blur' 事件上更新 v-model，而非在 'input' 上。模擬 Vue '.lazy' v-model 修飾詞
lazy-formatter
布林值false如果已設定，則於失去焦點時，而不是每個按鍵都按壓時，格式化文字區域 (如果已指定格式化程式).
max-rows
數字 或 字串要顯示的最大列數。當提供時，文字區域將「增長」 (或「收縮」) 以配合內容，直到最大列數
name
字串設定表單控制項上的 `name` 屬性的值
no-auto-shrink
布林值false當設定時，會防止自動高度的文字區域收縮以因應內容
no-resize
布林值false當設定時，會停用瀏覽器的調整大小控制項，以防止使用者更改文字區域的高度。於自動高度模式時自動設定
number
布林值false當設定時，會嘗試將輸入值轉換為原生數字。模擬 Vue '.number' v-model 修改器
placeholder
字串設定表單控制項上的 `placeholder` 屬性值
plaintext
布林值false將表單控制項設定為唯讀，並將控制項呈現為純文字 (無邊框) 的外觀
readonly
布林值false設定表單控制項上的 `readonly` 屬性
required
布林值false將 `required` 屬性加入表單控制項
rows
數字 或 字串2要顯示的最小列數。必須為大於 1 的值
size
字串設定組成元件的外觀大小。'sm'、'md' (預設) 或 'lg'
state
布林值null控制組成元件的驗證狀態外觀。`true` 表示有效，`false` 表示無效，或 `null` 表示無驗證狀態
trim
布林值false當設定時，會將輸入值的前導空白和尾隨空白裁剪。模擬 Vue '.trim' v-model 修改器
value
v-model 		數字 或 字串''文字區域的目前值。結果總是字串，但使用 'number' 屬性時除外
wrap
字串'soft'要置於文字區域的 'wrap' 屬性上的值。控制換行符號如何回傳

v-model

屬性
事件
valueupdate

事件

事件
參數
描述
blur
  1. event - 原生模糊事件 (在發生任何格式化之前)
文字區域失去焦點後發出
change
  1. value - 文字區域的目前值
由使用者互動觸發的變更事件。於任何格式化 (不包括 'trim' 或 'number' 屬性) 和更新 v-model 之後發出
input
  1. value - 文字區域的目前值
由使用者互動觸發的輸入事件。於任何格式化 (不包括 'trim' 或 'number' 屬性) 和更新 v-model 之後發出
update
  1. value - 文字區域的值，在任何格式化後。如果值未改變，則不發出
發出以更新 v-model

匯入個別組件

您可以透過以下命名匯出，將個別組件匯入至專案

組件
命名匯出
匯入路徑
<b-form-textarea>BFormTextareabootstrap-vue

範例

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

以 Vue.js 外掛程式匯入

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

命名匯出
匯入路徑
FormTextareaPluginbootstrap-vue

範例

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