气泡卡片 Popover - Svelte

使用场景

Popover 气泡卡片是由用户自主打开的临时性浮层卡片，能够承载一些额外内容和交互行为而不影响原页面。

和 Tooltip 的区别是，它可以承载更复杂的内容，而不仅仅是提示文本。

代码演示

如何引入

<script lang="ts">
    import { Popover } from '@fibrae/semi-ui-svelte';
</script>

注意事项

Popover 需要将触发属性和事件监听器应用到触发元素上，并以触发元素的真实 DOM 元素计算弹出层的定位，因此触发元素支持如下写法：

child snippet：参数 { props } 必须整体展开到接收焦点的元素上，该元素可以是真实 DOM 元素（如 span、div、p...），也可以是会把属性透传到根 DOM 元素的组件（如 <Button {...props} />）
children snippet（直接写在标签内的内容）：文本、组件、多个节点，Popover 会用一个 span 包裹它们作为触发元素

Component

Text DOM

代码

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Space, Tag } from '@fibrae/semi-ui-svelte';

    const style = 'border: 2px solid var(--semi-color-border); padding-left: 4px; padding-right: 4px; border-radius: 4px';
    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet card()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<Space>
    <Popover content={card}>
        <Tag {style}>Component</Tag>
    </Popover>
    <Popover content={card}>Text</Popover>
    <Popover content={card}>
        {#snippet child({ props })}
            <span {...props} {style}>DOM</span>
        {/snippet}
    </Popover>
</Space>

基本使用

将浮层的触发器 Trigger 写在标签内（如下的例子中触发器为 Tag 元素），使用 Popover 包裹。浮层内容通过 content snippet 传入
注意事项同 Tooltip

悬停此处

代码

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Tag } from '@fibrae/semi-ui-svelte';

    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet card()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<Popover content={card}>
    <Tag>悬停此处</Tag>
</Popover>

弹出位置

支持通过position设置浮层弹出方向，共支持十二个方向。

Top

Left

Right

Bottom

代码

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';

    const tops: [Position, string][] = [
        ['topLeft', 'TL'],
        ['top', 'Top'],
        ['topRight', 'TR'],
    ];
    const lefts: [Position, string][] = [
        ['leftTop', 'LT'],
        ['left', 'Left'],
        ['leftBottom', 'LB'],
    ];
    const rights: [Position, string][] = [
        ['rightTop', 'RT'],
        ['right', 'Right'],
        ['rightBottom', 'RB'],
    ];
    const bottoms: [Position, string][] = [
        ['bottomLeft', 'BL'],
        ['bottom', 'Bottom'],
        ['bottomRight', 'BR'],
    ];
    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet content()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<div>
    <div style="margin-left: 80px; white-space: nowrap">
        {#each tops as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px">{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 80px; float: left">
        {#each lefts as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; margin-left: 300px">
        {#each rights as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="margin-left: 80px; clear: both; white-space: nowrap">
        {#each bottoms as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
            </Popover>
        {/each}
    </div>
</div>

受控显示

设置 trigger="custom"，此场景下，Popover 的显示与否完全受到参数 visible 的控制，可以配合 bind:visible 使用。

受控显示

受控隐藏

代码

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Radio, RadioGroup, type RadioValue } from '@fibrae/semi-ui-svelte';

    let value = $state<RadioValue | undefined>(0);
    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet content()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<Popover {content} trigger="custom" visible={value === 1}>
    <span style="display: inline-block">
        <RadioGroup bind:value type="button">
            <Radio value={1}>受控显示</Radio>
            <Radio value={0}>受控隐藏</Radio>
        </RadioGroup>
    </span>
</Popover>

condition 条件触发

当 condition={false} 时，Popover 不响应 hover/click/focus 等触发行为（trigger="custom" 时仍按 visible 显示）；condition 由 true 变为 false 时，已显示的弹出层立即关闭；visible 受控时只调用 onVisibleChange(false)，使用方回写 visible 后才关闭。

代码

<script lang="ts">
    import { Button, Popover, Space, Switch, TypographyText } from '@fibrae/semi-ui-svelte';

    let enabled = $state(true);
    const text = $derived(`condition is ${enabled ? 'true' : 'false'}`);
</script>

{#snippet content()}{text}{/snippet}

<Space align="center">
    <TypographyText id="popover-condition-label">condition</TypographyText>
    <Switch aria-labelledby="popover-condition-label" bind:checked={enabled} />
    <Popover condition={enabled} {content}>
        {#snippet child({ props })}
            <Button {...props}>Hover me</Button>
        {/snippet}
    </Popover>
    <Popover condition={enabled} {content} trigger="click">
        {#snippet child({ props })}
            <Button {...props}>Click me</Button>
        {/snippet}
    </Popover>
</Space>

显示小三角

通过设置showArrow, Popover 同样也支持展示一个小三角。

这种模式下浮层会拥有一个默认的样式，你可以通过传递 style 参数来覆盖掉。

Top

Left

Right

Bottom

代码

<script lang="ts">
    import { Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';

    const tops: [Position, string][] = [
        ['topLeft', 'TL'],
        ['top', 'Top'],
        ['topRight', 'TR'],
    ];
    const lefts: [Position, string][] = [
        ['leftTop', 'LT'],
        ['left', 'Left'],
        ['leftBottom', 'LB'],
    ];
    const rights: [Position, string][] = [
        ['rightTop', 'RT'],
        ['right', 'Right'],
        ['rightBottom', 'RB'],
    ];
    const bottoms: [Position, string][] = [
        ['bottomLeft', 'BL'],
        ['bottom', 'Bottom'],
        ['bottomRight', 'BR'],
    ];
</script>

{#snippet content()}
    <article>
        Hi ByteDancer, this is a popover.
        <br />
        We have 2 lines.
    </article>
{/snippet}

<div class="tag-margin-right" style="padding-left: 40px">
    <div style="margin-left: 40px; white-space: nowrap">
        {#each tops as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; float: left">
        {#each lefts as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; margin-left: 180px">
        {#each rights as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="margin-left: 40px; clear: both; white-space: nowrap">
        {#each bottoms as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
</div>

指向元素中心

在显示小三角的条件（showArrow=true）下，可以传入 arrowPointAtCenter=true 使得小三角始终指向元素中心位置。

Top

Left

Right

Bottom

代码

<script lang="ts">
    import { Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';

    const tops: [Position, string][] = [
        ['topLeft', 'TL'],
        ['top', 'Top'],
        ['topRight', 'TR'],
    ];
    const lefts: [Position, string][] = [
        ['leftTop', 'LT'],
        ['left', 'Left'],
        ['leftBottom', 'LB'],
    ];
    const rights: [Position, string][] = [
        ['rightTop', 'RT'],
        ['right', 'Right'],
        ['rightBottom', 'RB'],
    ];
    const bottoms: [Position, string][] = [
        ['bottomLeft', 'BL'],
        ['bottom', 'Bottom'],
        ['bottomRight', 'BR'],
    ];
</script>

{#snippet content()}
    <article>
        Hi ByteDancer, this is a popover.
        <br />
        We have 2 lines.
    </article>
{/snippet}

<div class="tag-margin-right" style="padding-left: 40px">
    <div style="margin-left: 40px; white-space: nowrap">
        {#each tops as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; float: left">
        {#each lefts as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; margin-left: 180px">
        {#each rights as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="margin-left: 40px; clear: both; white-space: nowrap">
        {#each bottoms as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
</div>

设置浮层背景色

如果你需要定制浮层的背景色或边框颜色，请务必单独声明 style 中的 backgroundColor 和 borderColor 属性，这样能够使得“小三角”也能应用相同的背景色和边框颜色。

Colorful Popover

代码

<script lang="ts">
    import { Popover, Tag } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Popover aria-label="Colorful Popover" position="right" showArrow style="background-color: var(--semi-blue-6); border-color: var(--semi-blue-6); color: var(--semi-color-white); border-width: 1px; border-style: solid" trigger="custom" visible>
        <Tag style="background-color: var(--semi-blue-6); color: var(--semi-color-white)">Colorful Popover</Tag>
        {#snippet content()}
            <article style="padding: 4px">Hi, Semi UI Popover.</article>
        {/snippet}
    </Popover>
</div>

初始化弹出层焦点位置

content snippet 的参数为 { initialFocusRef }，用 {@attach initialFocusRef} 把它绑定在可聚焦的元素上，打开面板时会自动聚焦在该位置。写在组件上时，{@attach} 落在组件内接收 aria-*、tabindex 的原生控件上（如示例中 Input 的原生 <input>）。

代码

<script lang="ts">
    import { Button, Input, Popover, Space } from '@fibrae/semi-ui-svelte';
</script>

<Popover trigger="click">
    <Button>click me</Button>
    {#snippet content({ initialFocusRef })}
        <div style="padding: 12px">
            <Space>
                <Button>first focusable element</Button>
                <Input {@attach initialFocusRef} placeholder="focus here" />
            </Space>
        </div>
    {/snippet}
</Popover>

请参考搭配使用

API 参考

Props

属性	说明	类型	默认值
afterClose	弹出层关闭且离场动画结束后调用。	`TooltipProps['afterClose']`	-
afterOpen	弹出层打开且进场动画结束后调用；没有进场动画时打开后即调用，受控与非受控相同；进场结束前被关闭的打开不调用。	`TooltipProps['afterOpen']`	-
aria-describedby	弹出层 role 为 dialog 时的 aria-describedby。	`string`	-
aria-label	弹出层 role 为 dialog 时的 aria-label。	`string`	-
aria-labelledby	弹出层 role 为 dialog 时的 aria-labelledby。	`string`	-
arrowPointAtCenter	箭头是否指向触发元素中心，需要同时开启 showArrow。	`boolean`	-
arrowStyle	箭头的 borderColor、backgroundColor 与 borderOpacity；缺省跟随卡片 style 中的 backgroundColor 与 borderColor。	`ArrowStyle`	-
autoAdjustOverflow	弹出层被遮挡时是否自动调整方向。	`boolean`	`true`
child	直接渲染触发元素的 snippet，参数 `{ props }` 必须整体展开到触发元素上；传了 `child` 时 `children` 不再生效。	`TooltipProps['child']`	-
children	触发元素的 snippet，会被包进 Tooltip 自己的 span，由该 span 接收触发属性。	`TooltipProps['children']`	-
class	弹出层的类名。	`string`	-
clickToHide	点击弹出层及其内部任一元素时是否关闭弹出层。	`boolean`	-
closeOnEsc	弹出层打开期间按 Esc 是否关闭弹出层；trigger 为 custom 时只调用 onEscKeyDown，由使用方决定是否关闭。	`boolean`	`true`
condition	是否允许触发显示；仅显式设为 false 时，hover、click、focus 等触发行为不生效，trigger 为 custom 时仍按 visible 显示。由 true 变为 false 时立即关闭已显示的弹出层；visible 受控时只调用 onVisibleChange(false)，使用方回写后才关闭。	`boolean`	-
content	卡片内容的 snippet，参数 `{ initialFocusRef }` 是回调，可直接写 `{@attach initialFocusRef}` 绑定到弹出层打开时需要聚焦的元素。	`TooltipProps['content']`	-
contentClassName	弹出层内容卡片的类名。	`ClassValue`	-
disableArrowKeyDown	是否禁用在触发元素上按方向键把焦点移入弹出层。	`boolean`	-
disableFocusListener	trigger 为 hover 时，是否不响应键盘聚焦打开弹出层。	`boolean`	-
guardFocus	焦点位于弹出层内时，Tab 是否在弹出层内循环。	`boolean`	`true`
keepDOM	关闭时是否保留弹出层内容而不销毁。	`boolean`	-
motion	是否展示弹出层动画。	`boolean`	`true`
mouseEnterDelay	指针移入后延迟显示的毫秒数，仅 trigger 为 hover 或 focus 时生效。	`number`	-
mouseLeaveDelay	指针移出后延迟隐藏的毫秒数，仅 trigger 为 hover 或 focus 时生效，不小于 mouseEnterDelay。	`number`	-
onClickOutSide	弹出层打开时在触发元素与弹出层以外的区域按下鼠标时调用，仅 trigger 为 click、contextMenu、custom 时有效。	`TooltipProps['onClickOutSide']`	-
onEscKeyDown	closeOnEsc 为 true 时，弹出层打开期间按 Esc 调用。	`TooltipProps['onEscKeyDown']`	-
onOpen	弹出层显示、进场动画开始时调用，每次打开一次，早于 afterOpen，受控与非受控相同；悬停打开后指针已离开而撤回的打开不调用。	`TooltipProps['onOpen']`	-
onVisibleChange	弹出层显示状态变化时调用；visible 受控时只报告用户交互发起的请求，使用方自己改变 visible 不调用。	`TooltipProps['onVisibleChange']`	-
position	弹出层相对触发元素的位置，共十二个方向。	`TooltipProps['position']`	`"bottom"`
prefixCls	弹出层类名前缀，设置后弹出层不再带 Popover 的样式。	`string`	`"semi-popover"`
returnFocusOnClose	按 Esc 关闭弹出层后焦点是否回到触发元素。	`boolean`	`true`
role	弹出层的 role。不传时 trigger 为 click、contextMenu、custom 是 dialog，其余是 tooltip；弹出层只是另一个控件的附属（如 combobox 的下拉）时传 presentation。	`string`	-
showArrow	是否显示箭头三角形。	`boolean`	`false`
spacing	弹出层与触发元素的距离，单位为像素；对象形式分别设置水平与垂直方向。不传时无箭头为 4，有箭头为 10。	`number \| { x: number; y: number }`	-
stopPropagation	是否阻止弹出层上的 click、mousedown 与焦点进出事件冒泡。	`boolean \| string`	-
style	弹出层的样式字符串；其中的 background-color 与 border-color 也给箭头着色。	`string`	-
trigger	触发显示的时机。custom 时显示与否完全由 visible 决定。	`TooltipProps['trigger']`	`"hover"`
visible	弹出层是否显示，配合 trigger 为 custom 使用，可用 `bind:visible` 双向绑定；传入后由该值决定显示。	`boolean`	-

Methods

方法	说明	类型
focusTrigger	让触发元素获得焦点，仅在 returnFocusOnClose 为 true 且 trigger 不是 custom 时生效。	`Type`
rePosition	按触发器当前位置立即重新计算弹出层位置。弹出层已随滚动、窗口尺寸变化、触发器移动以及触发器或弹出层的尺寸变化自动重新定位，一般无需调用；跟随触发器移动会晚一帧，需要同一帧内对齐时调用。	`Type`

class、style 落在弹出层上，其他未声明的属性会被丢弃（Popover 没有根 DOM 元素）；触发属性只加在触发元素上。bind:this 收到的是实例方法，不是 DOM 元素。

Accessibility

ARIA

关于 role
- 当 Popover 的 trigger 为 click、contextMenu、custom 时，Popover 的 content 具有 dialog role
- 当 trigger 为 hover、focus 时，Popover 的 content 具有 tooltip role
- role 属性可覆盖默认值。dialog 需要名称：传入 aria-label，或用 aria-labelledby 指向 content 中的标题；未命名的 dialog 在开发环境会输出警告
Popover 的 content
- content 的 wrapper 会被自动添加 id 属性
Popover 的 children（tooltip 只会被添加 aria-describedby；presentation 等其他 role 不添加任何属性）
- 会被自动添加 aria-expanded 属性，当 Popover 可见时，属性值为 true，不可见时为 false
- 会被自动添加 aria-haspopup 属性，为 dialog
- 会被自动添加 aria-controls 属性，为 content 的 wrapper 的 id

键盘和焦点

Popover 触发方式设置为 hover 时：鼠标悬浮或聚焦时打开 Popover
Popover 触发方式设置为 click 时：点击触发器或聚焦时并使用 Enter 键打开 Popover
Popover 激活后，按下方向键 ⬇️ 将焦点移动到 Popover 上，此时焦点默认处于 Popover 中第一个可交互元素上，用户也可自定义焦点位置（若 Popover 内无可交互元素则表现为无响应）
焦点处于 Popover 内时使用 Tab 键，焦点会在 Popover 内循环，使用 Shift + Tab 会反方向移动焦点
键盘用户能够通过按 Esc 关闭 Popover，关闭后焦点返回到触发器上（仅当 trigger 为 click 时）

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$animation_duration-popover-out	100ms	popover-显示及收起动画-动画持续时间
$animation_function-popover-out	cubic-bezier(0.215, 0.61, 0.355, 1)	popover-显示及收起动画-动画插值函数
$horizontal-rate-popover	0.24	水平方向矫正因子
$color-popover_arrow-icon-default	unset	箭头图标
$color-popover-bg-default	var(--semi-color-bg-3)	默认背景色
$color-popover-border-default	var(--semi-color-border)	默认描边颜色
$color-popover-arrow-border	var(--semi-color-border)	箭头描边颜色
$color-popover-arrow-bg	var(--semi-color-bg-3)	箭头默认背景色
$width-popover_arrow	24px	水平箭头宽度
$height-popover_arrow	8px	水平箭头高度
$height-popover_arrow_vertical	24px	垂直箭头高度
$width-popover_arrow_vertical	8px	垂直箭头宽度
$width-popover_title-border	1px
$spacing-popover_title-padding	8px	气泡卡片标题内边距
$spacing-popover_withArrow-padding	12px	带箭头的气泡卡片标题内边距
$spacing-popover_arrow_adjusted_offset-y	6px	垂直方向上的校正偏移量，主要修正三角形有棱角的问题
$spacing-popover_arrow_adjusted_offset-x	math.round($horizontal-rate-popover * $width-popover_arrow)	水平方向上的校正偏移量，主要修正三角形有棱角的问题
$radius-popover	var(--semi-border-radius-medium)	气泡卡片的圆角大小
$filter-popover-bg	none

FAQ

为什么 Popover 浮层卡片的位置和浮层的触发器的相对位置不符合预期?
Popover 底层依赖了 Tooltip，Tooltip 为了计算定位，需要获取到 children 的真实 DOM 元素，因此 Popover 类型目前支持如下类型的 children：
1. child snippet：把 props 展开到真实 DOM 元素，或展开到会把属性透传到根 DOM 元素的组件上
2. children snippet（文本、组件、多个节点），由 Popover 用一个 span 包裹
若触发元素的真实 DOM 节点宽高并非是你的触发内容的全部，则位置可能有出入。例如设置了 prefix、suffix 的 Input，Popover位置仍是相对于不包含前缀部分的 input 框进行定位，此时只要在 Input 外层再套一个 div 就能解决问题。
为什么 Popover 浮层卡片在靠近屏幕边界宽度不够时，丢失宽度意外换行?
在 chromium 104 后对于屏幕边界文本宽度不够时的换行渲染策略发生变化，详细原因可查看 issue #1022，semi侧已经在v2.17.0版本修复了这个问题。

使用场景

代码演示

如何引入

注意事项

基本使用

弹出位置

受控显示

condition 条件触发

显示小三角

指向元素中心

设置浮层背景色

初始化弹出层焦点位置

搭配 Tooltip 或 Popconfirm 使用

API 参考

Accessibility

ARIA

键盘和焦点

设计变量

FAQ