表單自旋按鈕

自旋按鈕是 BootstrapVue 自訂數字範圍表單控制項。自旋按鈕允許在最小數字和最大數字的範圍內增加或減少數字值，並提供選用步驟值。

從 BootstrapVue 2.5.0 版開始提供

概觀

元件 <b-form-spinbutton> 符合 WAI-ARIA 規範，允許透過鍵盤控制，且同時支援水平（預設）和垂直配置。

類似的範圍類型輸入，BootstrapVue 的 <b-form-spinbutton> 不允許 使用者輸入值。

<template>
  <div>
    <label for="demo-sb">Spin Button</label>
    <b-form-spinbutton id="demo-sb" v-model="value" min="1" max="100"></b-form-spinbutton>
    <p>Value: {{ value }}</p>
  </div>
</template>

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

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

可以使用 ArrowUp 和 ArrowDown 按鍵來增加或減少值。

若透過原生瀏覽器表單提交，自旋按鈕必須透過 name 道具設定名稱。這會建立一個隱藏輸入，其中包含自旋按鈕的目前值。如果自旋按鈕沒有值，隱藏輸入的值會是空字串。

`v-model` 值

v-model 永遠會傳回數字形式的值。如果沒有設定初始值，v-model 可以是 null。

如果初始值為 null，不會在自旋按鈕中顯示值。使用 placeholder 道具，以便在自旋按鈕沒有值時顯示字串（例如 placeholder="--"）。

最小值、最大值和步驟

旋鈕預設範圍從 1 到 100，可透過設定 min 和 max 屬性來變更。預設步驟增量為 1，而且可透過 step 屬性來變更（允許小數值）。

當設定 step 時，其值將永遠為步驟大小加上最小值的倍數。

<template>
  <div>
    <label for="sb-step">Spin button with step of 0.25</label>
    <b-form-spinbutton
      id="sb-step"
      v-model="value"
      min="0"
      max="10"
      step="0.25"
    ></b-form-spinbutton>
  </div>
</template>

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

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

數字包裝

預設狀況下，當將值增加到 max 值時，按增加按鈕後不會產生任何效果。同樣地，當值為 min 值時，按減少按鈕後不會產生任何效果。

若要在增加時讓旋鈕從最大值包裝到最小值（或在減少時從最小值包裝到最大值），請將 wrap 屬性設定為 true。

<template>
  <div>
    <label for="sb-wrap">Wrapping value spin button</label>
    <b-form-spinbutton id="sb-wrap" wrap min="1" max="25" placeholder="--"></b-form-spinbutton>
  </div>
</template>

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

樣式設定

大小

與其他表單控制項相同，<b-form-spinbutton> 支援小型和大型尺寸設定，方法是將 size 屬性分別設定為 'sm' 或 'lg'。

<template>
  <div>
    <label for="sb-small">Spin button - Small size</label>
    <b-form-spinbutton id="sb-small" size="sm" placeholder="--" class="mb-2"></b-form-spinbutton>

    <label for="sb-default">Spin button - Default size</label>
    <b-form-spinbutton id="sb-default" placeholder="--" class="mb-2"></b-form-spinbutton>

    <label for="sb-large">Spin button - Large size</label>
    <b-form-spinbutton id="sb-large" size="lg" placeholder="--" class="mb-2"></b-form-spinbutton>
  </div>
</template>

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

內嵌

<template>
  <div>
    <label for="sb-inline">Inline spin button</label>
    <b-form-spinbutton id="sb-inline" v-model="value" inline></b-form-spinbutton>
  </div>
</template>

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

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

旋鈕會自動調整其寬度以符合顯示值。有關控制或設定寬度的詳細資料，請參閱下方的寬度區段。

垂直

旋鈕可以調整為垂直模式

<template>
  <div>
    <label for="sb-vertical">Vertical spin button</label><br>
    <b-form-spinbutton id="sb-vertical" v-model="value" vertical></b-form-spinbutton>
  </div>
</template>

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

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

垂直旋鈕也可以使用 size 屬性進行調整大小。在垂直模式中，旋鈕會顯示為內嵌元素。

旋鈕會自動調整其寬度以符合顯示值。有關控制或設定寬度的詳細資料，請參閱下方的寬度區段。

寬度

控制項（當未設定 vertical 或 inline 時）會擴充到父層容器的最大寬度，您可以透過實用工具類別，例如 w-25、w-50、w-75，或使用樣式設定寬度來控制寬度。

當設定 vertical 或 inline 時，控制項會根據顯示的值調整其寬度。您可以使用 CSS 樣式來控制控制項的整體寬度（例如 style="width: 10rem;）。

數字格式化與設定

預設狀況下，<b-form-spinbutton> 會以使用者瀏覽器的預設設定格式化顯示的數字。您可以透過 locale 屬性指定設定（或設定的陣列）來變更當地格式。數字格式設定是透過 Intl.NumberFormat 執行。可用的設定會依瀏覽器實作而異。設定僅會控制向使用者顯示的值，而不會影響 v-model。

<template>
  <div>
    <label for="sb-locales">Locale</label>
    <b-form-select id="sb-locales" v-model="locale" :options="locales"></b-form-select>
    <label for="sb-local" class="mt-2">Spin button with locale</label>
    <b-form-spinbutton
      id="sb-locale"
      v-model="value"
      :locale="locale"
      min="0"
      max="10"
      step="0.125"
    ></b-form-spinbutton>
    <p>Value: {{ value }}</p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: 0,
        locale: 'fr-CA',
        locales: [
          { value: 'en', text: 'English' },
          { value: 'de', text: 'German' },
          { value: 'fr-CA', text: 'French (Canadian)' },
          { value: 'fa', text: 'Persian' },
          { value: 'ar-EG', text: 'Arabic (Egyptian)' }
        ]
      }
    }
  }
</script>

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

或者，您可以提供自己的數字格式化函數來格式化顯示的值。當要顯示文字而非數字，或當您想套用 Intl.NumberFormat 的不同功能時，此功能非常有用。

如需提供格式化器函數，請將屬性 formatter-fn 設定為方法參考。格式化器會傳遞單一參數，即當前值。請注意，格式化器只會影響顯示給使用者的值，並不會影響 v-model。

<template>
  <div>
    <label for="sb-days" class="mt-2">Spin button with formatter</label>
    <b-form-spinbutton
      id="sb-days"
      v-model="value"
      :formatter-fn="dayFormatter"
      min="0"
      max="6"
      wrap
    ></b-form-spinbutton>
    <p>Value: {{ value }}</p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value: 0,
        days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
      }
    },
    methods: {
      dayFormatter(value) {
        return this.days[value]
      }
    }
  }
</script>

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

停用和唯讀狀態

設定屬性 disabled 可讓元件處於已停用、不可互動狀態。屬性 readonly 可讓元件處於唯讀狀態（可聚焦，但使用者無法變更值）。

<template>
  <b-row>
    <b-col md="6" class="mb-2">
      <label for="sb-disabled">Disabled spin button</label>
      <b-form-spinbutton id="sb-disabled" v-model="value" disabled></b-form-spinbutton>
    </b-col>
    <b-col md="6" class="mb-2">
      <label for="sb-readonly" class="">Readonly spin button</label>
      <b-form-spinbutton id="sb-readonly" v-model="value" readonly></b-form-spinbutton>
    </b-col>
  </b-row>
</template>

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

<!-- b-form-spinbutton-disabled-readonly.vue -->

在原生瀏覽器表單提交期間，已停用的數字旋鈕不會提交，唯讀數字旋鈕則會提交（只要已透過 name 屬性設定名稱，便會提交）。

驗證狀態

當您預設 null 值，且使用者尚未選取值時，您可以使用 state 屬性為元件套用其中一種脈絡相關驗證樣式。

true 為元件套用有效樣式
false 為元件套用無效樣式
null 不套用任何脈絡相關樣式（預設）

必填屬性

請注意，必填屬性只會為元件產生 aria-required="true" 屬性，而不會在表單提交時執行任何驗證。您必須在您的應用邏輯中驗證 v-model。

請注意，如果已設定屬性 required，且 v-model 為 null，則屬性 aria-invalid="true" 會呈現在元件上。

事件

屬性 input 用於更新 v-model，且會在每次值變更時發出。

屬性 change 會在使用者放開滑鼠按鈕（按下數字旋鈕或減數字鈕時）或使用者放開 向下鍵 或 向上鍵 時發出。在您需要消除輸入回彈時，這會非常方便。

下列範例說明屬性 input 和 change 之間的差別。按住數字旋鈕或減數字鈕（或使用向上/向下箭頭鍵）。

<template>
  <div>
    <label for="sb-input">Spin button - input and change events</label>
    <b-form-spinbutton
      id="sb-input"
      v-model="value1"
      @change="value2 = $event"
      wrap
    ></b-form-spinbutton>
    <p>Input event: {{ value1 }}</p>
    <p>Change event: {{ value2 }}</p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        value1: 0,
        value2: null
      }
    }
  }
</script>

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

無障礙

聚焦數字按鈕時，以下鍵盤控制可使用

Home 將值設為 min 值
End 將值設為 max 值
↑（向上鍵） 增加值為步進幅度
↓（向下鍵） 減少值為步進幅度
PageUp 增加值為步進幅度乘以 repeat-step-multiplier 的倍數
PageDown 減少值為步進幅度乘以 repeat-step-multiplier 的倍數

按住 向上鍵、向下鍵、向上翻頁鍵 或 向下翻頁鍵 鍵，將會自動重複遞增或遞減（在初始延遲後）。持續按住 向上鍵 或 向下鍵 一段時間，將會將遞增或遞減的數量乘以 repeat-step-multiplier 數量。

請注意，repeat-delay、repeat-threshold 和 repeat-interval 僅適用於 向上鍵 或 向下鍵。

實作備註

<b-form-spinbutton> 混合使用 Bootstrap v4 的實用工具類別（邊框、對齊、彈性）、`form-control` 和按鈕類別，以及額外的自訂 BootstrapVue SCSS/CSS。

請參閱

範圍類型輸入

元件參考

`<b-form-spinbutton>`

2.5.0+

檢視原始碼

<b-form-spinbutton> 元件別名
<b-form-spinbutton> 屬性
<b-form-spinbutton> v-model
<b-form-spinbutton> 插槽
<b-form-spinbutton> 事件

元件別名

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

<b-spinbutton>

注意：只有在匯入所有 BootstrapVue，或使用元件群組外掛時，才能使用元件別名。

屬性

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

屬性（按一下進行升序排序）	類型（按一下進行升序排序）	預設值	說明
`aria-controls`	`字串`		如果這個元件控制另一個元件或元素，請設定為受控元件或元素的 ID
`aria-label`	`字串`		要放進旋鈕按鈕的 `aria-label` 屬性值
`disabled`	`布林值`	`false`	置元件於停用狀態
`form`	`字串`		表單的 ID，表單控制元件屬於此表單。在控制元件上設定 `form` 屬性
`formatter-fn`	`函數`		對要顯示的值套用格式的 method 參照。傳入單一引數給它，即目前的值
`id`	`字串`		用於設定已呈示內容的 `id` 屬性，並用來視需要產生任何額外的元素 ID
`inline`	`布林值`	`false`	設定時，會以內嵌元素的方式呈示元件
`label-decrement`	`字串`	`「遞減」`	要使用在遞減按鈕 `aria-label` 屬性上的文字
`label-increment`	`字串`	`「遞增」`	要使用在遞增按鈕 `aria-label` 屬性上的文字
`locale`	`陣列` 或 `字串`		指定用於設置數字格式的地區。預設為瀏覽器地區。僅在使用內建格式器時適用
`max`	`數字` 或 `字串`	`100`	可以選取的最大值。必須大於 `min` 屬性。允許負數
`min`	`數字` 或 `字串`	`1`	選擇的最小值。允許負數
`名稱`	`字串`		設定表單控制元件的 `name` 屬性的值
`提示文字`	`字串`		當 v-model 為 `null` 時顯示的值
`唯讀`	`布林值`	`false`	將元件置於唯讀狀態
`重複延遲`	`數字` 或 `字串`	`500`	在自動重複遞增或遞減發生前的延遲時間（毫秒）。必須是正整數。要求使用者持續按一下並按住
`重複間隔`	`數字` 或 `字串`	`100`	遞增或遞減重複之間的時間間隔（毫秒）。必須是正整數
`重複步進值倍增數`	`數字` 或 `字串`	`4`	一旦達到 `重複閾值` 後，要跳過的步進數。必須是正整數。此值也用於上下分頁鍵
`重複閾值`	`數字` 或 `字串`	`10`	在以 `重複步進值倍增數` 增加步進大小之前，要重複出現的次數。必須是正整數
`大小`	`字串`		設定元件外觀的大小。'sm'、'md'（預設）或 'lg'
`狀態`	`布林值`	`無`	控制元件的驗證狀態外觀。`true` 表示有效，`false` 表示無效，或 `null` 表示沒有驗證狀態
`步進值`	`數字` 或 `字串`	`1`	指定值必須遵守的粒度大小的正數
`值` v-model	`布林值` 或 `數字`		旋鈕的值。繫結至 v-model
`垂直`	`布林值`	`false`	設定時，會以垂直配置呈現元件
`折返`	`布林值`	`false`	設定時，允許值達到最小值或最大值時折返

`v-model`

屬性	事件
`值`	`輸入`

插槽

名稱	範圍	說明
`遞減` v2.8.0+		置於遞減按鈕中的自訂內容
`遞增` v2.8.0+		置於遞增按鈕中的自訂內容

事件

事件	引數	說明
`變更`	`值` - 旋鈕的目前值	當使用者放開滑鼠按鈕或按鍵時觸發
`輸入`	`值` - 旋鈕的目前值	在每次值變更時觸發，以更新 v-model

匯入個別元件

您可以透過下列命名匯出至專案中匯入個別元件

元件	命名匯出	匯入路徑
`<b-form-spinbutton>`	`BFormSpinbutton`	`bootstrap-vue`

範例

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

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

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

命名匯出	匯入路徑
`FormSpinbuttonPlugin`	`bootstrap-vue`

範例

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

概觀

v-model 值