SChoiceList <s-choice-list>

一组单选框或复选框，用于选择一个或多个选项。 SChoiceList 是 Shopify Polaris <s-choice-list> web component 的带类型 Vue 3 wrapper。

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

最佳实践

• 让选择模式与选项相匹配。 对互斥的选项（例如付款方式或配送速度）保持单选；当商家可以选择多个选项时，设置 multiple。
• 让选项标签描述结果。 “新订单的电子邮件通知”比“电子邮件”传达的信息更多。标签要简短，但要清晰到可以独立理解。
• 将 label 写成问题或陈述。 像“选择哪种配送方式？”或“选择通知偏好”这样的标题，比“选项”或“设置”这类含糊的词更能让商家明白。
• 在 details slot 中解释复杂的选项。 当商家需要了解选择某个选项意味着什么时，为该 SChoice 添加详细说明。
• 让 error 消息具体明确。 准确告诉商家缺少什么，例如“请至少选择一项通知偏好”，而不是笼统的“必填字段”。

<SChoiceList label="Which shipping method?">
  <SChoice value="standard">Standard shipping</SChoice>
  <SChoice value="express">
    Express shipping
    <template #details>
      <SText>Costs more, but orders arrive in 1–2 business days.</SText>
    </template>
  </SChoice>
</SChoiceList>

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

示例

EmailSMSPush notification

Selected: (none)

<script setup>
import { ref } from 'vue'
import { SChoiceList, SChoice } from 'polaris-vue-elements'

const value = ref([])
</script>

<template>
  <SChoiceList label="Notify me by" multiple v-model="value">
    <SChoice value="email">Email</SChoice>
    <SChoice value="sms">SMS</SChoice>
    <SChoice value="push">Push notification</SChoice>
  </SChoiceList>
  <p>Selected: {{ value.join(', ') }}</p>
</template>

v-model

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

<SChoiceList v-model="value" />

等价于：

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

Props

Prop	类型	说明
details	any	为字段提供上下文或指引的附加文本。该文本会与字段及其标签一起显示，为用户提供更多信息或说明。它也会提供给屏幕阅读器用户。
disabled	boolean	字段是否被禁用，禁用后将阻止任何用户交互。为 true 时，任何子选项上的 disabled 属性都会被忽略。
error	any	向用户提示错误。字段会采用特定的样式处理，以传达必须立即解决的问题。
label	any	用作字段标签的内容。
labelAccessibilityVisibility	"visible" | "exclusive"	更改组件标签的可见性。 - visible：标签对所有用户可见。 - exclusive：标签在视觉上隐藏，但仍保留在无障碍树中。
multiple	boolean	是否可以选择多个选项。
name	string	字段的标识符，在最近的外层表单内唯一。
values	string[]	所选选项的 value 组成的数组。这是一个便捷 prop，用于设置子选项上的 selected prop。

Events

Event	类型
change	Event
input	Event

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

Slots

Slot	说明
default	用户可以从中选择的选项。接受选项组件。