For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt, and this page is available as Markdown at /next/zh/ui/components/switch.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • Switch

    一个适用于 ReactLynx 的无样式开关组件,提供切换状态基础能力。
    Info

    你可以查看源码来了解它的运行原理,也欢迎大家提 PR 来丰富其能力。

    基础用法

    <Switch> 的基本使用方式

    示例

    主题控制

    用受控模式(checked + onChange)驱动页面主题切换,并让 token 变化自动影响 Switch 的视觉表现。示例同时展示组合组件 ThemedSwitch 与基于 primitives 的按需组合;更多主题封装方式可参考样式与主题。

    结构

    <Switch>
      <SwitchTrack />
      <SwitchThumb />
    </Switch>

    组件 API

    Switch

    Props for the Switch component.

    checkediOSAndroid
    类型boolean
    是否选中。如果设置了 checked,则 Switch 将处于受控模式,此时 defaultChecked 将被忽略。
    classNameiOSAndroidHarmony
    类型string
    类名
    defaultCheckediOSAndroid
    类型boolean·默认值false
    默认选中状态,仅在非受控模式下生效。
    disablediOSAndroid
    类型boolean·默认值false
    是否禁用,当为 true 时用户无法操作。
    onChangeiOSAndroid
    类型(checked: boolean) => void
    状态变化时触发的回调函数。参数 checked 表示最新的选中状态。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    switchPropsiOSAndroid
    类型ViewProps
    Switch 支持将原始视图属性直接展开到这个属性中。
    childreniOSAndroid
    类型ReactNode | ((status: { checked: boolean; active: boolean; disabled: boolean }) => ReactNode)
    Switch 的内容,可以是节点或根据状态动态渲染的函数。

    基于状态的样式与渲染

    该组件通过以下一种或两种方式暴露运行时状态。下表仅展示每个状态实际支持的方式:

    • UI variant class:支持时,对应组件节点会动态加上 ui-<state> 形式的类名,可用 .ui-<state> { ... } 选择器定制样式;
    • Render-prop 字段:支持时,当 children 传入函数,状态会以 children({ <state>: boolean, ... }) 的形式作为参数传入,便于在运行时做条件渲染。

    UI variants applied by Switch based on its render state.

    类名渲染属性类型说明
    ui-activeactiveboolean是否处于激活状态(按下或交互中)。 当 status.active 为 true 时生效,可用于 `.ui-active { ... }`。
    ui-checkedcheckedboolean是否选中。 当 status.checked 为 true 时生效,可用于 `.ui-checked { ... }`。
    ui-disableddisabledboolean是否禁用。 当 status.disabled 为 true 时生效,可用于 `.ui-disabled { ... }`。

    SwitchTrack

    The track of the Switch. Represents the background area on which the thumb slides. Can also be used for pressed overlays or state decorations.

    childreniOSAndroid
    类型ReactNode
    轨道的内容插槽,可用于添加覆盖层或状态装饰。
    classNameiOSAndroidHarmony
    类型string
    类名
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    UI variants applied by SwitchTrack.

    类名说明
    ui-active是否处于激活状态(按下或交互中)。 当 status.active 为 true 时生效,可用于 `.ui-active { ... }`。
    ui-checked是否选中。 当 status.checked 为 true 时生效,可用于 `.ui-checked { ... }`。
    ui-disabled是否禁用。 当 status.disabled 为 true 时生效,可用于 `.ui-disabled { ... }`。

    SwitchThumb

    The thumb of the Switch. The draggable/clickable handle that toggles the state.

    childreniOSAndroid
    类型ReactNode
    手柄的内容插槽,可放置自定义元素(如图标)。
    classNameiOSAndroidHarmony
    类型string
    类名
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    UI variants applied by SwitchThumb.

    类名说明
    ui-active是否处于激活状态(按下或交互中)。 当 status.active 为 true 时生效,可用于 `.ui-active { ... }`。
    ui-checked是否选中。 当 status.checked 为 true 时生效,可用于 `.ui-checked { ... }`。
    ui-disabled是否禁用。 当 status.disabled 为 true 时生效,可用于 `.ui-disabled { ... }`。
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。