Switch 開關

開關用來在設定列切換布林值。尺寸列舉與 Button、Input 相同（sm / md / lg），軌道高度低於欄位高度。

示範

基礎

綁定 checked，並以 e.detail.checked 監聽 change。沒有可見標籤時，請用 aria-label 提供可存取名稱。

通知

<!-- host: const basicOn = ref(true); function onBasicChange(e: CustomEvent<{ checked: boolean }>) { basicOn.value = e.detail.checked } -->
<div class="settings-row">
  <span>通知</span>
  <gk-switch
    aria-label="通知"
    :checked="basicOn"
    @change="onBasicChange"
  ></gk-switch>
</div>

尺寸

尺寸列舉與 Button、Input 一致：sm、md、lg。軌道仍小於 28 / 34 / 40 的欄位高度。

<gk-switch size="sm" checked aria-label="小"></gk-switch>
<gk-switch size="md" checked aria-label="中"></gk-switch>
<gk-switch size="lg" checked aria-label="大"></gk-switch>

停用

disabled 會阻擋切換。關閉時維持較淡；開啟時軌道仍可清楚辨認。

<gk-switch disabled aria-label="停用（關）"></gk-switch>
<gk-switch disabled checked aria-label="停用（開）"></gk-switch>

附標籤

預設插槽文字會作為可見標籤與可存取名稱。使用 :round="false" 可改為方角軌道（預設為膠囊形）。

電子郵件提醒方角

<!-- host: const labelOn = ref(false); function onLabelChange(e: CustomEvent<{ checked: boolean }>) { labelOn.value = e.detail.checked } -->
<gk-switch :checked="labelOn" @change="onLabelChange">電子郵件提醒</gk-switch>
<gk-switch checked :round="false">方角</gk-switch>

互動場

自由組合屬性並即時預覽。

尺寸 smmdlg checked disabled round

飛航模式

API

Switch Props

Prop	型別	預設值
checked	boolean	false
size	'sm' | 'md' | 'lg'	'md'
disabled	boolean	false
round	boolean	true

round 預設為膠囊形。原始 HTML 的布林屬性無法表達 false；請使用屬性綁定或 Vue 的 :round="false"。

Switch Slots

名稱	說明
default	可選的可見標籤（同時作為可存取名稱）

Switch Events

名稱	說明
change	使用者切換開關；bubbles；composed: true；detail: { checked: boolean }

不使用原生 checkbox 的 input / change。Vue / Alpine 請只綁定此 CustomEvent。

CSS Parts

Part	說明
track	role="switch" 控制項
thumb	軌道內的圓鈕
label	預設插槽容器

無障礙

• 內部控制項：role="switch"，aria-checked 反映 checked。
• 空白鍵與 Enter 可切換。
• 請以預設插槽或 aria-label 提供可存取名稱。
• disabled 時不可切換。