總開關連鎖

把一整組設定收在一個總開關底下。翻動總開關時，元件量測每個子格中心到起點（總開關、網格左上角或網格中心）的距離，依距離比例排出延遲，子開關像漣漪一樣由近到遠依序切換，切換瞬間該格閃一圈強調色光環。子開關也能單獨切換，總開關會即時反映全開、全關或部分（中間顯示「—」）三種狀態。停用的子項不參與連鎖。開關本體（track + thumb）在元件內自行實作，不依賴其他元件；值支援受控／非受控雙模式。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<MasterSwitchCascade/>

    </div>
  );
}

安裝

npx webberui@latest add https://webberui.com/r/master-switch-cascade.json

使用

import { Package, CreditCard, Truck, MessageSquare } from "lucide-react";
import { MasterSwitchCascade } from "@/components/ui/master-switch-cascade";

const items = [
  { id: "orders", label: "訂單更新", icon: <Package /> },
  { id: "payments", label: "付款提醒", icon: <CreditCard /> },
  { id: "shipping", label: "出貨通知", icon: <Truck /> },
  { id: "reviews", label: "評論回覆", icon: <MessageSquare /> },
];

export function NotificationSettings() {
  const [value, setValue] = React.useState<Record<string, boolean>>({
    orders: true,
  });
  return (
    <MasterSwitchCascade
      items={items}
      value={value}
      onChange={setValue}
      masterLabel="全部啟用"
      origin="master"
      spread={600}
      columns={4}
    />
  );
}

Props

MasterSwitchItem

細節

• 延遲公式：每格延遲 = 該格中心到起點的距離 ÷ 所有可參與格子的最遠距離 × spread。最遠距離以所有未停用的格子計算，所以同一格每次的延遲都一樣，節奏穩定。
• 切換規則：總開關為全開時翻動會全部關閉；全關或部分時翻動會全部啟用。只有狀態需要改變的子開關會排入佇列並閃光環。
• 佇列管理：子開關的延遲切換用 setTimeout 佇列排程；再次翻動總開關會先清空佇列，從當下狀態重新起算；元件卸載時一併清除。連鎖途中單獨切換某格，會取消那一格尚未觸發的切換，以手動為準。
• 連鎖進行中，總開關直接顯示目標狀態，不會中途閃成「部分」。
• 三態只計算未停用的子項：停用項的開關狀態不影響總開關。
• CSS 變數：--wb-master-switch-duration（thumb 位移與 track 變色，預設 150ms）、--wb-master-switch-ring（光環時長，預設 400ms）、--wb-master-switch-accent（強調色，由 accent prop 寫入）。

可及性

• 每個子開關是 type="button" 的 role="switch"，以 aria-checked 表示開關狀態，無障礙名稱來自格內的名稱文字；停用項設定 disabled
• 總開關需要表達「部分」狀態，而 role="switch" 不支援 aria-checked="mixed"，因此總開關一律使用 role="checkbox"，aria-checked 為 true／false／mixed，並以 aria-labelledby 指向總開關標題
• 子開關網格為 role="group"，同樣以總開關標題命名
• 所有開關都是原生按鈕，空白鍵與 Enter 皆可切換，並有 focus-visible 外框
• 連鎖完成後，role="status"、aria-live="polite" 區域宣告結果，例如「已啟用 12 項」或「已關閉 11 項」
• 使用者系統開啟「減少動態效果」時，所有子開關同時切換、不閃光環，thumb 也不播放過渡動畫