Tooltip 工具提示

工具提示用于对一个元素进行标识或者附上少量辅助信息，最典型的场景是向用户解释图标的含义、展示被截断的文本、显示图片的描述等。

代码演示

如何引入

import { Tooltip } from '@kousum/semi-ui-vue';

注意事项

Tooltip 需要将 DOM 事件监听器应用到 children 中，如果子元素是自定义的组件，你需要确保它能将属性传递至底层的 DOM 元素

同时为了计算弹出层的定位，需要获取到 children 的真实 DOM 元素，因此 Tooltip 支持如下类型的 children

1. Class Component，不强制绑定ref，但需要确保 props 可被透传至真实的 DOM 节点上
2. 使用 forwardRef 包裹后的函数式组件，将 props 与 ref 透传到 children 内真实的 DOM 节点上
3. 真实 DOM 节点, 如 span，div，p...

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

30

 

1

import { Tooltip, Space } from '@kousum/semi-ui-vue';

2

​

3

const style={ border: '2px solid var(--semi-color-border)', paddingLeft: '4px', paddingRight: '4px', borderRadius: '4px' };

4

​

5

// 将props属性传递，绑定ref

6

const FCChildren = (props) => {

7

  return (<span {...props} style={style}>Functional Component</span>);

8

};

9

​

10

// 将props属性传递

11

const MyComponent = (props)=><span {...props} style={style}>ClassComponent</span>

12

​

13

function Demo() {

14

    return (

15

        <Space>

16

            <Tooltip content={'semi design'}>

17

                <FCChildren />

18

            </Tooltip>

19

            <Tooltip content={'semi design'}>

20

                <MyComponent />

21

            </Tooltip>

22

            <Tooltip content={'semi design'}>

23

                <span style={style}>DOM</span>

24

            </Tooltip>

25

        </Space>

26

    );

27

}

Show Error

Auto Save

位置

可以通过 position 配置弹出层方向以及对齐位置，position 详细可选值请参考下方 API 文档
配置为 top 时 向上弹出
配置为 topLeft 时，向上弹出，且弹出层与 children 左对齐（当arrowPointAtCenter=false时）
配置为 topRight 时，向上弹出，且弹出层与 children 右对齐（当arrowPointAtCenter=false时）
其他方向同理

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

99

 

1

import { Tooltip, Tag } from '@kousum/semi-ui-vue';

2

​

3

function Demo() {

4

    const tops = [

5

        ['topLeft', 'TL'],

6

        ['top', 'Top'],

7

        ['topRight', 'TR'],

8

    ];

9

    const lefts = [

10

        ['leftTop', 'LT'],

11

        ['left', 'Left'],

12

        ['leftBottom', 'LB'],

13

    ];

14

    const rights = [

15

        ['rightTop', 'RT'],

16

        ['right', 'Right'],

17

        ['rightBottom', 'RB'],

18

    ];

19

    const bottoms = [

20

        ['bottomLeft', 'BL'],

21

        ['bottom', 'Bottom'],

22

        ['bottomRight', 'BR'],

23

    ];

24

​

25

    return (

26

        <div>

27

            <div style={{ marginLeft: '80px', whiteSpace: 'nowrap' }}>

28

                {tops.map((pos, index) => (

Show Error

Auto Save

指向元素中心

默认情况下 arrowPointAtCenter=true，小三角始终指向 children 元素中心位置。 你可以将其设置为 false，此时小三角将不再保持指向元素中心。弹出层与 children 边缘对齐

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

26

 

1

import { Tooltip, Button } from '@kousum/semi-ui-vue';

2

​

3

function Demo() {

4

    return (

5

        <>

6

            <div>

7

                <Tooltip

8

                    position='topLeft'

9

                    content='semi design tooltip'>

10

                    <Button type='secondary' style={{ marginRight: '8px' }}>指向元素中心</Button>

11

                </Tooltip>

12

            </div>

13

​

14

            <div style={{ marginTop: '20px' }}>

15

                <Tooltip

16

                    content='semi design tooltip'

17

                    arrowPointAtCenter={false}

18

                    position='topLeft'

19

                >

20

                    <Button type='secondary' style={{ marginRight: '8px', width: '120px' }}>边缘对齐</Button>

21

                </Tooltip>

22

            </div>

23

        </>

24

    );

25

};

26

export default Demo

Show Error

Auto Save

触发时机

• 配置触发展示的时机，默认为 hover，可选 hover/focus/click/custom/ 'contextMenu'
• 设为 custom 时，需要配合 visible 属性使用，此时显示与否完全受控
• contextMenu 右键触发在 v 2.42.0 后开始提供

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

47

 

1

import { Tooltip, Button, Input, RadioGroup, Radio } from '@kousum/semi-ui-vue';

2

import { defineComponent, ref } from 'vue';

3

​

4

​

5

const Demo = defineComponent(() => {

6

​

7

  const visible = ref(false);

8

  // container 需要设置 position: relative

9

  const getPopupContainer = () => document.querySelector('#tooltip-container');

10

​

11

  return () => (

12

    <div style={{ width: '100%', height: '100%', overflow: 'hidden', position: 'relative' }} id="tooltip-container">

13

      <div style={{ width: '150%', height: '150%', paddingLeft: '50px', paddingTop: '50px' }}>

14

        <Tooltip content={'hi bytedance'} getPopupContainer={getPopupContainer}>

15

          <Button theme='solid' type='tertiary' style={{ marginBottom: '20px' }}>悬停显示</Button>

16

        </Tooltip>

17

        <br />

18

        <Tooltip content={'hi bytedance'} trigger="click" getPopupContainer={getPopupContainer}>

19

          <Button style={{ marginBottom: '20px' }}>点击显示</Button>

20

        </Tooltip>

21

        <br />

22

        <Tooltip content={'hi bytedance'} trigger="focus" getPopupContainer={getPopupContainer}>

23

          <Input style={{ width: '100px', marginBottom: '20px' }} placeholder="聚焦显示" />

24

        </Tooltip>

25

        <br />

26

        <Tooltip content={'hi bytedance'} trigger="contextMenu" getPopupContainer={getPopupContainer}>

27

          <Button theme='solid' type='secondary' style={{ marginBottom: '20px' }}>右键点击展示</Button>

28

        </Tooltip>

29

        <br />

30

        <Tooltip

31

          content={'hi bytedance'}

Show Error

Auto Save

覆盖特定样式

你可以通过 className、style 为弹出层配置特定样式，例如覆盖默认的 maxWidth （280px）

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

17

 

1

import { Tooltip, Tag } from '@kousum/semi-ui-vue';

2

​

3

export default () => {

4

    return (

5

        <div>

6

            <Tooltip

7

                style={{

8

                    maxWidth: '320px'

9

                }}

10

                className='another-classname'

11

                content={'hi semi semi semi semi semi semi semi'}

12

            >

13

                <Tag style={{ marginRight: '8px' }}>Custom Style And ClassName</Tag>

14

            </Tooltip>

15

        </div>

16

    );

17

};

Show Error

Auto Save

渲染至指定 DOM

传入 getPopupContainer，弹层将会渲染至该函数返回的 DOM 中。 这会改变浮层 DOM 树位置，但不会改变视图渲染位置。

需要注意的是： 返回的容器如果不是 document.body，position 需要设为 "relative"（版本 >= 0.18.0）。

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

17

 

1

import { Tooltip, Tag } from '@kousum/semi-ui-vue';

2

​

3

function Demo() {

4

    return (

5

        <div id="tooltip-wrapper" style={{ position: 'relative' }}>

6

            <Tooltip

7

                position="right"

8

                content="浮层被渲染至#tooltip-wrapper元素中"

9

                trigger="click"

10

                getPopupContainer={() => document.querySelector('#tooltip-wrapper')}

11

            >

12

                <Tag>点击此处</Tag>

13

            </Tooltip>

14

        </div>

15

    );

16

}

17

export default Demo

Show Error

Auto Save

搭配 Popover 或 Popconfirm 使用

Tooltip、Popconfirm、Popover 都需要劫持 children 的相关事件（onMouseEnter/onMouseLeave/onClick....），用于配置 trigger。
如果直接嵌套使用的话，会使外层 trigger 失效。
需要在中间加一层元素（div 或 span）以防止 trigger 的事件劫持失效。

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

11

 

1

import { Tooltip, Popconfirm, Button } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <Popconfirm content="是否确认删除" title='确认' style={{ width: '320px' }}>

5

        <span style={{ display: 'inline-block' }}>

6

            <Tooltip content={'删除评价'}>

7

                <Button type="danger">删除</Button>

8

            </Tooltip>

9

        </span>

10

    </Popconfirm>

11

);

Show Error

Auto Save

仅当内容宽度超出时展示 Tooltip

Semi 为这种场景提供了 Typography 组件，可以更简单快捷地满足需求。不需要自己再对 Tooltip 的出现做条件判断，详细的使用请参考Typography 组件文档

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

29

 

1

import { Typography } from '@kousum/semi-ui-vue';

2

const { Paragraph, Title, Text } = Typography;

3

​

4

function Demo() {

5

​

6

    return (

7

        <div>

8

            <Title heading={5} ellipsis={{ showTooltip: true }} style={{ width: '250px' }}>

9

                是一个很长很长很长很长5号标题

10

            </Title>

11

            <br />

12

            <Text link ellipsis={{ showTooltip: true, pos: 'middle' }} style={{ width: '150px' }}>

13

                是一个很长很长很长很长的链接

14

            </Text>

15

            <br />

16

            <br />

17

            <Paragraph

18

                ellipsis={{ rows: 3, showTooltip: { type: 'popover', opts: { style: { width: '300px' } } } }}

19

                style={{ width: '300px' }}

20

            >

21

                多行截断，展示 Popover：Semi Design 是由抖音前端团队与 UED

22

                团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件，帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的

23

                Web 应用。

24

            </Paragraph>

25

        </div>

26

    );

27

}

28

​

29

export default Demo

Show Error

Auto Save

API 参考

---

属性	说明	类型	默认值	版本
autoAdjustOverflow	弹出层被遮挡时是否自动调整方向	boolean	true
arrowPointAtCenter	“小三角”是否指向元素中心，需要同时传入"showArrow=true"	boolean	true
content	弹出层内容	string|ReactNode
className	弹出层的样式名	string
clickToHide	点击弹出层及内部任一元素时是否自动关闭弹层	boolean	false
disableFocusListener	trigger为hover时，不响应键盘聚焦弹出浮层事件，详见issue#977	boolean	false	2.17.0
getPopupContainer	指定父级 DOM，弹层将会渲染至该 DOM 中，自定义需要设置 position: relative 这会改变浮层 DOM 树位置，但不会改变视图渲染位置。	function():HTMLElement	() => document.body
keepDOM	关闭时是否保留内部组件不销毁	boolean	false	2.31.0
margin	计算溢出时的增加的冗余值，详见issue#549	number ｜ MarginObject	0	2.23.0
mouseEnterDelay	鼠标移入后，延迟显示的时间，单位毫秒（仅当 trigger 为 hover/focus 时生效）	number	50
mouseLeaveDelay	鼠标移出后，延迟消失的时间，单位毫秒（仅当 trigger 为 hove/focus 时生效），不小于 mouseEnterDelay	number	50
motion	是否展示弹出层动画	boolean	true
position	弹出层展示位置，可选值：top, topLeft, topRight, left, leftTop, leftBottom, right, rightTop, rightBottom, bottom, bottomLeft, bottomRight	string	'top'
prefixCls	弹出层 wrapper div 的 className 前缀，设置该项时，弹出层将不再带 Tooltip 的样式	string	'semi-tooltip'
preventScroll	指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的 focus 方法	boolean
rePosKey	可以更新该项值手动触发弹出层的重新定位	string|number
style	弹出层的内联样式	object
spacing	弹出层与 children 元素的距离，单位 px（object类型自 v2.45后支持）	number ｜ SpacingObject	8
showArrow	是否显示箭头三角形	boolean	true
stopPropagation	是否阻止弹层上的点击事件冒泡	boolean	false	0.34.0
transformFromCenter	是否从包裹的元素水平或垂直中心处变换，该参数仅影响动效变换的 transform-origin，一般无需改动	boolean	true
trigger	触发展示的时机，可选值：hover / focus / click / custom / contextMenu (v2.42后提供)	string	'hover'
visible	是否展示弹出层	boolean
wrapperClassName	当 children 为 disabled ，或者 children 为多个元素时，外层将会包裹一层 span 元素，该 api 用于设置此 span 的样式类名	string
wrapperId	弹出层 wrapper 节点的 id，trigger 的 aria 属性指向此 id，若不设置组件会随机生成一个 id	string		2.11.0
zIndex	弹层层级	number	1060
onVisibleChange	弹出层展示/隐藏时触发的回调	function(isVisible:boolean)
onClickOutSide	当弹出层处于展示状态，点击非Children、非浮层内部区域时的回调（仅trigger为custom、click时有效）	function(e:event)		2.1.0

Accessibility

ARIA

• Tooltip 具有 tooltip role，遵循 WAI-ARIA 规范中对于 Tooltip 的定义
• Tooltip 的 content 与 children
  • 关于 content
    • content 的 wrapper 会被自动添加 id 属性，用于与 children 的 aria-describedby 匹配，关联 content 与 children
  • 关于 children
    • Tooltip 的内容（content）与其触发器（children）之间应当具有显式联系。Tooltip 会自动为 children 元素添加 aria-describedby 属性，值为 content wraper的 id
    • 若你 Tooltip的children 是Icon，不包含可见文本，我们推荐你在 children 上添加 aria-label 属性进行相应描述

// Good practices, add aria-label to description tooltip children
/* eslint-disable */
<Tooltip content={<p id='description'>Edit your setting</p>}>
    <IconSetting aria-label='Settings'> 
    </IconSetting>
</Tooltip>

文案规范

• 只展示信息说明和引导，不展示报错信息
• 不在 tooltip 里只能是额外的链接和按钮
• 尽量精简至一句话进行说明，不展示标点符号

设计变量

other

motion

color

radius

spacing

font

width

height

animation

变量	默认值	用法
$horizontal-rate	0.24	水平方向矫正因子
$vertical-rate	0	垂直方向矫正因子

显示第 1 条-第 2 条，共 2 条

• 1

变量	默认值	用法
$motion-zoom_scale-from	0.8	初始缩放 - 动画用
$motion-zoom_opacity-from	0	初始透明度 - 动画用
$motion-zoom_opacity-to	1	最终透明度 - 动画用

显示第 1 条-第 3 条，共 3 条

• 1

变量	默认值	用法
$color-tooltip-bg-default	rgba(var(--semi-grey-7), 1)	工具提示默认背景色
$color-tooltip-text-default	var(--semi-color-bg-0)	工具提示默认文字颜色
$color-tooltip-icon-default	rgba(var(--semi-grey-7), 1)	工具提示默认图标颜色
$color-tooltip_arrow-icon-default	$color-tooltip-icon-default	工具提示默认小三角箭头颜色

显示第 1 条-第 4 条，共 4 条

• 1

变量	默认值	用法
$radius-tooltip	var(--semi-border-radius-medium)	工具提示默认圆角

显示第 1 条-第 1 条，共 1 条

• 1

变量	默认值	用法
$spacing-tooltip_content-paddingLeft	$spacing-base-tight	工具提示内容左侧内边距
$spacing-tooltip_content-paddingRight	$spacing-base-tight	工具提示内容右侧内边距
$spacing-tooltip_content-paddingTop	$spacing-tight	工具提示内容顶部内边距
$spacing-tooltip_content-paddingBottom	$spacing-tight	工具提示内容底部内边距
$spacing-tooltip_arrow_offset-x	1px	水平方向渲染会有缝隙，所以加个偏移量
$spacing-tooltip_arrow_offset-y	1px	垂直方向渲染会有缝隙，所以加个偏移量
$spacing-tooltip_arrow_adjusted_offset-y	5px	垂直方向上的校正偏移量，主要修正三角形有棱角的问题
$spacing-tooltip_arrow_adjusted_offset-x	round($horizontal-rate * $width-tooltip_arrow)	水平方向上的校正偏移量，主要修正三角形有棱角的问题

显示第 1 条-第 8 条，共 8 条

• 1

变量	默认值	用法
$font-tooltip-fontSize	$font-size-regular	工具提示文本字号

显示第 1 条-第 1 条，共 1 条

• 1

变量	默认值	用法
$width-tooltip	240px	工具提示宽度 - 默认
$width-tooltip_arrow	24px	工具提示小三角箭头宽度 - 水平
$width-tooltip_arrow_vertical	7px	工具提示小三角箭头宽度度 - 垂直

显示第 1 条-第 3 条，共 3 条

• 1

变量	默认值	用法
$height-tooltip_arrow	7px	工具提示小三角箭头高度 - 水平
$height-tooltip_arrow_vertical	24px	工具提示小三角箭头高度 - 垂直

显示第 1 条-第 2 条，共 2 条

• 1

变量	默认值	用法
$animation_duration-tooltip_in	100ms	tooltip-弹出动画-动画持续时间
$animation_duration-tooltip_out	100ms	tooltip-收起动画-动画持续时间
$animation_function-tooltip_in	cubic-bezier(0.215, 0.61, 0.355, 1)	tooltip-弹出动画-动画插值函数
$animation_function-tooltip_out	cubic-bezier(0.215, 0.61, 0.355, 1)	tooltip-收起动画-动画插值函数

显示第 1 条-第 4 条，共 4 条

• 1

FAQ

• 为什么 Tooltip content 配置很长很长的内容时，某些情况下内容会超出显示区域?
  在 v2.36.0 版本以前，考虑到不同语言内容（纯英文、中文、中英文混合、其他语种混合）对换行的需求不太一致，所以组件层没有做这个预设。在接收到较多使用反馈后，自 v2.36.0 版本，Tooltip 内部通过设置 word-wrap 为 break-word 处理文本换行。对于任意版本，如果默认设置不符合预期，使用方都可以通过 style/className API 设置换行相关 CSS 属性进行调整。

相关物料