shadcn-svelte Tooltip 组件完全指南从 Provider 到 Content 的源码级实战【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelteTooltip提示气泡是 shadcn-svelte 中基于 bits-ui 封装的高频交互组件用于在元素获得键盘焦点或鼠标悬停时展示补充信息。本文以 Tooltip 官方文档 为主线结合 组件源码 与 仓库内真实示例完整讲解安装方式、Provider 架构、Root/Trigger/Content 的用法、嵌套 Provider 场景以及 2025-12 颜色更新帮助你直接在项目中落地一套无障碍、可复制的 Tooltip 方案。组件架构一览shadcn-svelte 的 Tooltip 由 5 个可组合子组件构成全部通过 index.ts 统一导出为命名空间形式子组件底层实现职责Tooltip.Roottooltip.svelte状态容器绑定open开关Tooltip.Triggertooltip-trigger.svelte触发元素支持键盘聚焦Tooltip.Contenttooltip-content.svelte气泡内容与箭头默认渲染在 Portal 中Tooltip.Providertooltip-provider.svelte全局协调器控制同一时刻只打开一个 TooltipTooltip.Portaltooltip-portal.svelte将气泡渲染到 body 层级避免父级overflow/z-index干扰从 index.ts 可以看到除了命名空间别名还同时导出了TooltipContent、TooltipTrigger等扁平命名两种引用方式等价。所有组件都直接透传 bits-ui 的RootProps/ContentProps/ProviderProps因此 bits-ui Tooltip 的全部配置能力都保留给了调用方。安装与 shadcn-svelte 其他组件一致Tooltip 提供 CLI 与手动两种安装路径二者等价。CLI 一键安装在项目根目录执行npx shadcn-sveltelatest add tooltipCLI 会自动解析依赖、写入组件文件并处理样式与注册表配置。对于使用 pnpm 的项目可替换为pnpm dlx shadcn-sveltelatest add tooltipnpm 用户则使用npx。手动安装安装运行时依赖bits-uinpm install bits-ui -D将仓库docs/src/lib/registry/ui/tooltip/目录下的 6 个文件index.ts、tooltip.svelte、tooltip-trigger.svelte、tooltip-content.svelte、tooltip-provider.svelte、tooltip-portal.svelte复制到你的$lib/components/ui/tooltip/目录。确保项目中的cn()工具函数一般位于$lib/utils.js与 Tailwind 配置可正常解析组件内部使用的cn()与data-slot类。使用三步搭好全局 Tooltip第一步在根布局挂载 ProviderTooltip.Provider是协调中心官方文档明确要求它只放置一次并且包裹所有可能包含 Tooltip 的内容以保证在 Provider 作用域内同一时刻只有一个 Tooltip 处于打开状态。在src/routes/layout.svelte中引入script langts import * as Tooltip from $lib/components/ui/tooltip/index.js; let { children } $props(); /script然后在模板中包裹插槽Tooltip.Provider {render children()} /Tooltip.Provider从 tooltip-provider.svelte 源码可见Provider 的默认参数为delayDuration 0即悬停后立即显示不附加延迟...restProps会把 bits-ui Provider 的其他配置如skipDelayDuration、disableHoverableContent等透传下去。第二步组合 Root / Trigger / Content在任意页面或组件中使用script langts import * as Tooltip from $lib/components/ui/tooltip/index.js; /script Tooltip.Root Tooltip.TriggerHover/Tooltip.Trigger Tooltip.Content pAdd to library/p /Tooltip.Content /Tooltip.Root这是仓库 tooltip-demo 演示的官方标准用法。结合源码补充说明Root见 tooltip.svelte声明open $bindable(false)因此你可以通过bind:open受控管理 Tooltip 的开合状态例如配合快捷键或按钮切换显示。Trigger见 tooltip-trigger.svelte透传 bits-ui Trigger自动获得键盘聚焦Tab 聚焦后按 Enter/Space与鼠标悬停两种触发方式并带有data-slottooltip-trigger标识方便样式钩子。Trigger 本身不产生额外 DOM 包装直接渲染在触发元素上。Content见 tooltip-content.svelte默认渲染在TooltipPortal中默认side top、sideOffset 0并内置了可选的箭头TooltipPrimitive.Arrow。它还支持arrowClasses与portalProps两个额外属性分别用于定制箭头样式和 Portal 行为。第三步结合按钮组件增强样式仓库演示中常将 Trigger 与按钮变体组合例如 tooltip-demo.svelteTooltip.Provider Tooltip.Root Tooltip.Trigger class{buttonVariants({ variant: outline })}Hover/Tooltip.Trigger Tooltip.Content pAdd to library/p /Tooltip.Content /Tooltip.Root /Tooltip.ProviderbuttonVariants由$lib/registry/ui/button/index.js或你项目中的$lib/components/ui/button/index.js导出直接复用按钮视觉体系让触发元素与页面其他按钮风格统一。进阶技巧嵌套 Provider 与分组配置官方文档提供了一个高频场景嵌套 Provider。Tooltip 遵循最近祖先 Provider原则——当页面同时存在外层与内层 Provider 时内层 Tooltip 使用距离最近的 Provider 配置。这非常适合在特定区域覆盖全局设置Tooltip.Provider delayDuration{0} !-- Tooltips here will open instantly -- /Tooltip.Provider外层 Provider 若设置了较长的delayDuration例如 700ms作为全站统一延迟内层嵌套delayDuration{0}的 Provider 即可让该区域 Tooltip 即时弹出典型用于工具栏、图标按钮密集区域。仓库示例 tooltip-basic.svelte 等大量示例也印证了Provider包裹Root的标准层级结构。实战扩展仓库示例中的边界场景禁用状态下仍可触发 Tooltip原生 disabled 按钮不会触发鼠标事件Tooltip 因而失效。仓库 tooltip-disabled.svelte 给出了官方解法用Tooltip.Trigger的childsnippet 包一层span把触发行为交给外层 spanTooltip.Root Tooltip.Trigger {#snippet child({ props })} span classinline-block w-fit {...props} Button variantoutline disabledDisabled/Button /span {/snippet} /Tooltip.Trigger Tooltip.Content pThis feature is currently unavailable/p /Tooltip.Content /Tooltip.Rootchildsnippet 让 Trigger 把事件与无障碍属性aria-describedby等附着到包裹 span 上从而在禁用按钮场景下也能弹出说明气泡。同类技巧也见于 tooltip-on-link.svelte、tooltip-with-icon.svelte 等示例。控制气泡方位Tooltip.Content支持 bits-ui 的side属性默认top。仓库 tooltip-sides.svelte 用#each遍历四种方位验证其可用性{#each [top, right, bottom, left] as const as side (side)} Tooltip.Root Tooltip.Trigger {#snippet child({ props })} Button variantoutline classw-fit capitalize {...props}{side}/Button {/snippet} /Tooltip.Trigger Tooltip.Content {side} pAdd to library/p /Tooltip.Content /Tooltip.Root {/each}此外sideOffset默认 0用于调整气泡与触发元素的间距当空间不足时bits-ui 的浮层逻辑会自动翻转方位Content 源码中的origin-(--bits-tooltip-content-transform-origin)类即配合翻转做入场动画。格式化内容与键盘提示Tooltip 内容不止于纯文本仓库还提供了 tooltip-formatted.svelte富文本/多行排版与 tooltip-with-keyboard.svelte在气泡内展示kbd快捷键等示例均可作为扩展样式参考。仓库其余模块如 Sidebar 的 sidebar-menu-button.svelte、Bubble 的 bubble-tooltip.svelte也在内部复用了 Tooltip 组件可作为大型组件组合使用的样板。2025-12 样式更新Foreground/Background 配色方案官方文档记录了 2025-12 的一次重要样式变更Tooltip 颜色由bg-primary text-primary-foreground改为bg-foreground text-background即气泡背景使用前景色、文字使用背景色。这一调整在 tooltip-content.svelte 的源码中已生效class{cn( cn-tooltip-content z-50 w-fit max-w-xs origin-(--bits-tooltip-content-transform-origin) bg-foreground text-background, className )}箭头部分同样跟随新方案见同文件 tooltip-content.svelte 的cn-tooltip-arrow bg-foreground fill-foreground。如果你在旧版本或自定义主题中仍使用bg-primary text-primary-foreground请替换为bg-foreground text-background保证与新版主题体系一致。同时注意Content 的类前缀为cn-tooltip-content、cn-tooltip-arrow可通过这些稳定类名在全局 CSS 中追加自定义样式宽度约束为w-fit max-w-xs超出即换行避免超长内容撑破布局默认z-50层级配合 Portal 渲染可覆盖绝大多数页面层级。无障碍与可访问性要点基于 bits-ui 底层实现Tooltip 开箱即用具备以下无障碍特性可从 Trigger/Content 透传属性推断键盘可触发Tab 聚焦 Trigger 后按 Enter/Space 即可显示气泡无需鼠标ARIA 关联Content 自动挂载roletooltip并通过aria-describedby与 Trigger 建立关联屏幕阅读器可朗读气泡内容焦点与悬停双路径鼠标悬停与键盘聚焦共享同一套开合状态均由 Root 的open绑定统一管理。如需完全受控可在 Root 上使用bind:open将开合状态提升到父组件便于实现首次访问引导条件显示等业务逻辑。小结安装npx shadcn-sveltelatest add tooltip或手动复制 tooltip 目录 并安装bits-ui架构Provider全局唯一→ Root → Trigger → ContentContent 默认经 Portal 渲染并带箭头关键配置Provider 的delayDuration默认 0、Content 的side默认 top与sideOffset默认 0、Root 的bind:open禁用态处理使用 Trigger 的childsnippet 包裹 span参考 tooltip-disabled.svelte配色更新统一采用bg-foreground text-background勿再使用旧版bg-primary text-primary-foreground。按以上步骤即可在 shadcn-svelte 项目中快速获得一套键盘友好、样式统一、可深度定制的 Tooltip 体系需要查看更多边界示例时可直接浏览仓库的 create/tooltip 示例集。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考