SNumberField <s-number-field>

可设置最小值、最大值和步长的数字输入框。 SNumberField 是 Shopify Polaris <s-number-field> web component 的带类型 Vue 3 wrapper。

import { SNumberField } from 'polaris-vue-elements'

最佳实践

• 只用于纯数值。 适用于数量、尺寸或百分比等。如果值可能包含字母或符号（例如产品代码或电话号码），请改用 STextField。
• 显示单位。 使用 prefix 或 suffix 说明数字的度量单位，免得商家猜测自己输入的是美元、千克还是百分比。
• 设置符合业务规则的限制。 提供反映实际允许范围的 min 和 max 值，在商家提交表单之前就引导他们输入有效内容。
• 校验并解释错误。 检查每一个数值输入；校验失败时，用 error 准确说明问题所在以及如何修正，而不是显示一条笼统的消息。

<SNumberField label="Discount" suffix="%" :min="0" :max="100" />

参阅 Shopify 关于 <s-number-field> 的最佳实践（英文）以获取完整指南。

示例

Value: 1

<script setup>
import { ref } from 'vue'
import { SNumberField } from 'polaris-vue-elements'

const value = ref('1')
</script>

<template>
  <SNumberField label="Quantity" :min="0" :max="100" :step="1" v-model="value" />
  <p>Value: {{ value }}</p>
</template>

v-model

<SNumberField> 上的 v-model 绑定到 value property，并监听 input DOM 事件。

<SNumberField v-model="value" />

等价于：

<SNumberField :value="value" @input="value = $event.target.value" />

Props

Prop	类型	说明
autocomplete	"one-time-code" | "cc-number" | "cc-csc" | "on" | "off" | "shipping one-time-code" | "billing one-time-code" | "shipping cc-number" … (3 more)	关于字段预期内容的提示。设置为 on（默认值）时，表示该字段应支持自动填充，但没有关于预期内容的更多语义信息。设置为 off 时，表示该字段包含敏感信息或永远不会被保存的内容，例如一次性验证码。此外，也可以提供一个值，描述希望在自动填充时填入该字段的具体数据。
defaultValue	string	字段的默认值。
details	any	为字段提供上下文或指引的附加文本。该文本会与字段及其标签一起显示，为用户提供更多信息或说明。它也会提供给屏幕阅读器用户。
disabled	boolean	禁用字段，不允许任何交互。
error	any	向用户提示错误。字段会采用特定的样式处理，以传达必须立即解决的问题。
id	string	元素的唯一标识符。
inputMode	"decimal" | "numeric"	在移动设备上显示的虚拟键盘类型。 - decimal：显示带小数点的数字键盘，适合价格或尺寸。 - numeric：显示不带小数点的数字键盘，适合数量等整数。详细了解 inputmode 属性。
label	any	用作字段标签的内容。
labelAccessibilityVisibility	"visible" | "exclusive"	更改组件标签的可见性。 - visible：标签对所有用户可见。 - exclusive：标签在视觉上隐藏，但仍保留在无障碍树中。
max	number	字段可接受的最大小数或整数。与 step 一起使用时，值会向下取整到最大值。注意：用户仍然可以通过键盘输入高于最大值的数字，需要由开发者自行添加适当的校验。
min	number	字段可接受的最小小数或整数。与 step 一起使用时，值会向上取整到最小值。注意：用户仍然可以通过键盘输入低于最小值的数字，需要由开发者自行添加适当的校验。
name	string	字段的标识符，在最近的外层表单内唯一。
placeholder	string	描述字段预期值的简短提示。
prefix	string	显示在字段可编辑部分之前的值。适合用于显示值中隐含的部分，例如 "https://" 或 "+353"。用户无法编辑它，它也不包含在字段的值中。在用户与输入框交互之前，它可能不会显示。例如，在用户聚焦输入框之前，内联标签可能会占据前缀的位置。
readOnly	boolean	该字段不能由用户编辑。它可以获得焦点，并会被屏幕阅读器朗读。
required	boolean	字段是否需要填写值。此要求会为字段添加语义，但不会自动显示错误。如果希望在字段为空时显示错误，可以使用 error 属性。
step	number	值每次可增加或减少的量。可以是整数或小数。如果在通过按钮增减值时，与 step 一起指定了 max 或 min，最终值将始终取整到 max 或 min，而不是最接近的有效值。
suffix	string	显示在字段可编辑部分之后的值。适合用于显示值中隐含的部分，例如 "@shopify.com" 或 "%"。用户无法编辑它，它也不包含在字段的值中。在用户与输入框交互之前，它可能不会显示。例如，在用户聚焦输入框之前，内联标签可能会占据后缀的位置。
value	string

为便于阅读，上面部分类型列已被截断；完整的联合类型见库中生成的 TypeScript 类型（src/lib/generated/types.ts）。

Events

Event	类型
blur	FocusEvent
change	Event
focus	FocusEvent
input	Event

在 <SNumberField> 上使用 @blur 形式的监听器来监听这些事件。

Slots

Slot	说明
details
error