amis TooltipWrapper 文字提示容器从 JSON 配置到浮层渲染的完整指南【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisTooltipWrapper文字提示容器是 amis 前端低代码框架中的轻量级交互组件通过一段 JSON 配置即可为任意内容包裹浮层提示支持 hover / click / focus 多触发方式、四向定位、位置偏移、主题切换与延迟显隐等能力。本文以 docs/zh-CN/components/tooltip-wrapper.md 为主线结合 TooltipWrapper.tsx 渲染器源码、amis-ui 底层交互实现 与对应单元测试帮助读者完整掌握该组件的全部配置项、JSON 写法与底层渲染原理。基本配置hover 与 click 两种最常用姿势当用户鼠标悬停或者点击元素时组件会显示文字提示浮层title可以为浮层添加标题。最小的用法只需要三个字段type、content提示内容与body被包裹的内容。{ type: tooltip-wrapper, content: 提示文字, body: hover 激活文字提示 }trigger用于指定浮层的触发方式默认是hover切换为click后则通过点击激活并可通过title为浮层增加标题行[ { type: tooltip-wrapper, content: 提示文字, body: hover 激活文字提示 }, { type: tooltip-wrapper, title: 标题, content: 提示文字, trigger: click, body: click 激活文字提示 } ]body与 amis 其他容器组件一致支持传入多个子元素SchemaNode 的数组形式。例如做一个「删除」文字加垃圾桶图标的组合提示可以这样配置{ type: tooltip-wrapper, content: 删除提示, inline: true, body: [ { type: tpl, tpl: 删除 }, { className: ml-1, type: icon, icon: trash } ] }底层实现amis 的 TooltipWrapper.tsx 渲染器 通过Renderer({type: tooltip-wrapper})装饰器注册到渲染器工厂body经过render(body, body)递归渲染为任意 amis 子节点因此body可以是模板字符串、单个 Schema 或 Schema 数组。在 TooltipWrapper 单元测试 中分别对 hover 与 click 两种 trigger 做了验证fireEvent.mouseEnter后浮层出现、fireEvent.click后标题与内容都出现在文档中。提示位置placement 四向定位placement提供四种不同方向的展示方式top | left | right | bottom默认值是top。下面用 flex 布局把上、左、右、下四个方向组合在一起展示{ type: flex, justify: space-around, alignItems: center, direction: column, items: [ { type: tooltip-wrapper, content: 提示文字, body: [ {type: icon, icon: arrow-circle-up, className: mr-1}, {type: tpl, tpl: 上} ] }, { type: tooltip-wrapper, content: 提示文字, placement: left, body: [ {type: icon, icon: arrow-circle-left, className: mr-1}, {type: tpl, tpl: 左} ] }, { type: tooltip-wrapper, content: 提示文字, placement: right, body: [ {type: icon, icon: arrow-circle-right, className: mr-1}, {type: tpl, tpl: 右} ] }, { type: tooltip-wrapper, content: 提示文字, placement: bottom, body: [ {type: icon, icon: arrow-circle-down, className: mr-1}, {type: tpl, tpl: 下} ] } ] }底层实现placement最终会透传到 amis-ui 的Overlay浮层定位组件见 amis-ui TooltipWrapper.tsx。渲染出的浮层 DOM 会带上Tooltip--top/Tooltip--left等方位类名方便样式定制参见 Tooltip 组件。位置偏移offset 微调浮层坐标当浮层默认位置与目标元素存在遮挡时可以用offset在垂直、水平方向上做偏移默认值为[0, 0]。数组第一项为水平偏移正数向右第二项为垂直偏移正数向下单位为 px{ type: tooltip-wrapper, title: 标题, content: 文案提示位置偏移 [10, -20], offset: [10, -20], inline: true, body: [ { type: tpl, tpl: 向右偏移10px向上偏移20px } ] }上例中浮层相对默认位置向右偏移 10px、向上偏移 20px。在 offset 单元测试 中传入offset: [19, -22]后断言浮层元素带有offset19,-22属性Overlay内部对非数组的 offset 会兜底为[0, 0]见 amis-ui TooltipWrapper.tsx。展示箭头showArrow 控制指向箭头浮层默认带有一个指向目标元素的小箭头设置showArrow: false即可隐藏{ type: tooltip-wrapper, title: 标题, content: 提示内容, showArrow: false, inline: true, body: [ { type: tpl, tpl: 没有箭头 } ] }底层实现箭头由 Tooltip 组件 渲染类名为Tooltip-arrow同时支持通过tooltipArrowClassName覆盖箭头类名。测试 showArrow 用例 验证了默认情况下.cxd-Tooltip-arrow存在于 DOM设置为false后该节点被移除。主题色tooltipTheme 切换 light / dark组件提供dark和light两种主题默认使用light。暗色主题适合在深色页面上使用[ { type: tooltip-wrapper, title: 标题, content: 文案提示, inline: true, body: [ { type: tpl, tpl: light主题提示 } ] }, { type: tooltip-wrapper, title: 标题, content: 文案提示, inline: true, tooltipTheme: dark, body: [ { type: tpl, tpl: dark主题提示 } ] } ]底层实现主题通过 CSS 类名实现Tooltip 组件 会根据tooltipTheme追加Tooltip--light或Tooltip--dark类名。测试 tooltipTheme 用例 断言tooltipTheme: dark时浮层带有.cxd-Tooltip--dark类。另外注意 amis-ui 的Tooltip组件自身也默认tooltipTheme: light、showArrow: true与文档属性表一致。延迟打开与关闭mouseEnterDelay / mouseLeaveDelaymouseEnterDelay控制浮层延迟展示mouseLeaveDelay控制浮层延迟隐藏单位均为毫秒ms默认值分别为0与300{ type: tooltip-wrapper, title: 标题, content: 提示内容, mouseEnterDelay: 1000, mouseLeaveDelay: 2000, inline: true, body: [ { type: tpl, tpl: 延迟1s展示延迟2s隐藏 } ] }底层实现延迟逻辑由 amis-ui TooltipWrapper.tsx 通过setTimeout实现handleShow使用mouseEnterDelay延迟调用show()handleHide使用mouseLeaveDelay延迟调用hide()并借助模块级变量waitToHide保证多组件切换时旧浮层立即收起。测试 mouseEnterDelay mouseLeaveDelay 用例 精确验证了 300ms / 600ms 延迟下浮层的出现与消失时机。动态文案content 与 title 支持变量映射content和title支持 amis 模板变量映射可以从页面上下文中动态获取提示文案。下面的例子把一段超长文本同时作为内容区超出宽度省略号截断与浮层提示文案{ type: page, data: { text: The longest word in any of the major English language dictionaries is pneumonoultramicroscopicsilicovolcanoconiosis, a word that refers to a lung disease contracted from the inhalation of very fine silica particles, specifically from a volcano; medically, it is the same as silicosis. }, body: { type: tooltip-wrapper, content: ${text}, body: { type: html, style: { overflow: hidden, textOverflow: ellipsis, whiteSpace: nowrap, maxWidth: 300px, display: inline-block }, html: ${text} } } }底层实现渲染器在构造浮层配置时使用 amis-core 的filter方法对title、content以及已废弃的tooltip属性做模板解析见 TooltipWrapper.tsx 渲染器。测试 context data 用例 验证了body、title、content三处的${text}、${text2}变量均被正确替换。内联展示inline 控制容器布局默认情况下内容容器以块级元素渲染div设置inline: true后容器改为内联展示便于将多个提示容器排在同一行[ { type: tooltip-wrapper, content: 文字提示, inline: true, className: p-1 mr-3 border-2 border-solid border-indigo-400, body: 内联容器1 }, { type: tooltip-wrapper, content: 文字提示, inline: true, className: p-1 mr-3 border-2 border-solid border-indigo-400, body: 内联容器2 }, { type: tooltip-wrapper, content: 文字提示, className: p-1 mt-3 border-2 border-solid border-green-400, body: 非内联容器 } ]上例中前两个容器因为inline: true排在同一行第三个容器保持块级布局换行展示。底层实现渲染器根据wrapperComponent或inline决定包裹标签inline为 true 时使用span并追加TooltipWrapper--inline类名见 TooltipWrapper.tsx 渲染器。测试 inline 用例 断言容器带有cxd-TooltipWrapper--inline类。自定义样式style 与 tooltipStylestyle控制内容区样式tooltipStyle控制浮层区样式。两者都支持对象写法{ type: tooltip-wrapper, content: 文字提示(加粗), inline: true, style: { fontStyle: italic }, tooltipStyle: { fontWeight: bold }, body: [ { type: tpl, tpl: 一段文案 } ] }上例中内容区文字显示为斜体浮层提示文字显示为加粗。底层实现两处样式都经由 amis-core 的buildStyle处理且支持基于data的动态样式见 TooltipWrapper.tsx 渲染器。测试 style tooltipStyle 用例 分别断言内容区容器font-style: italic、浮层font-weight: bold。自定义包裹标签wrapperComponentwrapperComponent用于修改内容容器的标签名使容器使用其他 HTML 标签渲染。典型场景是包裹代码块时改为pre标签以保留换行与等宽字体{ type: tooltip-wrapper, content: 文字提示, wrapperComponent: pre, body: function HelloWorld() {\n console.log(Hello World);\n} }底层实现渲染器以wrapperComponent作为包裹元素类型as keyof JSX.IntrinsicElements未配置时按inline回退为span或div见 TooltipWrapper.tsx 渲染器。测试 wrapperComponent 用例 断言页面中存在pre.cxd-TooltipWrapper元素。属性表完整配置参考属性名类型默认值说明typestringtooltip-wrapper指定为文字提示容器组件titlestring文字提示标题contentstring文字提示内容, 兼容之前的 tooltip 属性placementtop \| left \| right \| bottomtop文字提示浮层出现位置tooltipThemelight \| darklight主题样式 默认为 lightoffset[number, number][0, 0]文字提示浮层位置相对偏移量单位 pxshowArrowbooleantrue是否展示浮层指向箭头enterablebooleantrue是否鼠标可以移入到浮层中disabledbooleanfalse是否禁用浮层提示triggerhover \| click \| focus \| Arrayhover \| click \| focushover浮层触发方式支持数组写法[hover, click]mouseEnterDelaynumber0浮层延迟展示时间单位 msmouseLeaveDelaynumber300浮层延迟隐藏时间单位 msrootClosebooleantrue是否点击非内容区域关闭提示inlinebooleanfalse内容区是否内联显示wrapperComponentstringdiv \| span容器标签名bodySchemaNode-内容容器styleObject|string内容区自定义样式tooltipStyleObject|string浮层自定义样式classNamestring内容区类名tooltipClassNamestring文字提示浮层类名tooltipArrowClassNamestring箭头类名进阶补充说明trigger 数组写法trigger支持数组形式如[hover, click]多种触发方式并存。底层 amis-ui TooltipWrapper.tsx 会把 trigger 归一化为数组后按需给子元素挂载onClick/onFocus/onBlur/onMouseOver/onMouseOut事件focus触发方式依赖目标元素可聚焦。enterable 与浮层交互enterable控制鼠标能否移入浮层内部。开启时默认鼠标移入浮层会取消隐藏定时器便于用户在浮层中复制文本或操作链接见 amis-ui TooltipWrapper.tsx。disabled 与 rootClosedisabled为 true 时浮层不再展示Overlay的show条件为this.state.show !disabledrootClose控制点击浮层外区域时是否关闭提示默认开启。自定义类名除className内容区外tooltipClassName与tooltipArrowClassName分别作用于浮层与箭头可用于覆盖默认样式。主题定制接入渲染器通过setThemeClassName将themeCss应用到内容区与浮层并输出 CustomStyle 节点因此该组件可参与 amis 的样式定制体系。总结TooltipWrapper 是 amis 中实现「悬浮/点击文字提示」最直接的方式从最基本的contentbody两字段起步到placement、offset、showArrow、tooltipTheme、延迟显隐、变量映射、内联布局与自定义标签配合style/tooltipStyle/ 三类 className 完成精细化定制。通过本组件对应的渲染器源码、底层交互实现与完整单元测试开发者既可以在业务 JSON 中直接套用上文所有示例也可以深入了解浮层触发、延迟与定位的底层机制在需要时对其进行二次封装。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考