SSwitch <s-switch>

Một công tắc bật/tắt một thiết lập. SSwitch là Vue 3 wrapper có type cho web component <s-switch> của Shopify Polaris.

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

Best practices

• Đừng kết hợp switch với nút lưu. Switch có hiệu lực ngay khi được bật/tắt, nên thêm nút lưu sẽ khiến người bán không chắc khi nào thay đổi thực sự được áp dụng.
• Làm rõ thiết lập. Viết label cho người bán biết switch điều khiển gì và bật hay tắt nghĩa là gì, để họ không phải gạt thử mới biết.
• Mô tả hệ quả. Dùng details để giải thích điều gì thay đổi khi switch được bật/tắt, đặc biệt với các thiết lập ảnh hưởng đến tính năng hoặc dữ liệu quan trọng, để người bán có thể quyết định một cách tự tin.
• Nhóm và sắp xếp các switch liên quan. Khi một trang có nhiều switch, hãy giữ các thiết lập liên quan ở cạnh nhau theo thứ tự hợp lý để người bán dễ tìm và cấu hình.
• Giải thích vì sao switch không khả dụng. Khi một switch bị vô hiệu hóa (disabled) do quyền hạn, phụ thuộc hoặc giới hạn của gói, hãy cho người bán biết lý do, đó có phải là tạm thời không, và họ cần làm gì để mở khóa.

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

Xem best practices của Shopify cho <s-switch> (tiếng Anh) để có hướng dẫn đầy đủ.

Ví dụ

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

v-model trên <SSwitch> gắn với property checked và lắng nghe DOM event change.

<SSwitch v-model="value" />

tương đương với:

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

Props

Prop	Kiểu	Mô tả
accessibilityLabel	string	Nhãn dành cho người dùng công nghệ hỗ trợ như trình đọc màn hình. Khi được đặt, mọi phần tử con hoặc label được cung cấp sẽ không được đọc lên. Nhãn này cũng có thể dùng để hiển thị một control không có nhãn hiển thị, trong khi vẫn cung cấp ngữ cảnh cho người dùng trình đọc màn hình.
checked	boolean	Control có đang active hay không.
defaultChecked	boolean	Control có ở trạng thái active theo mặc định hay không.
details	any	Văn bản bổ sung cung cấp ngữ cảnh hoặc hướng dẫn cho trường. Văn bản này được hiển thị cùng với trường và nhãn của nó để cung cấp thêm thông tin hoặc chỉ dẫn cho người dùng. Văn bản này cũng được cung cấp cho người dùng trình đọc màn hình.
disabled	boolean	Vô hiệu hóa control, không cho phép bất kỳ tương tác nào.
error	any	Báo lỗi cho người dùng. Trường sẽ được áp dụng kiểu hiển thị riêng để thông báo các vấn đề cần được giải quyết ngay.
label	any	Nội dung trực quan dùng làm nhãn của control.
labelAccessibilityVisibility	"visible" | "exclusive"	Thay đổi khả năng hiển thị của nhãn của component. - visible: nhãn hiển thị với mọi người dùng. - exclusive: nhãn bị ẩn về mặt thị giác nhưng vẫn nằm trong cây trợ năng (accessibility tree).
name	string	Định danh cho control, là duy nhất trong component Form chứa nó gần nhất.
required	boolean	Trường có bắt buộc phải có giá trị hay không. Yêu cầu này bổ sung giá trị ngữ nghĩa cho trường, nhưng sẽ không tự động hiển thị lỗi. Nếu muốn hiển thị lỗi khi trường này trống, bạn có thể dùng thuộc tính error.
value	string	Giá trị dùng trong dữ liệu form khi control được chọn.

Events

Event	Kiểu
blur	FocusEvent
change	Event
input	Event

Lắng nghe các event này bằng listener dạng @blur trên <SSwitch>.