Material Components Web Tooltip 完整指南安装、无障碍、定位算法与主题定制【免费下载链接】material-components-webModular and customizable Material Design UI components for the web项目地址: https://gitcode.com/gh_mirrors/ma/material-components-webTooltip提示气泡是 Material Components WebMDC Web中的基础交互组件用于在用户悬停、聚焦或点按某个元素时显示说明性文本。本文以 packages/mdc-tooltip/README.md 为骨架结合material/tooltip包的 TypeScript 源码、SCSS 主题模块与测试用例系统讲解从安装、DOM 结构、无障碍标注、两种 Tooltip 类型Plain / Rich的完整用法到源码级的定位算法、显示/隐藏延时、滚动容器适配与 Sass 主题定制帮助你在实际项目中直接落地可访问、可定制、定位可靠的 Tooltip。使用场景与设计定位根据官方文档Plain普通Tooltip 在被激活时显示一段文本标签用于标识某个元素的用途。它应只包含简短、描述性的文本且避免重复 UI 上已有的可见文字。常见使用场景包括展示被截断的完整文本标识某个 UI 控件的用途affordance描述相似元素之间的差异区分带有相关图标的操作Rich富内容Tooltip 通过可选的标题title与按钮actions提供更丰富的上下文和行动指引。常见场景包括对页面某个区域或对象给出使用引导提供信息性、情境化的操作入口从packages/mdc-tooltip/package.json可以看到该组件依赖material/animation、material/base、material/button、material/dom、material/elevation、material/feature-targeting、material/rtl、material/shape、material/theme、material/tokens、material/typography等模块这解释了为何 Rich Tooltip 中可以直接嵌入mdc-button样式且主题定制与 elevation阴影能力是原生内置的。安装与引入安装npm install material/tooltip引入样式use material/tooltip/styles;JavaScript 实例化import {MDCTooltip} from material/tooltip; const tooltip new MDCTooltip(document.querySelector(.mdc-tooltip));更多 JavaScript 导入方式可参考 docs/importing-js.md。需要说明的是组件初始化存在两条硬性校验从 packages/mdc-tooltip/component.ts 的initialize()实现可见Tooltip 根元素必须带有id且文档中必须存在一个以data-tooltip-id或aria-describedby指向该id的锚元素否则会抛出错误MDCTooltip: Tooltip component must have an id. MDCTooltip: Tooltip component requires an anchor element annotated with [aria-describedby] or [data-tooltip-id].无障碍Accessibility要求官方文档对无障碍做了明确约定这也是使用 Tooltip 时必须遵守的规范每个放入 DOM 的 Tooltip 元素必须有唯一的id对应的锚元素必须用aria-describedby属性标注从而建立锚点与 Tooltip 之间的关联不含交互内容如链接或操作按钮的 Rich Tooltip其锚元素同样用aria-describedby标注且 Rich Tooltip 自身使用roletooltip包含交互元素的 Rich Tooltip锚元素改用data-tooltip-id标注。这样屏幕阅读器不会在用户进入 Tooltip 之前就播报其内容用户进入后才能把焦点交给其中的交互元素。此类 Rich Tooltip 的role为dialog而非tooltip锚元素需要设置aria-haspopupdialog并用aria-expanded反映交互型 Rich Tooltip 的可见状态。从源码看这一约定不仅是文档规范也是组件运行时的判定依据packages/mdc-tooltip/foundation.ts 的init()会读取这些属性aria-haspopupdialog且存在aria-expanded时Tooltip 被判定为 interactive交互型data-mdc-tooltip-persistenttrue时判定为 persistent持久型data-mdc-tooltip-has-carettrue时判定为带 caret小箭头的 Rich Tooltip。当交互型 Rich Tooltip 显示/隐藏时foundation.ts 的show()与hide()会同步把锚元素的aria-expanded置为true/false并把 Tooltip 根元素的aria-hidden移除/设置回来保证辅助技术状态始终与视觉状态一致。Plain Tooltip普通 Tooltip典型结构div idtooltip-id classmdc-tooltip roletooltip aria-hiddentrue div classmdc-tooltip__surface mdc-tooltip__surface-animation span classmdc-tooltip__labellorem ipsum dolor/span /div /div为保证定位正确该 Tooltip 元素必须是body的直接子元素不能嵌套在锚元素或其他元素内部。这一点与源码实现一致Plain Tooltip 采用position: fixed见 packages/mdc-tooltip/_tooltip.scss定位基于视口计算因此必须直接挂载在 body 下。锚元素示例a aria-describedbytooltip-id hrefwww.google.com Link /aaria-describedby的值就是关联 Tooltip 的id它把该元素声明为这个 Tooltip 的锚元素。其他 MDC 组件也可以作为锚元素只需加上这个属性即可例如button classmdc-button mdc-button--outlined aria-describedbytooltip-id div classmdc-button__ripple/div span classmdc-button__labelButton/span /buttonbutton classmdc-icon-button material-icons aria-describedbytooltip-idfavorite/button锚元素信息与 Tooltip 重复时的处理如果 Tooltip 中展示的信息与锚元素自身的aria-label重复为避免屏幕阅读器把同一信息播报两遍一次来自aria-label一次来自 Tooltip官方文档建议改用data-tooltip-id标注锚元素从而把 Tooltip 从屏幕阅读器中隐藏button classmdc-icon-button material-icons aria-labeltoggle favorite >div classmdc-tooltip-wrapper--rich button classmdc-button aria-describedbytt0 div classmdc-button__ripple/div span classmdc-button__labelButton/span /button div idtt0 classmdc-tooltip mdc-tooltip--rich aria-hiddentrue roletooltip div classmdc-tooltip__surface mdc-tooltip__surface-animation p classmdc-tooltip__content Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur pretium vitae est et dapibus. Aenean sit amet felis eu lorem fermentum aliquam sit amet sit amet eros. /p /div /div /div注意Rich Tooltip 元素必须是锚元素的兄弟节点锚元素与 Tooltip 需要共同包裹在一个带mdc-tooltip-wrapper--rich类的父容器内否则无法正确定位。这是因为 Rich Tooltip 采用position: absolute见 packages/mdc-tooltip/_tooltip.scss定位基准是包裹它的父容器mdc-tooltip-wrapper--rich本身是position: relativefoundation.ts 在计算时也会把父容器的getBoundingClientRect()左上角作为偏移基准。默认 Rich Tooltip带交互内容div classmdc-tooltip-wrapper--rich button classmdc-button>div classmdc-tooltip-wrapper--rich button classmdc-button />Plain tooltip aligned with the end, center, and start of an anchor element (in a LTR page flow).Rich tooltip aligned with the end and start of an anchor element (in a LTR page flow).视口阈值与有效位置判定官方文档明确Tooltip 与视口边缘之间需要保持32px的阈值距离注意packages/mdc-tooltip/constants.ts中MIN_VIEWPORT_TOOLTIP_THRESHOLD的实际默认值为8文档中的 32px 属于 Material 规范建议值运行时以常量值为准。定位算法的规则如下在候选位置x 轴的 start/center/endy 轴的 above/below中选出能够保持该阈值的有效位置如果所有候选位置都会违反阈值则退而选择一个不与视口碰撞collide的位置用户指定的位置只有在“有效”时才会被采纳若用户指定的位置会导致与视口碰撞则会被覆盖。从 foundation.ts 的determineValidPositionOptions()可以看出这一“先阈值、后视口”的两级筛选逻辑优先返回满足positionHonorsViewportThreshold的位置集合若为空则返回仅满足positionDoesntCollideWithViewport的集合。x 轴与 y 轴的判定分别由positionHonorsViewportThreshold/positionDoesntCollideWithViewport和yPositionHonorsViewportThreshold/yPositionDoesntCollideWithViewport完成foundation.ts。默认位置倾向当用户没有指定位置时Rich Tooltip 默认先选end再选startPlain Tooltip 默认按center → start → end的优先级选择。见 foundation.ts 的possiblePositions数组。锚元素边界类型与间距通过setAnchorBoundaryType()可以指定锚元素的边界类型bounded默认元素有明确的视觉边界如按钮Tooltip 更贴近锚元素间距为 4pxBOUNDED_ANCHOR_GAPunbounded元素没有明确视觉边界如纯文本链接间距为 8pxUNBOUNDED_ANCHOR_GAP。对应实现见 packages/mdc-tooltip/constants.ts 与 foundation.ts。API 参考Sass mixins使用主题 mixin 需要先引入 tooltip 的主题样式模块use material/tooltip;该语句实际转发的是 packages/mdc-tooltip/_index.scss 中的./tooltip-theme即 packages/mdc-tooltip/_tooltip-theme.scss。Mixin说明fill-color($color)设置 Tooltip 的填充色作用于.mdc-tooltip__surface的background-color。rich-fill-color($color)设置 Rich Tooltip 的填充色同时作用于 surface 与 caret 上下表面。label-ink-color($color)设置 Tooltip 标签文字的颜色。rich-text-ink-color($title-color, $content-color, $content-link-color)分别设置 Rich Tooltip 内标题、正文、链接的颜色。shape-radius($radius, $rtl-reflexive)设置 Tooltip 表面的圆角。$rtl-reflexive为true时在 RTL 环境中翻转圆角值默认为false。该 mixin 同时作用于 surface 与 caret 元素另有仅作用于 surface 的surface-shape-radius见 packages/mdc-tooltip/_tooltip-theme.scss。word-break($value, $fallbackValue)设置标签的word-break属性用于强制换行没有空格和连字符的长标签。$fallbackValue可选专为 IE11 准备IE11 不支持break-word不想让 IE11 默认break-all行为的用户可用此 mixin 覆盖。实现中还同时设置了overflow-wrap: anywhere见 packages/mdc-tooltip/_tooltip-theme.scss。z-index($z-index)设置 Tooltip 的 z-index默认9见 packages/mdc-tooltip/_tooltip-theme.scss。show-transition($enter-duration)设置显示动画时长默认150ms。exit-transition($exit-duration)设置隐藏动画时长默认75ms。rich-max-height($max-height)设置 Rich Tooltip 的最大高度。rich-max-width($max-width)设置 Rich Tooltip 的最大宽度默认320px。SCSS 默认变量packages/mdc-tooltip/_tooltip-theme.scss可供参考默认背景为黑色半透明、圆角small、标签文字为text-primary-on-darkRich Tooltip 背景为surface色、标题为text-primary-on-light、正文为黑色 medium 透明度、链接为primary色。除上述低阶 mixin 外组件还提供基于 Material tokens 的主题系统_plain-tooltip-theme.scss提供theme()/theme-styles()支持container-color、container-shape、supporting-text-*系列 token_rich-tooltip-theme.scss则支持container-*含 elevation、surface tint、subhead-*、supporting-text-*、action-*Rich Tooltip 内按钮的 label 颜色、状态层等以及content-overflow-x/y等 token且 action 按钮的样式直接复用了material/button/button-text-theme的theme-styles。MDCTooltip方法方法签名说明setTooltipPosition(position: {xPos?: XPosition, yPos?: YPosition}) void指定 Tooltip 与锚元素的对齐方式详见上文“Tooltip 定位”。当 Tooltip 带 caret 时还可传入withCaretPosPositionWithCaret。setAnchorBoundaryType(type: AnchorBoundaryType) void指定锚元素是bounded有明确边界如按钮还是unbounded无明确边界如文本链接。bounded 锚元素的 Tooltip 比 unbounded 更贴近锚元素未指定时默认bounded。hide() void代理 foundation 的hide方法若 Tooltip 处于显示状态则立即隐藏。isShown() boolean返回 Tooltip 当前是否显示。attachScrollHandler(addEventListenerFn: (event, handler) void) void传入一个可注册事件监听的函数在 Tooltip 显示时为其注册scroll事件处理。适用于锚元素位于可滚动容器非 body内的场景滚动时保持 Tooltip“跟随”锚元素。removeScrollHandler(removeEventHandlerFn: (event, handler) void) void与attachScrollHandler配套使用在 Tooltip 隐藏时移除上述附加的 scroll 处理。setShowDelay(delayMs: number) void指定 Tooltip 显示前的延时默认500ms见 packages/mdc-tooltip/constants.ts。setHideDelay(delayMs: number) void指定 Tooltip 隐藏前的延时默认600ms。源码提示持久型 Rich Tooltip 走的是click事件分支其余类型监听mouseenter、focus、mouseleave、touchstart、touchendpackages/mdc-tooltip/component.ts并在destroy()中对称地移除监听component.ts。显示与隐藏延时默认的显示延时为 500ms、隐藏延时为 600msconstants.ts中的SHOW_DELAY_MS/HIDE_DELAY_MS。显示延时在鼠标进入锚元素、聚焦锚元素、触摸开始时触发foundation.ts隐藏延时在鼠标离开锚元素或 Tooltip、以及 Tooltip 自身失去焦点时触发。在handleAnchorMouseEnter中还有一个细节若 Tooltip 已显示再次进入锚元素会直接show()而不会重新播放显隐动画避免“离开又快速回来”时出现闪烁。滚动容器支持当锚元素位于非 body 的可滚动容器内时需要在 Tooltip 显示/隐藏时分别调用attachScrollHandler/removeScrollHandler注册自定义滚动监听同时组件自身也会监听 window 的scroll与resize事件非持久型 Tooltip 在窗口滚动时直接隐藏handleWindowScrollEventfoundation.ts而 resize/scroll 引发的重定位则通过requestAnimationFrame节流handleWindowChangeEventfoundation.ts。事件组件在 Tooltip 完全隐藏/显示后会触发两个自定义事件packages/mdc-tooltip/constants.tsMDCTooltip:hidden—— 隐藏动画结束后触发MDCTooltip:shown—— 显示完成后触发。事件在handleTransitionEnd中根据当前是否带mdc-tooltip--hide类来区分并分发foundation.ts其中隐藏通知不会在“隐藏过程中又触发显示”的场景下误发。框架集成如果使用 React、Angular 等 JavaScript 框架可以为自己的框架封装 Tooltip。根据需求可以选择Simple Approach: Wrapping MDC Web Vanilla Components简单方式包装原生组件或Advanced Approach: Using Foundations and Adapters进阶方式使用 Foundation 与 Adapter完整说明见 docs/integrating-into-frameworks.md。Foundation 层通过 MDCTooltipAdapter 与 DOM 解耦。该接口定义了getAttribute/setAttribute/addClass/removeClass/getTooltipSize/getAnchorBoundingRect/getViewportWidth/registerEventHandler/notifyHidden/notifyShown等 30 余个方法packages/mdc-tooltip/adapter.ts涵盖属性读写、样式操作、尺寸/边界测量、事件注册与状态通知MDCTooltipFoundation 的defaultAdapter提供了全量空实现便于框架侧只覆盖自己需要的方法。关键行为速查Plain Tooltip必须直接挂在body下position: fixedRich Tooltip必须作为锚元素的兄弟节点并包在mdc-tooltip-wrapper--rich中position: absolute相对父容器定位。无交互内容的 Rich Tooltip 用aria-describedby关联锚元素、roletooltip有交互内容的用data-tooltip-id关联、roledialog、锚元素加aria-haspopupdialog与aria-expanded。持久型 Rich Tooltip 通过data-mdc-tooltip-persistenttrue开启并需要tabindex-1点击切换显隐点击内容内部保持显示。位置计算遵循“优先满足 32px 视口阈值 → 退而满足不碰撞 → 允许越界”的兜底顺序用户指定位置仅在有效时生效。默认显示延时 500ms、隐藏延时 600ms可通过setShowDelay/setHideDelay调整bounded 与 unbounded 锚元素的 Tooltip 间距分别为 4px 与 8px。主题定制既可以使用fill-color、label-ink-color、shape-radius、show-transition等低阶 mixin也可以使用_plain-tooltip-theme/_rich-tooltip-theme提供的 token 化theme()/theme-styles()接口。延伸阅读组件结构mdc-tooltip包采用标准的 component / foundation / adapter 三层架构源码入口为 packages/mdc-tooltip/index.ts同时导出adapter、component、foundation与constants构建产物声明于 packages/mdc-tooltip/package.jsonmain: dist/mdc.tooltip.js。样式入口packages/mdc-tooltip/styles.scss 引入./tooltip并调用tooltip.core-styles核心样式与动画在 packages/mdc-tooltip/_tooltip.scss包含 caret 的 35deg 旋转菱形实现、_animation-scale: 0.8的入场缩放、以及 multiline 截断等。主题实现packages/mdc-tooltip/_tooltip-theme.scss、packages/mdc-tooltip/_plain-tooltip-theme.scss、packages/mdc-tooltip/_rich-tooltip-theme.scss。测试用例packages/mdc-tooltip/test/foundation.test.ts覆盖定位、caret 各位置的 transform 计算等、packages/mdc-tooltip/test/component.test.ts、packages/mdc-tooltip/test/mdc-tooltip.scss.test.ts。【免费下载链接】material-components-webModular and customizable Material Design UI components for the web项目地址: https://gitcode.com/gh_mirrors/ma/material-components-web创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考