For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/components/switch.md.

开关

开关立即切换一个独立设置的开启或关闭状态，不用于需要提交表单后才生效的选择。若远程更新可能失败，控件应保持可交互，播报进行中或被拒绝的结果，并在拒绝时恢复先前值。

飞行模式

飞行模式已关闭。

安装Terminal

npm install @a3s-lab/ui

<input type="checkbox" role="switch" class="input" />

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

用法

引入 CSS

导入 Tailwind 和一个完整的 A3S UI 样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

或者仅导入基本 CSS、Switch 组件 CSS 和一个样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/switch.css";
@import "@a3s-lab/ui/styles/a3s.css";

使用CDN或批量程序导入？请参见安装页。

添加开关 HTML

Add class="input" and role="switch" to a native checkbox. Use a native <label> or aria-label for accessible naming.

<input type="checkbox" role="switch" class="input" />

HTML 结构

<input type="checkbox" role="switch" class="input">: The switch control. Use native checkbox state: add checked for an initially enabled switch, disabled for a disabled switch, and aria-invalid="true" for invalid state.
data-size="sm" Optional: Renders the smaller switch size.

示例

说明

Share across devices

Focus is shared across devices, and turns off when you leave the app.

<div role="group" class="field" data-orientation="horizontal">
  <section>
    <label for="switch-focus-mode">Share across devices</label>
    <p id="switch-focus-mode-description">Focus is shared across devices, and turns off when you leave the app.</p>
  </section>
  <input type="checkbox" id="switch-focus-mode" role="switch" class="input" aria-describedby="switch-focus-mode-description" />
</div>

卡片式选项

需要点击整张卡片来切换开关时，请使用 <label> 包裹卡片。

Share across devices

Focus is shared across devices, and turns off when you leave the app.

Enable notifications

Receive notifications when focus mode changes.

<div role="group" class="grid w-full gap-3" aria-label="Focus settings">
  <label>
    <div role="group" class="field" data-orientation="horizontal">
      <section>
        <h3>Share across devices</h3>
        <p>Focus is shared across devices, and turns off when you leave the app.</p>
      </section>
      <input type="checkbox" role="switch" class="input" />
    </div>
  </label>
  <label>
    <div role="group" class="field" data-orientation="horizontal">
      <section>
        <h3>Enable notifications</h3>
        <p>Receive notifications when focus mode changes.</p>
      </section>
      <input type="checkbox" role="switch" class="input" defaultChecked />
    </div>
  </label>
</div>

远程接受与拒绝

持久化由宿主负责。这些固定示例证明：接受时保留新值，拒绝时恢复先前值。

同步专注设置（拒绝）

此示例始终拒绝远程更新并恢复先前值。

准备同步。

同步专注设置（接受）

此示例始终接受远程更新。

准备同步。

<div class="grid gap-4">
    <div class="grid gap-3" data-switch-remote-demo="zh" data-switch-remote-outcome="reject" data-switch-value="off">
      <div role="group" class="field" data-orientation="horizontal">
        <section>
          <label for="switch-remote-reject-zh">同步专注设置（拒绝）</label>
          <p id="switch-remote-reject-zh-description">此示例始终拒绝远程更新并恢复先前值。</p>
        </section>
        <input type="checkbox" id="switch-remote-reject-zh" role="switch" class="input" aria-describedby="switch-remote-reject-zh-description"
          data-preview-onchange="const demo = document.querySelector('[data-switch-remote-demo=zh][data-switch-remote-outcome=reject]'); const status = demo.querySelector('[data-switch-status]'); const next = this.checked; this.setAttribute('aria-busy', 'true'); this.checked = !next; status.textContent = '同步被拒绝，已恢复先前设置。'; demo.setAttribute('data-switch-value', this.checked ? 'on' : 'off'); demo.setAttribute('data-switch-remote-result', 'rejected'); this.removeAttribute('aria-busy');" />
      </div>
      <p data-switch-status aria-live="polite">准备同步。</p>
    </div>
    <div class="grid gap-3" data-switch-remote-demo="zh" data-switch-remote-outcome="accept" data-switch-value="off">
      <div role="group" class="field" data-orientation="horizontal">
        <section>
          <label for="switch-remote-accept-zh">同步专注设置（接受）</label>
          <p id="switch-remote-accept-zh-description">此示例始终接受远程更新。</p>
        </section>
        <input type="checkbox" id="switch-remote-accept-zh" role="switch" class="input" aria-describedby="switch-remote-accept-zh-description"
          data-preview-onchange="const demo = document.querySelector('[data-switch-remote-demo=zh][data-switch-remote-outcome=accept]'); const status = demo.querySelector('[data-switch-status]'); const next = this.checked; this.setAttribute('aria-busy', 'true'); status.textContent = next ? '同步已接受，设置已开启。' : '同步已接受，设置已关闭。'; demo.setAttribute('data-switch-value', next ? 'on' : 'off'); demo.setAttribute('data-switch-remote-result', 'accepted'); this.removeAttribute('aria-busy');" />
      </div>
      <p data-switch-status aria-live="polite">准备同步。</p>
    </div>
  </div>

已禁用

当周围字段应使用禁用样式时，将 disabled 添加到开关，将 data-disabled="true" 添加到字段包装器。保留标签与原因可见。

已禁用

仅组织所有者可以更改此设置。

<div role="group" class="field" data-orientation="horizontal" data-disabled="true">
  <input type="checkbox" id="switch-disabled-unchecked" role="switch" class="input" disabled />
  <section>
    <label for="switch-disabled-unchecked">已禁用</label>
    <p>仅组织所有者可以更改此设置。</p>
  </section>
</div>

无效

将 aria-invalid="true" 添加到开关，并将 data-invalid="true" 添加到字段包装器。

接受条款与条件

必须接受条款与条件才能继续。

<div role="group" class="field" data-orientation="horizontal" data-invalid="true">
  <section>
    <label for="switch-invalid">接受条款与条件</label>
    <p>必须接受条款与条件才能继续。</p>
  </section>
  <input type="checkbox" id="switch-invalid" role="switch" class="input" aria-invalid="true" />
</div>

尺寸

使用data-size="sm"渲染较小的开关尺寸。

Small

Default

<div role="group" class="grid w-full gap-4" aria-label="Switch sizes">
  <div role="group" class="field" data-orientation="horizontal">
    <input type="checkbox" id="switch-size-sm" role="switch" class="input" data-size="sm" />
    <label for="switch-size-sm">Small</label>
  </div>
  <div role="group" class="field" data-orientation="horizontal">
    <input type="checkbox" id="switch-size-default" role="switch" class="input" />
    <label for="switch-size-default">Default</label>
  </div>
</div>

RTL

切换字段布局使用文档方向。在字段或祖先上设置 dir="rtl"。

المشاركة عبر الأجهزة

يتم مشاركة التركيز عبر الأجهزة، ويتم إيقاف تشغيله عند مغادرة التطبيق.

<div dir="rtl" role="group" class="field" data-orientation="horizontal">
  <section>
    <label for="switch-rtl">المشاركة عبر الأجهزة</label>
    <p id="switch-rtl-description">يتم مشاركة التركيز عبر الأجهزة، ويتم إيقاف تشغيله عند مغادرة التطبيق.</p>
  </section>
  <input type="checkbox" id="switch-rtl" role="switch" class="input" aria-describedby="switch-rtl-description" defaultChecked />
</div>

#开关

#用法

引入 CSS

添加开关 HTML

#HTML 结构

#示例

#说明

#卡片式选项

Share across devices

Enable notifications

#远程接受与拒绝

#已禁用

#无效

#尺寸

#RTL

开关

用法

HTML 结构

示例

说明

卡片式选项

远程接受与拒绝

已禁用

无效

尺寸

RTL