SSwitch <s-switch>

設定のオン・オフを切り替えるトグルスイッチ。 SSwitch は、Shopify Polaris の <s-switch> web component 向けの型付き Vue 3 wrapper です。

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

ベストプラクティス

• スイッチと保存ボタンを組み合わせない。 スイッチは切り替えた瞬間に反映されるため、保存ボタンを追加すると、変更がいつ実際に適用されるのかマーチャントが判断できなくなります。
• 設定内容をわかりやすくする。 スイッチが何を制御し、オンとオフが何を意味するのかを伝える label を書き、確かめるためだけに切り替える必要がないようにします。
• 結果を説明する。 特に重要な機能やデータに影響する設定では、details を使ってスイッチを切り替えると何が変わるのかを説明し、マーチャントが自信を持って判断できるようにします。
• 関連するスイッチをまとめて並べる。 ページに複数のスイッチがある場合は、関連する設定を論理的な順序でまとめ、マーチャントが簡単に見つけて設定できるようにします。
• スイッチが使えない理由を説明する。 権限、依存関係、プランの制限によってスイッチが disabled になっている場合は、その理由、一時的なものかどうか、そして使えるようにするには何をすればよいかをマーチャントに伝えます。

<SSwitch label="Send order confirmation emails" details="Customers get an email as soon as they place an order." />

詳しいガイダンスについては、<s-switch> に関する Shopify のベストプラクティス（英語）を参照してください。

例

On: false

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

const value = ref(false)
</script>

<template>
  <SSwitch label="Enable notifications" v-model="value" />
  <p>On: {{ value }}</p>
</template>

v-model

<SSwitch> の v-model は checked プロパティにバインドされ、change DOM イベントを監視します。

<SSwitch v-model="value" />

これは次と同等です：

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

Props

Prop	型	説明
accessibilityLabel	string	スクリーンリーダーなどの支援技術を使用するユーザー向けのラベルです。設定すると、子要素や指定した label は読み上げられなくなります。視覚的なラベルなしでコントロールを表示しつつ、スクリーンリーダーを使用するユーザーにはコンテキストを提供する用途にも使用できます。
checked	boolean	コントロールがアクティブかどうか。
defaultChecked	boolean	コントロールがデフォルトでアクティブかどうか。
details	any	フィールドのコンテキストやガイダンスを提供する追加のテキストです。このテキストはフィールドとそのラベルとともに表示され、ユーザーに詳しい情報や手順を伝えます。スクリーンリーダーのユーザーにも公開されます。
disabled	boolean	コントロールを無効にし、あらゆる操作を受け付けないようにします。
error	any	ユーザーにエラーを示します。すぐに解決する必要がある問題を伝えるため、フィールドに特定のスタイルが適用されます。
label	any	コントロールのラベルとして使用するビジュアルコンテンツです。
labelAccessibilityVisibility	"visible" | "exclusive"	コンポーネントのラベルの表示状態を変更します。 - visible: ラベルはすべてのユーザーに表示されます。 - exclusive: ラベルは視覚的に非表示になりますが、アクセシビリティツリーには残ります。
name	string	最も近い親の Form コンポーネント内で一意となる、コントロールの識別子です。
required	boolean	フィールドに値が必要かどうか。この要件はフィールドにセマンティックな意味を加えますが、エラーが自動的に表示されるわけではありません。このフィールドが空のときにエラーを表示したい場合は、error プロパティを使用してください。
value	string	コントロールがチェックされたときにフォームデータで使用される値です。

Events

Event	型
blur	FocusEvent
change	Event
input	Event

これらのイベントは <SSwitch> 上で @blur 形式のリスナーで受け取れます。