在 coss 设计系统中掌握 Tooltip：基于 Base UI 的悬停提示组件实战指南

前端UI组件设计系统【免费下载链接】cosscoss.com/ui is the official design system of Cal.com项目地址https://gitcode.com/gh_mirrors/or/coss点击查看免费下载导读Tooltip 是界面中最常见却最容易被忽视的非阻塞提示组件。在 cossCal.com 官方设计系统中coss/tooltip是基于 Base UITooltip的完整封装提供了Tooltip、TooltipTrigger、TooltipPopup、TooltipProvider、TooltipCreateHandle五个开箱即用的 API并内置了 portal 转发、分组联动与动画过渡能力。本文以 tooltip.md 为骨架结合 tooltip.tsx 源码与p-tooltip-1至p-tooltip-4粒子示例完整讲解安装方式、标准用法、图标按钮场景、分组提示、分离触发器动画以及常见误区帮助你写出既符合无障碍规范又具有一致体验的提示交互。什么时候该用 Tooltip以及什么时候不该用在设计系统中Tooltip 的职责非常窄在悬停或聚焦时为控件和图标提供简短辅助文本且不打断用户当前操作流。✅适合使用控件与图标上的短提示文案如Settings、Copy link、非阻塞的上下文提示不需要模态行为的轻量说明。❌不适合使用内容含交互元素链接、按钮→ 应改用Popover内容为富文本、图片或表单 → 应改用PreviewCard或Popover提示需要常驻直至用户手动关闭 → 应改用Popover。这条边界在 coss 中是有明确定义的Tooltip 只承载信息性内容任何需要用户点击操作或长文展示的场景都应升级到带模态语义的浮层组件。这既是交互规范也是可访问性的基本要求。安装方式一CLI 一键安装npx shadcnlatest add coss/tooltip该命令会将 tooltip.tsx 复制到项目的components/ui/tooltip.tsx并自动处理依赖。方式二手动安装安装运行时依赖Base UInpm install base-ui/react复制components/ui/tooltip.tsx的代码到你的项目按项目结构调整/registry/default/lib/utils等导入路径。安装完成后按文档推荐的规范方式导入官方用法import { Tooltip, TooltipCreateHandle, TooltipPopup, TooltipProvider, TooltipTrigger, } from /components/ui/tooltip最小可用模式一个 Tooltip 由三个部件组成Tooltip根、TooltipTrigger触发元素、TooltipPopup提示气泡。核心用法如下Tooltip TooltipTrigger render{Button variantoutline /} Hover me /TooltipTrigger TooltipPopupHelpful hint/TooltipPopup /Tooltip注意TooltipTrigger使用了 Base UI 的render属性将按钮渲染为触发元素这是 coss 组件组合的标准手法——既保留原生按钮的语义与样式又让触发逻辑附着其上。该模式在粒子示例 p-tooltip-1.tsx 中得到了完整复现。核心 API 解析源自源码TooltipPopup在 tooltip.tsx 中的实现把Portal → Positioner → Popup → Viewport四层结构完整暴露给了使用者并在默认值上做了贴近实际使用的设定部件说明Tooltip根组件Base UITooltip.Root的别名负责开关状态与事件逻辑TooltipTrigger触发元素Base UITooltip.Trigger的别名带data-slottooltip-triggerTooltipPopup提示气泡包裹Portal/Positioner/Popup/Viewport同时导出别名TooltipContentTooltipProvider分组提供者Base UITooltip.Provider的别名TooltipCreateHandle创建分离触发器句柄Base UITooltip.createHandle的别名TooltipPopup的关键 props 及默认值如下与 官方文档 API 表 一致Prop类型默认值说明sidetop \| bottom \| left \| righttop提示气泡相对触发元素的方位alignstart \| center \| endcenter相对触发元素的对齐方式sideOffsetnumber4气泡与触发元素之间的像素距离anchorPositioner.Props[anchor]-自定义锚点元素portalPropsTooltip.Portal.Props-转发给内部Portal的 propskeepMounted、container等classNamestring-透传到Popup的样式类从源码可以确认sideOffset、side、align会透传给内部的Positionertooltip.tsx而portalProps则展开在TooltipPrimitive.Portal上tooltip.tsx。气泡默认带z-50层级、bg-popover背景、text-xs字号与圆角边框并内置了进入/退出的 scale 与 opacity 过渡样式。Portal 转发portalPropscoss 的多个浮层组件都在*Popup上暴露了portalProps用于转发 Base UIPortal的底层能力详见 portal-props.mdkeepMounted保持浮层挂载在 DOM 中需要组件对应的Portal类型支持container将浮层渲染到指定 DOM 节点适用于堆叠上下文、微前端或 Shadow DOM 场景该组件Portal.Props接受的其他 props包括适用的className/ref。一个典型场景是微前端架构中需要把提示渲染到特定容器TooltipPopup portalProps{{ container: document.getElementById(tooltip-root) }} Helpful hint /TooltipPopup需要明确的是portalProps只影响portal 节点本身。要调整气泡的位置应使用side、align、sideOffset等定位参数或组合 Base UI 的Positioner。实战模式一图标按钮上的 Tooltip纯图标按钮没有可见文字Tooltip 是最自然的补充说明方式。但仅仅加 Tooltip 是不够的——图标按钮仍必须有可访问名称accessible namecoss 的规范做法是同时在aria-label中提供tooltip.mdTooltip TooltipTrigger render{Button sizeicon variantghost aria-labelSettings /} SettingsIcon aria-hiddentrue / /TooltipTrigger TooltipPopupSettings/TooltipPopup /Tooltip这里两个细节值得注意aria-labelSettings为纯图标按钮提供屏幕阅读器可读的名称图标本身用aria-hiddentrue对辅助技术隐藏Tooltip 文案与aria-label保持一致使悬停用户与读屏用户获得相同语义。在 Cal.com 示例应用中有更复杂的封装——TooltipIconButton组件把图标 Tooltip aria-label收敛成一个可复用组件booking-actions.tsx/booking/booking-actions.tsx#L249-L268)function TooltipIconButton({ icon, label, variant outline, }: { icon: React.ReactNode; label: string; variant?: React.ComponentPropstypeof Button[variant]; }) { return ( Tooltip TooltipTrigger render{ Button aria-label{label} sizeicon variant{variant} {icon} /Button } / TooltipPopup{label}/TooltipPopup /Tooltip ); }随后在预订操作栏中以TooltipIconButton icon{XIcon /} labelReject variantoutline /的形式批量使用同时配合Group/GroupSeparator形成紧凑的工具按钮组。这是图标按钮 Tooltip在企业级表单界面中的典型落地形态。实战模式二分组 Tooltip共享延迟当页面中存在一组相邻的 Tooltip 时默认逐个出现会造成闪烁和噪音。Base UI 的Tooltip.Provider提供了分组逻辑一旦组内某个 Tooltip 可见相邻的 Tooltip 会立即显示无需等待各自的延迟。coss 将其封装为TooltipProviderTooltipProvider Tooltip TooltipTriggerItem 1/TooltipTrigger TooltipPopupHint 1/TooltipPopup /Tooltip Tooltip TooltipTriggerItem 2/TooltipTrigger TooltipPopupHint 2/TooltipPopup /Tooltip /TooltipProvider该模式的真实示例是 p-tooltip-2.tsx——一个文本格式工具栏Bold、Italic、Underline三个ToggleGroupItem图标按钮分别被 Tooltip 包裹外层由TooltipProvider统一管理延迟TooltipProvider ToggleGroup defaultValue{[bold]} multiple Tooltip TooltipTrigger render{ToggleGroupItem aria-labelToggle bold valuebold /} BoldIcon / /TooltipTrigger TooltipPopupBold/TooltipPopup /Tooltip {/* Italic / Underline 同理 */} /ToggleGroup /TooltipProvider这正是组内多个 Tooltip 共享一个 provider、相互间无感知延迟的推荐写法。实战模式三分离触发器的动画 Tooltip分组 Tooltip 解决的是多个独立气泡的节奏问题而动画 Tooltip 解决的是**多个触发器共享一个气泡**的位置/尺寸/内容平滑过渡问题。coss 通过TooltipCreateHandle实现用TooltipCreateHandle创建句柄可指定载荷类型如ComponentType将同一个handle附加到多个TooltipTrigger上每个触发器通过payload提供各自的内容组件用单个Tooltip承载该句柄渲染气泡气泡内容由 render prop 从payload解出。参考 p-tooltip-3.tsxconst tooltipHandle TooltipCreateHandleComponentType(); const BoldContent () spanMake text bold/span; const ItalicContent () spanApply italic formatting to text/span; const UnderlineContent () spanUnderline text/span; export default function Particle() { return ( TooltipProvider ToggleGroup defaultValue{[bold]} multiple TooltipTrigger handle{tooltipHandle} payload{BoldContent} render{ToggleGroupItem aria-labelToggle bold valuebold /} BoldIcon aria-hiddentrue / /TooltipTrigger {/* Italic / Underline 触发器同样绑定 tooltipHandle */} /ToggleGroup Tooltip handle{tooltipHandle} {({ payload: Payload }) ( TooltipPopup{Payload ! undefined Payload /}/TooltipPopup )} /Tooltip /TooltipProvider ); }鼠标在不同格式按钮之间横向移动时单个气泡会自动在触发器之间动画切换位置、尺寸与文本内容而不是每个按钮各弹各的气泡。这正是分离触发器模式的核心价值。p-tooltip-4.tsx 则展示了分离触发器与Group组件结合、气泡定向到右侧sideright并限宽max-w-40的变体——它把分享语义的复制链接、邮件、社交媒体三个操作收进一个垂直Group共享同一个动画气泡。更多示例与跨组件参考在 coss 中每个组件示例被称为particle。与 Tooltip 相关的粒子及其定位如下粒子主题p-tooltip-1基础 Tooltip最小用法p-tooltip-2分组 TooltipTooltipProviderp-tooltip-3动画 Tooltip分离触发器 TooltipCreateHandlep-tooltip-4分离触发器 Group组合、sideright变体跨浮层组件的参考粒子包括p-dialog-1、p-popover-1、p-menu-2可用于理解 Tooltip 与 Dialog、Popover、Menu 在定位、Portal 与交互语义上的差异。所有粒子源码可在 apps/ui/registry/default/particles 目录下查看注册表入口见 registry-particles.ts。常见误区与无障碍检查清单coss 文档明确列出了三类最常见的误用tooltip.md在提示内容里放交互控件——Tooltip 必须保持纯信息性需要交互请升级为Popover让 Tooltip 成为图标控件的唯一标签——纯图标按钮仍必须提供可访问名称aria-label否则读屏用户无法识别用 Tooltip 承载长文本——长内容应使用Popover或DialogTooltip 只适合一两句话的短提示。结合源码可以提炼出以下自查清单图标触发元素是否同时具备aria-label与 Tooltip 文案装饰性图标是否设置了aria-hiddentrue提示内容是否只含静态文本无链接、按钮、表单文本长度是否足以在气泡内一行或两行展示多个相邻 Tooltip 是否已用TooltipProvider分组以消除延迟闪烁在微前端 / Shadow DOM / 特殊堆叠上下文场景下是否通过portalProps.container指定了正确的挂载节点总结coss 的coss/tooltip组件在保持短提示、非阻塞、信息性这一核心定位的同时通过 Base UI 的底层能力提供了portalProps转发、TooltipProvider分组联动和TooltipCreateHandle分离触发器动画三类高级能力。掌握最小用法解决 80% 的场景用TooltipProvider优化工具栏等密集提示区域的体验用分离触发器实现无缝动画过渡——再配合aria-label守住无障碍底线即可在设计系统内交付一致、专业且易用的提示交互。更完整的 API 说明与示例可在 组件文档 与粒子目录 particles 中继续深入。赞分享前端UI组件设计系统【免费下载链接】cosscoss.com/ui is the official design system of Cal.com项目地址https://gitcode.com/gh_mirrors/or/coss点击查看免费下载相关推荐在 Kaneo 中使用 coss Toast基于 Base UI 的 toastManager 通知体系实战指南在 Kaneo 中使用 coss Toast基于 Base UI 的 toastManager 通知体系实战指南 导读 Kaneo 是一款开源的轻量级项目管理企业应用后端前端Kaneo 前端体系中的 coss Fieldset 组件基于 Base UI 的语义化表单分组实现指南Kaneo 前端体系中的 coss Fieldset 组件基于 Base UI 的语义化表单分组实现指南 导读 Fieldset 是 coss 组件库本仓库企业应用后端前端回测引擎选型gs-quant 里 4 个维度决定走本地还是云回测引擎选型gs quant 里 4 个维度决定走本地还是云 用 Python 做量化回测时绕不开的决策是回测在哪跑、用哪个执行器。gs quant 是一前端UI组件设计系统上一篇Android Architecture Samples性能分析使用Profiler优化应用性能下一篇Go HTTP中间件开发build-web-application-with-golang中的请求拦截器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考