企业官网建设流程全解析

• UI组件
• 前端

本篇指南围绕 Ariakit 仓库中的官方示例examples/menu-tooltip展开：通过renderprop 将MenuButton与TooltipAnchor两个行为组件合并为单个按钮，实现"点击打开菜单、悬停显示 Tooltip"的双重交互。读完本文，你将理解 Ariakit 的render组合模式如何在单一 DOM 元素上叠加多套事件与 ARIA 行为，并掌握该示例中焦点转移、全局 Tooltip 时序等机制的源码级原理。

示例结构总览

官方示例 examples/menu-tooltip/index.react.tsx 完整代码不长，核心结构如下（图标部分做了缩略，完整 SVG 见原文件）：

import { Menu, MenuButton, MenuItem, MenuProvider, Tooltip, TooltipAnchor, TooltipProvider, VisuallyHidden, } from "@ariakit/react"; export default function Example() { return ( <MenuProvider> <TooltipProvider> <TooltipAnchor className="button" render={<MenuButton />}> <VisuallyHidden>Accessibility Shortcuts</VisuallyHidden> {icon} </TooltipAnchor> <Tooltip className="tooltip">Accessibility Shortcuts</Tooltip> </TooltipProvider> <Menu className="menu" gutter={4}> <MenuItem className="menu-item">VoiceOver</MenuItem> <MenuItem className="menu-item">Zoom</MenuItem> <MenuItem className="menu-item">Invert Colours</MenuItem> <MenuItem className="menu-item">Colour Filters</MenuItem> <MenuItem className="menu-item">Increase Contrast</MenuItem> <MenuItem className="menu-item">Reduce Transparency</MenuItem> </Menu> </MenuProvider> ); }

从源码结构看，整个示例的组织要点有三处：

1. 两个独立的 Provider：MenuProvider与TooltipProvider互不嵌套依赖，分别向内部组件注入菜单 store 和 tooltip store 的上下文。MenuButton通过useMenuProviderContext()获取菜单 store（见 menu-button.tsx 中store = store || context），TooltipAnchor同理从useTooltipProviderContext()获取 tooltip store（见 tooltip-anchor.tsx）。
2. 组合发生在TooltipAnchor上：<TooltipAnchor render={<MenuButton />}>表示"渲染一个MenuButton，但再叠加 TooltipAnchor 的全部行为"。这是 Ariakit Composition（组合）模式的核心用法，详见 guide/300-composition/readme.md。
3. 可访问名称：按钮内使用<VisuallyHidden>Accessibility Shortcuts</VisuallyHidden>提供视觉上隐藏但读屏可见的文本，再配合aria-hidden的 SVG 图标，保证锚点元素拥有可访问名称（accessible name）。TooltipAnchor源码的注释也明确提示：Tooltip 纯属视觉用途，锚点的可访问名称必须由开发者自行保证。

配套样式 examples/menu-tooltip/style.css 中为.button定义了按钮外观、为.tooltip定义了提示气泡外观，为.menu定义了菜单浮层样式，与仓库中其他示例的样式约定一致。

render 组合原理：单元素上的行为叠加

组合写法的本质只有一行：

<TooltipAnchor render={<MenuButton />}>

其机制可以从两层来理解：

行为链：外层组件 hook 后处理渲染元素

每个 Ariakit 组件的行为都封装在use*hook 中（如useTooltipAnchor、useMenuButton），返回一组事件处理器与 ARIA 属性；组件本体只是createElement(TagName, htmlProps)的薄封装。

当TooltipAnchor传入render={<MenuButton />}时，useTooltipAnchor返回的 props 会附着在<MenuButton />这个元素上。而MenuButton内部先执行自己的useMenuButton生成菜单按钮行为，再由createElement(TagName, withDefaultButtonType(htmlProps))渲染。因此最终产出的 DOM 上同时拥有：

• useMenuButton提供的：onClick（点击切换菜单开合，toggleOnClick: !hasParentMenu）、onKeyDown（方向键打开菜单并将初始焦点设为"first"/"last"）、onFocus、aria-haspopup等；
• useTooltipAnchor提供的：onMouseEnter（置位canShowOnHoverRef并调用showOnHover）、onFocusVisible（键盘聚焦即显示 tooltip，store.show()）、onBlur（失焦时清理全局活跃 tooltip 状态）以及aria-labelledby。

两层的ref、className、事件属性会按 Composition 指南所述规则合并：style、className、ref和事件 props 自动合并，渲染元素上显式定义的 props 会覆盖原组件 props（undefined值则被忽略）。

默认标签名差异：div 承载 button

一个容易忽略的细节：TooltipAnchor的默认标签是div（const TagName = "div" satisfies ElementType），而MenuButton的默认标签是button。正因为render把宿主换成了MenuButton，最终渲染出来的是<button>，保留了按钮的原生语义与键盘可激活性。反过来写（MenuButton通过render渲染TooltipAnchor）则会导致按钮退化为div，失去原生 button 特性——这就是示例中组合方向必须选TooltipAnchor render={<MenuButton />}的原因。

焦点转移与 Tooltip 隐藏时序

这个示例里最精妙的部分是：点击按钮打开菜单时，焦点会自动转移到菜单（store.setAutoFocusOnShow(true)+store.setInitialFocus("container")，见 menu-button.tsx 的onClick），此时 Tooltip 必须可靠地消失且不会在鼠标未离开按钮时"闪回"。TooltipAnchor源码中有三处针对性处理：

1. canShowOnHoverRef标志：仅在onMouseEnter时置为true；一旦挂载状态变化（tooltip 关闭）会被重置为false。showOnHover回调在该标志为false时直接返回，保证"失焦后再移回鼠标"不会立即触发 tooltip。
2. onBlur中的双重清理（tooltip-anchor.tsx）：锚点失焦时，把canShowOnHoverRef置false（注释明确写道：锚点是菜单按钮时，点击按钮会自动把焦点移到菜单上，此时不应让 tooltip 延迟重新出现），并把全局 store 中的activeStore清空，阻止后续 tooltip 零延迟弹出。
3. 全局活跃 tooltip 管理：TooltipAnchor用一个模块级globalStore（createStore<{ activeStore: TooltipStore | null }>）记录当前活跃 tooltip。当一个 tooltip 打开时立即隐藏上一个活跃 tooltip 并记为自己，使连续在不同锚点间悬停时无需等待showTimeout；关闭时则按skipTimeout延迟移除。hidingStores这个WeakSet则用于避免被强制重新打开的 tooltip 之间形成重入循环。

此外，TooltipAnchor还会从 store 的contentElement（即Tooltip挂载的元素）读取其id，在锚点上写入aria-labelledby（前提是未显式提供aria-label），进一步把 tooltip 文本纳入锚点的可访问名称解析。

组合模式的使用边界

guide/300-composition/readme.md 对renderprop 的行为边界做了权威说明，写本文示例这类组合代码时需要留意：

• 替换 HTML 元素：render可接收任意元素，如<Combobox render={<textarea rows={5} />} />；本示例即借此把 tooltip 锚点的宿主换成带完整菜单行为的MenuButton。
• props 合并优先级：style、className、ref与事件 props 自动合并；render元素上显式设置的 props（包括null）覆盖原组件 props，undefined被忽略。例如<ComboboxItem id="item" render={<a id="link" />} />最终渲染为id="link"。
• 自定义组件必须"开放扩展"：指南专门以警告框强调，用render渲染自定义组件时，该组件必须能透传 props（包括ref和事件），否则组合的行为会丢失。本示例能成立的前提，正是MenuButton本身就是一个可被render二次渲染的组件。
• 组合多个行为组件的通用套路：把"最终宿主"放在最内层render值上，外层组件依次叠加额外行为；需要多个 store 时，为每个子系统提供对应 Provider，store 通过各自 context 自动注入，无需手动传递。

小结与延伸

本示例用不到 40 行代码展示了 Ariakit 的三个关键能力：Provider 注入的 store 上下文、renderprop 的行为叠加组合、以及围绕焦点转移的 Tooltip 时序控制。若要在此基础上扩展，可以参考仓库中以下同类示例继续学习组合模式：

• examples/menu-item-checkbox：菜单项内嵌复选框；
• examples/menu-nested：嵌套子菜单（子菜单按钮同样经由MenuButton的hasParentMenu分支渲染为div，见 menu-button.tsx 中 Safari 兼容注释）；
• examples/combobox-disclosure：下拉按钮 + 过滤列表的组合形态。

相关组件文档见 components/menu.md 与 components/tooltip.md；TooltipAnchor的showOnHover、store等选项类型定义在 tooltip-anchor.tsx 底部的TooltipAnchorOptions，MenuButton的typeahead、store等选项在 menu-button.tsx 的MenuButtonOptions中有完整 JSDoc 说明。

• UI组件
• 前端