shadcn-svelte Toggle Group 组件全解析从 2023 年 11 月 Changelog 到源码实现【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelteToggle Group 是 shadcn-svelte 在 2023 年 11 月更新中加入的一组双态按钮集合组件允许用户在多个可切换按钮之间进行单选或多选常用于富文本工具栏、筛选器与视图切换等场景。本文以该版本更新的官方变更记录为起点结合组件文档、注册表条目与底层源码完整讲解其安装方式、基础用法、API 属性、官方示例以及 Context 传递与样式合并的实现原理帮助你直接上手并在项目中正确复用。组件发布背景2023 年 11 月的 Changelog在仓库的 docs/content/changelog/2023-11-toggle-group.md 中本次更新的描述非常简洁Weve added a new component to the library, Toggle Group.该条目对应日期为2023-11-01主题即为新增Toggle Group组件。同一内容也收录在汇总页 docs/content/changelog.md 的 November 2023 小节中。围绕该组件仓库提供了完整的组件文档 docs/content/components/toggle-group.md其元数据将其定位为A set of two-state buttons that can be toggled on or off.即一组可开可关的双态按钮。它本质上是一个受控的按钮组容器内部每个条目都具备独立的按下 / 未按下状态与单个 Toggle 组件共享视觉样式体系但增加了组级别的选择逻辑。Toggle Group 是什么定位与典型使用场景Toggle Group 适用于需要在一组互斥或并存的选项之间切换的场景典型包括富文本工具栏加粗 / 斜体 / 下划线 / 删除线等格式开关多选视图切换列表视图 / 网格视图 / 分栏视图单选内容筛选按类型筛选条目单选或多选均可图标动作组收藏、点赞、标记等带图标的小按钮集合。它与单个Toggle组件的区别在于Toggle只表达一个按钮是否被按下通过pressed双向绑定而ToggleGroup.Root通过typesingle | multiple管理整组的选择状态并由value属性统一暴露给外部。所有条目共享 Root 传入的variant、size、spacing配置无需逐个重复设置。安装方式组件文档 docs/content/components/toggle-group.md 提供了 CLI 与手动两种安装路径。方式一CLI 安装使用 shadcn-svelte CLI 一条命令即可添加命令来源见 pm-add-comp.svelte 中的shadcn-sveltelatest add ${name}模板shadcn-sveltelatest add toggle-groupCLI 会自动解析包管理器pnpm / npm / yarn / bun支持逻辑见 docs/src/lib/package-manager.ts并同步写入所需的依赖与源码文件。方式二手动安装先安装bits-uiToggle Group 的底层原语库安装为开发依赖npm install -D bits-ui # 或 pnpm add -D bits-ui / yarn add -D bits-ui / bun add -D bits-ui将以下三个文件复制到你的src/lib/components/ui/toggle-group/目录下完整内容见 docs/static/registry/toggle-group.jsontoggle-group/index.ts—— 模块出口导出Root/Item及别名ToggleGroup/ToggleGroupItemtoggle-group/toggle-group.svelte—— 组容器Roottoggle-group/toggle-group-item.svelte—— 组内条目Item。从注册表条目可以看到该组件声明的依赖关系devDependenciesbits-ui^2.14.4、internationalized/date^3.10.0、tailwind-variants^3.2.2registryDependencies[toggle]—— 表示它依赖 Toggle 组件 提供的toggleVariants样式工厂。基础用法组件文档给出的最小用法如下先引入命名空间script langts import * as ToggleGroup from $lib/components/ui/toggle-group/index.js; /script再在模板中组合 Root 与 ItemToggleGroup.Root typesingle ToggleGroup.Item valueaA/ToggleGroup.Item ToggleGroup.Item valuebB/ToggleGroup.Item ToggleGroup.Item valuecC/ToggleGroup.Item /ToggleGroup.Root要点typesingle表示整组最多选中一项切换新项会自动取消旧项改为typemultiple则允许多项同时保持开启每个Item的value是该条目在组内的唯一标识Root 的value通过$bindable()暴露保存当前选中值或选中值数组组件文档中标注该组件需要bits-ui若使用图标按钮请在Item上补充aria-label以保证可访问性详见下文官方示例。API 一览Root 与 Item 的属性依据源码 toggle-group.svelte 与 toggle-group-item.svelte 中的属性声明整理如下ToggleGroup.Root属性类型默认值说明typesingle \| multiple—必传来自 bits-ui选择模式单选或多选value$bindable()—当前选中值single 为值multiple 为数组可双向绑定ref$bindable()null根元素引用classstring—追加到根元素的样式类variantdefault \| outlinedefault视觉风格与 Toggle 组件一致sizedefault \| sm \| lgdefault尺寸规格spacingnumber0条目之间的间距像素大于 0 时条目彼此分离orientationhorizontal \| verticalhorizontal排列方向...restProps——透传给底层 bits-ui Root 的其余属性如disabledToggleGroup.Item属性类型默认值说明valuestring—条目在组内的唯一标识ref$bindable()null条目元素引用classstring—追加的样式类variant/size—继承 Root可单独覆盖未设置时回退到 Root 上下文值...restProps——透传给 bits-ui Item如disabled、aria-label从源码可见Item在渲染时使用ctx.variant || variant与ctx.size || size见 toggle-group-item.svelte即先取 Root 上下文再回退到条目自身的覆盖值实现了组级配置 条目级微调的双层机制。从源码看实现Context 传递与组合关系Context 机制组配置如何下发给每个 ItemRoot 组件在script langts module中定义了组上下文工具函数见 toggle-group.svelteexport function setToggleGroupCtx(props: ToggleGroupContext) { setContext(toggleGroup, props); } export function getToggleGroupCtx() { return getContextRequiredToggleGroupContext(toggleGroup); }Root 渲染时通过setToggleGroupCtx将variant、size、spacing、orientation以响应式 getter 形式写入 Svelte ContextItem 则在初始化时调用getToggleGroupCtx()读取。这样每个 Item 无需显式传参即可获得组级配置同时data-variant、data-size、data-spacing等数据属性也会被写到 DOM 上供 Tailwind 变体选择器使用。样式变体复用与 Toggle 共享的 toggleVariantsToggle Group 的视觉样式完全复用了 Toggle 组件 中用tailwind-variants声明的toggleVariantsexport const toggleVariants tv({ base: cn-toggle group/toggle inline-flex items-center ..., variants: { variant: { default: cn-toggle-variant-default, outline: cn-toggle-variant-outline }, size: { default: cn-toggle-size-default, sm: cn-toggle-size-sm, lg: cn-toggle-size-lg }, }, defaultVariants: { variant: default, size: default }, });因此整组按钮与单个 Toggle 在外观上保持严格一致这也是注册表条目将toggle列为registryDependencies的原因。spacing 的实现CSS 变量驱动Root 将spacing同时写入数据属性与内联样式见 toggle-group.sveltestyle{--gap: ${spacing}} class{cn( cn-toggle-group group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))]>ToggleGroup.Root variantoutline typemultiple ToggleGroup.Item valuebold aria-labelToggle bold BoldIcon classh-4 w-4 / /ToggleGroup.Item ToggleGroup.Item valueitalic aria-labelToggle italic ItalicIcon classh-4 w-4 / /ToggleGroup.Item ToggleGroup.Item valuestrikethrough aria-labelToggle strikethrough UnderlineIcon classh-4 w-4 / /ToggleGroup.Item /ToggleGroup.Root注意纯图标条目必须提供aria-label否则屏幕阅读器无法获知按钮含义。Outline与基础 Demo 相同的variantoutlinetypemultiple组合见 toggle-group-outline.svelte演示描边风格下条目边框的合并效果spacing0时相邻条目会去掉内侧边框形成一整块带圆角的描边按钮组。Single单选模式示例toggle-group-single.svelteToggleGroup.Root typesingle ToggleGroup.Item valuebold aria-labelToggle bold BoldIcon classsize-4 / /ToggleGroup.Item ToggleGroup.Item valueitalic aria-labelToggle italic ItalicIcon classsize-4 / /ToggleGroup.Item ToggleGroup.Item valuestrikethrough aria-labelToggle strikethrough UnderlineIcon classsize-4 / /ToggleGroup.Item /ToggleGroup.Root同一时刻只允许一个条目处于按下状态适合视图切换等互斥选择场景。Small / Large尺寸示例分别设置sizesmtoggle-group-sm.svelte与sizelgtoggle-group-lg.svelte。对应的尺寸类定义在 docs/src/lib/registry/styles/style-nova.css 中.cn-toggle-size-default { apply h-8 min-w-8 px-2.5 ...; } .cn-toggle-size-sm { apply h-7 min-w-7 px-2.5 text-[0.8rem] ...; } .cn-toggle-size-lg { apply h-9 min-w-9 px-2.5 ...; }即默认高 32px、sm 高 28px、lg 高 36pxmin-w保证窄内容下仍保持正方形触控区。Disabled整组禁用示例toggle-group-disabled.svelteToggleGroup.Root disabled typesingle ... /ToggleGroup.Root在 Root 上直接传disabled经restProps透传给底层 bits-ui 原语整组按钮不可交互toggleVariants的 base 中已包含disabled:pointer-events-none disabled:opacity-50禁用态会自动呈现半透明效果。Spacing带间距的分隔按钮组文档明确指出使用spacing{2}即可在条目之间添加间距。官方示例toggle-group-spacing.svelte组合了variantoutline、spacing{2}与sizesm并演示了按选中状态给图标着色ToggleGroup.Root typemultiple variantoutline spacing{2} sizesm ToggleGroup.Item valuestar aria-labelToggle star classdata-[stateon]:bg-transparent>.cn-toggle-group-item { apply group-data-[spacing0]/toggle-group:rounded-none group-data-[spacing0]/toggle-group:px-2 ... group-data-horizontal/toggle-group:data-[spacing0]:first:rounded-l-lg group-data-vertical/toggle-group:data-[spacing0]:first:rounded-t-lg group-data-horizontal/toggle-group:data-[spacing0]:last:rounded-r-lg group-data-vertical/toggle-group:data-[spacing0]:last:rounded-b-lg; }含义为间距为 0 时去除条目自身的圆角与内边距仅给组的首尾条目保留对应方向的圆角水平方向左端首项rounded-l、右端末项rounded-r并配合相邻条目去内边框border-l-0/border-t-0的逻辑最终渲染为整块描边按钮组。一旦设置spacing 0这些合并规则失效条目恢复独立圆角并通过--gap产生间距——这正是两种外观形态的切换原理。小结Toggle Group 是 shadcn-svelte 中组合式 UI设计的典型代表它以 bits-ui 原语为交互底座通过 Svelte Context 在组内下发variant/size/spacing配置复用toggleVariants保证与单个 Toggle 的外观一致并用 CSS 变量与数据属性驱动spacing和边框合并逻辑。无论你是通过shadcn-sveltelatest add toggle-group一键接入还是手动复制 docs/static/registry/toggle-group.json 中的三个文件都可以立即在富文本工具栏、筛选器或视图切换等场景中使用它如需进一步探索其实现可直接阅读 docs/src/lib/registry/ui/toggle-group/ 下的源码与 docs/src/lib/registry/examples/ 中的示例。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考