按钮式表单(Form Spinbutton)

旋转按钮是一个 BootstrapVue 自定义数值范围窗体控件。旋转按钮允许在最小值和最大值的范围内递增或递减一个数值，可选步长值。

<b-form-spinbutton> 兼容 WAI-ARIA ，允许 keyboard control【键盘控制】，并支持水平（默认）和垂直布局。

与 range type inputs【范围类型输入】类似，BootstrapVue的 <b-form-spinbutton> 不允许 用户键入值。

50

Value: 50

<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>

概述

ArrowUp 和 ArrowDown 键可用于增加或减少该值。

要通过本机浏览器表单提交提交，旋转按钮必须具有通过 name 属性设置的名称。这将创建一个包含输入按钮当前值的隐藏输入。如果旋转按钮没有值，则隐藏输入的值将为空字符串。

v-model 值

v-model 始终以数字形式返回值。如果未设置初始值，则 v-model 可以为 null 。

如果初始值为 null ，则不会在旋转按钮中显示任何值。当旋转按钮没有值时（例如，placeholder="--" ），请使用 placeholder【占位符】属性显示字符串。

最小、最大和步长

旋转按钮的默认范围是 1 到 100 ，可以通过设置 min 和 max 属性来更改。默认的步长增量为 1 ，可以通过 step【步长】道具更改（允许十进制值）。

设置 step【步长】后，该值将始终是步长加最小值的倍数。

0.00
 
<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>

数字包装

默认情况下，当该值增加到最 max 时，按增量按钮将不起作用。同样，当该值作为 min 值时，按减量按钮将无效。

若要使旋转按钮在递增时从 max 到 min 换行（在递减时从min到max换行），请将 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> 通过将 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>

内联

50
 
<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>

旋转按钮将自动调整其宽度以适合显示的值。有关控制或设置宽度的详细信息，请参见下面的 Width section【宽度部分】。

垂直

旋转按钮可以在垂直模式下定向：


50
 
<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>

垂直旋转按钮也可以使用 size 属性 调整大小。在垂直模式下，旋转按钮将呈现为嵌入式元素。

旋转按钮将自动调整其宽度以适合显示的值。有关控制或设置宽度的详细信息，请参见下面的 Width section【宽度部分】。

宽度

控件（当不是 vertical【垂直】控件或 inline【嵌入式】控件时）将扩展到父容器的最大宽度。您可以通过实用程序类（如 w-25 ，w-50 ，w-75 ）控制宽度，也可以使用样式设置宽度。

设置 vertical【垂直】或 inline【嵌入式】时，控件将根据显示的值调整其宽度。您可以使用CSS样式来控制控件的整体宽度（即 style="width: 10rem; ）。

数字格式和区域设置

默认情况下，<b-form-spinbutton> 将在用户浏览器的默认区域设置中格式化显示的数字。您可以通过 locale 属性指定语言环境（或语言环境数组）来更改本地化格式。数字格式本地化是通过 Intl.NumberFormat 执行的。可用的语言环境将取决于浏览器的实现。本地化仅控制向用户显示值，而不会影响 v-model 。

0,000

Value: 0

<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>

或者，您可以提供自己的数字格式化程序功能来格式化显示的值。这对于显示文本（而不是数字）或要实现 Intl.NumberFormat 的不同功能很有用。

要提供格式化程序功能，请将 formatter-fn 属性设置为方法参考。格式化程序将传递一个参数，该参数是当前值。请注意，格式化程序仅影响显示给用户的值，而不影响 v-model 。

Sunday

Value: 0

<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>

禁用和只读状态

将属性设置为 disabled 会将组件置于禁用的非交互状态。readonly 属性将组件置于只读状态（可聚焦，但用户无法更改该值）。

50
50
 
<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>

在本机浏览器提交表单期间，不会提交禁用的旋转按钮，而将提交只读旋转按钮（只要已通过 name 属性设置了名称）。

验证状态

当您默认为 null 值并且用户尚未选择值时，可以使用 state 属性将上下文验证样式之一应用于组件。

  • true 将有效样式应用于组件
  • false 将无效样式应用于组件
  • null 不应用任何上下文样式（默认）

Required 属性

请注意，required 属性仅在组件上生成 aria-required="true" 属性，并且不对表单提交执行任何验证。您必须在应用程序逻辑中验证 v-model 。

请注意，如果设置了 required 属性，并且 v-model 为 null ，则属性 aria-invalid="true" 将呈现在组件上。

事件

input 事件用于更新 v-model ，并在值更改时发出。

一旦用户释放鼠标按钮（在按下增加或减少按钮时），或者当用户释放 ArrowDown 或 ArrowUp 键时，就会发出 change 事件。当您需要对输入进行去抖动时，这会很方便。

以下示例说明了 input 和 change 事件之间的区别。单击并按住增加或减少按钮（或使用向上/向下箭头键）。

0

Input event: 0

Change event: 

<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>
  </b-row>
</template>

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

辅助功能

对准旋转按钮时，可以使用以下键盘控件：

  • Home 将值设置为 min 值
  • End 将值设置为 max 值
  • ArrowUp 逐步增加值
  • ArrowDown 递减步长值
  • PageUp 将值增加步数乘以 repeat-step-multiplier【重复步乘数】
  • PageDown 将值减小步数乘以 repeat-step-multiplier【重复步乘数】

按住 ArrowUp ，ArrowDown ，PageUp ，或 PageDown 键将自动重复递增或递减（在初始延迟之后）。长时间按住 ArrowUp 或 ArrowDown 键会将增量或减量乘以 repeat-step-multiplier【重复步乘数】。

注意 repeat-delay ，repeat-threshold 和 repeat-interval 仅适用于 ArrowUp 或 ArrowDown 键。

实施说明

<b-form-spinbutton> 结合使用了 Bootstrap v4 实用程序类（边距，填充和flex），表单控制和按钮类，以及其他自定义 BootstrapVue SCSS / CSS。

另请参阅

组件引用

<b-form-spinbutton>

v2.5.0+
查看源代码

组件别名

<b-form-spinbutton> 也可以通过以下别名使用：

  • <b-spinbutton>

注意：组件别名仅在导入所有 BootstrapVue 或使用组件组插件时可用。

属性

属性 (Click to sort Ascending) 类型 默认值 描述
id String 用于在渲染的内容上设置“id”属性，并用作根据需要生成任何其他元素ID的基础
value Number 旋转按钮的值。 绑定到v-model
min Number or String 1 可以选择的最小值。 允许负数
max Number or String 100 可以选择的最大值。须大于“min”属性。允许使用负数
step Number or String 1 一个正数，指定值必须遵循的粒度
wrap Boolean false 设置时，允许值在读取最小值或最大值时回绕
formatter-fn Function 对格式化显示值的方法的引用。 它传递了一个参数作为当前值
size String 设置组件外观的大小。'sm'，'md'（默认）或'lg'
placeholder String v-model 为 null 时显示的值
disabled Boolean false 将组件置于禁用状态
readonly Boolean false 将组件置于只读状态
required Boolean false 在组件上添加`aria-required =“true”`属性。注意，当值为空时，这不会阻止提交。
name String 设置表单控件上“name”属性的值
form String 表单控件所属的表单的ID。在控件上设置“form”属性
state Boolean 控制组件的验证状态外观。“true”表示有效，“false”表示无效”，“null”表示无验证状态
inline Boolean false 设置后，将组件呈现为嵌入式元素
vertical Boolean false 设置后，以垂直布局渲染组件
aria-label String 放置在旋转按钮的“aria-label”属性中的值
aria-controls String 如果此组件控制另一个组件或元素，请将其设置为受控组件或元素的ID
label-decrement String 'Decrement' 递减按钮上用于“aria-label”属性的文本
label-increment String 'Increment' 增量按钮上用于“aria-label”属性的文本
locale String or Array 指定用于格式化数字的本地名称。默认为浏览器语言环境。仅在使用内部格式化程序时适用
repeat-delay Number or String 500 自动重复递增或递减发生之前的延迟（以毫秒为单位）。必须为正整数。 要求用户单击/按下并按住
repeat-interval Number or String 100 递增或递减重复之间的间隔（以毫秒为单位）。必须为正整数
repeat-threshold Number or String 10 在通过“repeat-step-multiplier”增加步长之前发生的重复次数。必须为正整数
repeat-step-multiplier Number or String 4 达到“repeat-threshold”时要跳过的步骤数。 必须为正整数。 此值也用于上翻页和下翻页键

事件

事件 参数 描述
input
  1. value - 旋转按钮的当前值
 每次值更改时都会更新以更新 v-model
change
  1. value - 旋转按钮的当前值
 当用户释放鼠标按钮或键时发出

导入单个组件

您可以通过以下命名的导出将单个组件导入到项目中：

组件 命名输出 导入路径
<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)