SChoiceList <s-choice-list>

Un groupe de boutons radio ou de cases à cocher pour choisir une ou plusieurs options. SChoiceList est le wrapper Vue 3 typé du web component <s-choice-list> de Shopify Polaris.

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

Bonnes pratiques

• Accordez le mode de sélection aux options. Conservez la sélection unique pour les options qui s'excluent mutuellement, comme les moyens de paiement ou les vitesses de livraison, et définissez multiple lorsque les marchands peuvent en choisir plusieurs.
• Faites décrire le résultat par le libellé de chaque choix. "Email notifications for new orders" en dit plus que "Email". Gardez des libellés courts, mais assez clairs pour se suffire à eux-mêmes.
• Formulez le label comme une question ou une affirmation. Un titre comme "Which shipping method?" ou "Select notification preferences" en dit plus aux marchands qu'un mot vague comme "Options" ou "Settings".
• Expliquez les choix complexes dans le slot details. Ajoutez des détails à un SChoice lorsque les marchands doivent comprendre ce qu'implique ce choix.
• Rendez les messages d'error précis. Dites exactement aux marchands ce qui manque, par exemple "Select at least one notification preference", plutôt qu'un générique "Required field".

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

Consultez les bonnes pratiques de Shopify pour <s-choice-list> (en anglais) pour l'ensemble des recommandations.

Exemple

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

v-model sur <SChoiceList> est lié à la propriété values et écoute l'event DOM change.

<SChoiceList v-model="value" />

équivaut à :

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

Props

Prop	Type	Description
details	any	Texte supplémentaire apportant du contexte ou des indications pour le champ. Ce texte est affiché avec le champ et son libellé afin de fournir davantage d'informations ou d'instructions à l'utilisateur. Il est également exposé aux utilisateurs de lecteurs d'écran.
disabled	boolean	Indique si le champ est désactivé, ce qui empêche toute interaction de l'utilisateur. Lorsqu'il vaut true, la propriété disabled des choix enfants est ignorée.
error	any	Signale une erreur à l'utilisateur. Le champ reçoit un traitement visuel spécifique pour signaler des problèmes à résoudre immédiatement.
label	any	Contenu à utiliser comme libellé du champ.
labelAccessibilityVisibility	"visible" | "exclusive"	Modifie la visibilité du libellé du composant. - visible : le libellé est visible par tous les utilisateurs. - exclusive : le libellé est masqué visuellement mais reste dans l'arbre d'accessibilité.
multiple	boolean	Indique si plusieurs choix peuvent être sélectionnés.
name	string	Un identifiant du champ, unique au sein du formulaire parent le plus proche.
values	string[]	Un tableau des value des options sélectionnées. Prop de commodité pour définir la prop selected sur les options enfants.

Events

Event	Type
change	Event
input	Event

Écoutez-les avec des listeners de la forme @change sur <SChoiceList>.

Slots

Slot	Description
default	Les choix que l'utilisateur peut sélectionner. Accepte des composants choice.