SSelect <s-select>

从列表中选择一个选项的下拉选择框。 SSelect 是 Shopify Polaris <s-select> web component 的带类型 Vue 3 wrapper。

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

最佳实践

• 用于已知的选项集合。 当商家从预定义列表中选择时，select 很合适。当商家需要输入自定义值或在很长的列表中查找时，更适合使用能在输入时提示匹配项的文本字段，或可搜索的下拉菜单。
• 有意识地排列选项。 将相关选项分组、把最常用的放在最前面，或在没有自然顺序时按字母排序，让商家能快速找到所需选项。
• 编写便于浏览的标签。 为每个选项提供足够的上下文，让商家无需展开并逐一阅读多个选项就能区分它们。
• 有意识地选择初始状态。 存在明显的默认值时预先选中一个选项；当商家需要主动做出选择时，使用 placeholder。不要让初始状态含糊不清。
• 解释校验问题。 当某个选择是必填项或无效时，用 error 具体告诉商家该怎么做，因为有针对性的消息比笼统的消息更能帮助他们更快完成表单。

<SSelect label="Shipping speed" placeholder="Choose a shipping speed" required>
  <SOption value="standard">Standard (5–7 business days)</SOption>
  <SOption value="express">Express (2–3 business days)</SOption>
  <SOption value="overnight">Overnight (next business day)</SOption>
</SSelect>

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

示例

United StatesCanadaFranceGermany

Value: (none)

<script setup>
import { ref } from 'vue'
import { SSelect, SOption, SOptionGroup } from 'polaris-vue-elements'

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

<template>
  <SSelect label="Shipping region" placeholder="Select a region" v-model="value">
    <SOptionGroup label="North America">
      <SOption value="us">United States</SOption>
      <SOption value="ca">Canada</SOption>
    </SOptionGroup>
    <SOptionGroup label="Europe">
      <SOption value="fr">France</SOption>
      <SOption value="de">Germany</SOption>
    </SOptionGroup>
  </SSelect>
  <p>Value: {{ value }}</p>
</template>

v-model

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

<SSelect v-model="value" />

等价于：

<SSelect :value="value" @change="value = $event.target.value" />

Props

Prop	类型	说明
details	any	为字段提供上下文或指引的附加文本。该文本会与字段及其标签一起显示，为用户提供更多信息或说明。它也会提供给屏幕阅读器用户。
disabled	boolean	禁用字段，不允许任何交互。
error	any	向用户提示错误。字段会采用特定的样式处理，以传达必须立即解决的问题。
icon	"color" | "info" | "adjust" | "affiliate" | "airplane" | "alert-bubble" | "alert-circle" | "alert-diamond" … (553 more)	字段中显示的图标类型。
id	string	元素的唯一标识符。
label	any	用作字段标签的内容。
labelAccessibilityVisibility	"visible" | "exclusive"	更改组件标签的可见性。 - visible：标签对所有用户可见。 - exclusive：标签在视觉上隐藏，但仍保留在无障碍树中。
name	string	字段的标识符，在最近的外层表单内唯一。
placeholder	string	描述字段预期值的简短提示。
required	boolean	字段是否需要填写值。此要求会为字段添加语义，但不会自动显示错误。如果希望在字段为空时显示错误，可以使用 error 属性。
value	string

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

Events

Event	类型
blur	FocusEvent
change	Event
focus	FocusEvent
input	Event

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

Slots

Slot	说明
default	下拉列表中显示的可选选项。接受选项组件作为单个可选项，也接受选项组组件，将相关选项组织为带标签的逻辑分组。
details
error