SCheckbox <s-checkbox>

用于是/否选择的单个复选框，通过 v-model 绑定其选中状态。 SCheckbox 是 Shopify Polaris <s-checkbox> web component 的带类型 Vue 3 wrapper。

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

最佳实践

• 让每个复选框相互独立。 商家应能勾选任意组合的选项，而不会因为一个复选框影响另一个。
• 为每个复选框提供描述性的 label。 当复选框用于开启或关闭某项设置时，这一点尤为重要，这样商家才能确切知道自己启用的是什么。
• 按逻辑顺序排列选项。 按字母、数字或时间排序，让商家能快速找到想要的选项。
• indeterminate 只用于部分选中的“全选”。 当“全选”复选框所在分组中只有部分项目被勾选时，在该复选框上使用它。
• 在有助于理解时添加 details。 仅当单靠标签不足以说明时，才用它进一步解释某个选项的作用。

<SCheckbox
  label="Send order confirmation emails"
  details="Customers get an email as soon as their order is placed."
/>

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

示例

Checked: false

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

const value = ref(false)
</script>

<template>
  <SCheckbox label="Send me marketing emails" v-model="value" />
  <p>Checked: {{ value }}</p>
</template>

v-model

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

<SCheckbox v-model="value" />

等价于：

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

Props

Prop	类型	说明
accessibilityLabel	string	供屏幕阅读器等辅助技术用户使用的标签。设置后，提供的任何子元素或 label 都不会被朗读。也可以借此显示一个没有可见标签的控件，同时仍为屏幕阅读器用户提供上下文。
checked	boolean	控件是否处于激活状态。
defaultChecked	boolean	控件默认是否处于激活状态。
defaultIndeterminate	boolean	非受控组件的初始不确定状态。如果希望复选框以不确定状态开始，但之后不需要控制它，请使用此属性。在显式设置 indeterminate 或用户点击更改复选框状态之前，此值一直有效。
details	any	为字段提供上下文或指引的附加文本。该文本会与字段及其标签一起显示，为用户提供更多信息或说明。它也会提供给屏幕阅读器用户。
disabled	boolean	禁用控件，不允许任何交互。
error	any	向用户提示错误。字段会采用特定的样式处理，以传达必须立即解决的问题。
indeterminate	boolean	复选框是否显示为不确定状态（既非选中也非未选中），通常用于表示层级列表中的部分选中。此视觉状态仅在外观上优先于 checked prop，表单提交值仍由 checked prop 决定。如果 indeterminate 未被显式设置且未因用户交互而改变，则返回 defaultIndeterminate 的值。
label	any	用作控件标签的可视内容。
labelAccessibilityVisibility	"visible" | "exclusive"	更改组件标签的可见性。 - visible：标签对所有用户可见。 - exclusive：标签在视觉上隐藏，但仍保留在无障碍树中。
name	string	控件的标识符，在最近的外层 Form 组件内唯一。
required	boolean	字段是否需要填写值。此要求会为字段添加语义，但不会自动显示错误。如果希望在字段为空时显示错误，可以使用 error 属性。
value	string	控件被选中时在表单数据中使用的值。

Events

Event	类型
blur	FocusEvent
change	Event
input	Event

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

Slots

Slot	说明
details
error