提示 Toast - Svelte - Semi Design Next

代码演示

如何引入

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

静态方法只能在浏览器中调用（服务端调用会抛错），在事件处理函数里调用即可；需要在组件初始化阶段读取 context 时用 Toast.useToast()。

普通提示

通过调用 Toast的相关 method 可以实现弹出提示。推荐设置 stack 属性应用堆叠样式到同屏多个 Toast，Hover 展开，可有效防止一次性弹出多个并列 Toast 对用户造成干扰。

代码

<script lang="ts">
    import { throttle } from 'es-toolkit';
    import { Button, Toast } from '@fibrae/semi-ui-svelte';

    const opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 3,
        stack: true,
    };
    const throttleOpts = {
        content: 'Hi, Bytedance dance dance',
        duration: 10,
        onClose: () => throttled.cancel(),
        stack: true,
    };
    const throttled = throttle(() => Toast.info(throttleOpts), 10000, { edges: ['leading'] });
</script>

<div>
    <Button onclick={() => Toast.info(opts)}>Display Toast</Button>
    <br />
    <br />
    <Button onclick={throttled}>Throttled Toast</Button>
</div>

其他提示类型

包括成功、失败、警告

代码

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

    const opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 3,
    };
</script>

<Button style="color: var(--semi-color-success)" onclick={() => Toast.success('Hi,Bytedance dance dance')}>Success</Button>
<br />
<br />
<Button type="warning" onclick={() => Toast.warning(opts)}>Warning</Button>
<br />
<br />
<Button type="danger" onclick={() => Toast.error(opts)}>Error</Button>

多色样式

可以使用 theme 设置浅色填充样式提高与界面的对比，默认为 'normal' 的白色模式。

代码

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

    const opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 3,
        theme: 'light',
    } as const;
</script>

<Button onclick={() => Toast.info(opts)}>Info</Button>
<br />
<br />
<Button style="color: var(--semi-color-success)" onclick={() => Toast.success(opts)}>Success</Button>
<br />
<br />
<Button type="warning" onclick={() => Toast.warning(opts)}>Warning</Button>
<br />
<br />
<Button type="danger" onclick={() => Toast.error(opts)}>Error</Button>

堆叠样式

设置 stack 后，同屏 Toast 超过阈值时堆叠展示，Hover 展开。true 的阈值为 3，传数字可自定义阈值；堆叠时只显示最前面的 3 层。

代码

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

    const opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 10,
        stack: true,
    };
</script>

<Button onclick={() => Toast.info(opts)}>多次点击</Button>

链接文本

配合 Typography 可以自定义链接文本，用来配合更复杂的场景的使用。

content、icon 接受字符串或 snippet：用 {#snippet} 在组件里定义后传入，snippet 里可以直接使用 Typography 等组件。

代码

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

{#snippet single()}
    <span>
        <TypographyText>Hi, Bytedance dance dance</TypographyText>
        <TypographyText link style="margin-left: 12px">更多</TypographyText>
    </span>
{/snippet}
{#snippet multiLine()}
    <div>Hi, Bytedance dance dance</div>
    <div style="margin-top: 8px">
        <TypographyText link>查看详情</TypographyText>
        <TypographyText link style="margin-left: 20px">一会再看</TypographyText>
    </div>
{/snippet}

<Button onclick={() => Toast.info({ content: single, duration: 3 })}>Display Toast</Button>
<br />
<br />
<Button onclick={() => Toast.info({ content: multiLine, duration: 3 })}>Display Multi-line Toast</Button>

修改延时

自定义时长 10s，默认时长为 3s

代码

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

    const opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 10,
    };
</script>

<Button onclick={() => Toast.info(opts)}>Close After 10s</Button>

手动关闭

当 duration 设置为 0 时，toast 不会自动关闭，此时必须通过手动关闭。

代码

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

    let toastId: string | null = null;

    const destroy = () => {
        toastId = null;
    };

    const opts = {
        content: 'Not auto close',
        duration: 0,
        onClose: destroy,
    };

    const show = () => {
        if (toastId) {
            return;
        }
        toastId = Toast.info(opts);
    };

    const hide = () => {
        if (toastId) {
            Toast.close(toastId);
        }
        destroy();
    };
</script>

<Button type="primary" onclick={show}>Show Toast</Button>
<br />
<br />
<Button type="primary" onclick={hide}>Hide Toast</Button>

更新消息内容

可以通过唯一的 id 来更新内容。

代码

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

    const show = () => {
        const id = 'toastid';
        Toast.info({ content: 'Update Content By Id', id });
        setTimeout(() => {
            Toast.success({ content: 'Id By Content Update', id });
        }, 1000);
    };
</script>

<Button type="primary" onclick={show}>Update Content By Id</Button>

销毁所有

全局销毁：

Toast.destroyAll()

消费 Context

在组件初始化时调用 Toast.useToast()，得到的 toast 会读取调用它的组件所在位置的 context、ConfigProvider 和语言，不需要放置 Holder。toast 挂载在 document.body 下，调用组件销毁时一并移除。

Toast.useToast() 返回 toast 对象：info、success、warning、error、open 接收不含 type、id、top、bottom、left、right、zIndex、getPopupContainer 的 Options，返回 toastId；close(toastId) 手动关闭。content、icon 传 snippet 时，snippet 里可以 getContext 读到调用组件的 context。ConfigProvider、LocaleProvider 的值静态 Toast 读不到，需要时改用 useToast()。

代码

<script lang="ts">
    import { getContext, setContext } from 'svelte';
    import { Button, Toast } from '@fibrae/semi-ui-svelte';

    const reachableKey = Symbol('reachable');
    setContext(reachableKey, 'Light');

    const toast = Toast.useToast();
</script>

<!-- The snippet renders inside the toast list mounted with this component's contexts, so it reads the context set above -->
{#snippet reachable()}ReachableContext: {getContext(reachableKey)}{/snippet}

<div>
    <Button onclick={() => toast.success({ duration: 0, content: reachable })}>Hook Toast</Button>
</div>

创建不同配置 Toast

ToastFactory.create(config) => Toast
如果您的应用中需要使用不同 config 的 Toast，可以使用 ToastFactory.create(config)创建新的 Toast:

custom container

代码

<script lang="ts">
    import { onDestroy } from 'svelte';
    import { Button, Toast, ToastFactory } from '@fibrae/semi-ui-svelte';

    const ToastInCustomContainer = ToastFactory.create({
        getPopupContainer: () => document.getElementById('custom-toast-container') as HTMLElement,
    });
    onDestroy(() => ToastInCustomContainer.destroyAll());
</script>

<div>
    <Button onclick={() => Toast.info('Toast')}>Default Toast</Button>
    <br />
    <br />
    <Button onclick={() => ToastInCustomContainer.info('Toast in some container')}>Toast in custom container</Button>
    <div id="custom-toast-container">custom container</div>
</div>

API 参考

组件提供的静态方法，使用方式和参数如下：展示：可以直接传入 options 对象或 string：

全局配置, 在调用前提前配置，全局一次生效

Toast.config(config)
Toast.resetConfig() 将全局配置恢复为默认值，只影响之后弹出的 Toast。ToastFactory.create(config) 创建的实例恢复为创建时传入的 config

直接展示 Toast

Toast.info(options || string)
Toast.error(options || string)
Toast.warning(options || string)
Toast.success(options || string)

info error warning success 返回值为toastId, 可用于手动关闭

const toastId = Toast.info({ /*...options*/ })

Toast.close(toastId) 手动关闭

Options

Toast Options 支持以下 API 及 Config 中的 API

属性	说明	类型	默认值
content	提示内容，字符串或 snippet；snippet 在 Toast 渲染处执行	string \| Snippet	''
icon	自定义图标，字符串或 snippet，替换 `type` 对应的图标	string \| Snippet
showClose	是否展示关闭按钮	boolean	true
textMaxWidth	内容的最大宽度	number \| string	450
onClose	toast 关闭的回调函数	() => void
stack	同屏 Toast 超过多少条时堆叠展示，`true` 为 3，`false` 不堆叠	boolean \| number	false
id	自定义 ToastId，相同 id 的 Toast 会被更新	string
motion	是否开启进出场动画	boolean	true
class	类名	string \| object \| array
style	样式，只接受字符串	string

class、style 与未声明的选项（如 data-*、aria-*）落在 .semi-toast 上，堆叠模式下同样如此。

Config

以下 API 支持全局配置，用于更改当前 Toast 的默认配置

属性	说明	类型	默认值
bottom	弹出位置 bottom	number \| string	-
left	弹出位置 left	number \| string	-
right	弹出位置 right	number \| string	-
top	弹出位置 top	number \| string	-
zIndex	弹层 z-index 值	number	1010
theme	填充样式，支持 `light`, `normal`	string	`normal`
duration	自动关闭的延时，单位 s，设为 0 时不自动关闭	number	3
getPopupContainer	指定父级 DOM，弹层将会渲染至该 DOM 中，自定义需要设置 container 和内部的 .semi-toast-wrapper `position: relative`, 这会改变浮层 DOM 树位置，但不会改变视图渲染位置。	() => HTMLElement	() => document.body

Accessibility

ARIA

Toast 的 role 按类型区分：warning、error 为 alert，info、success 与没有 type 的为 status
status 类 Toast 由列表常驻的 aria-live="polite" 播报区朗读，Toast 自身为 aria-live="off"，只播报 content 的文本；warning、error 仍由 alert 自行播报

键盘和焦点

关闭按钮是原生 button，可以用 Tab 聚焦，Enter 或 Space 触发关闭
Toast 出现时不会抢走焦点
指针或键盘焦点进入 Toast 时暂停自动关闭的计时，并展开堆叠；移出后恢复计时

文案规范

Ticket transferred

保持简洁
句尾不使用句号
使用名词 + 动词的格式进行说明

✅ 推荐用法	❌ 不推荐用法
Language added	New language has been added successfully
Ticket transfer failed	Can't transfer ticket

提供动作的提示消息
- 只提供一个动作
- 不使用类似于「已读」类的动作，例如 OK, Got it, Dismiss, Cancel

✅ 推荐用法	❌ 不推荐用法
Ticket transfer failed Retry	Ticket transfer failed Dismiss

设计变量

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

Sass 变量	值	用法
$animation_duration-toast-show	300ms
$animation_duration-toast-hide	300ms
$animation_function-toast-show	cubic-bezier(0.22, 0.57, 0.02, 1.2)
$animation_function-toast-hide	cubic-bezier(0.22, 0.57, 0.02, 1.2)
$animation_delay-toast-show	0s
$animation_delay-toast-hide	0s
$animation_opacity-toast-show	0
$animation_opacity-toast-hide	0
$animation_transform_translateY-toast-show	-100%
$animation_transform_translateY-toast-hide	-100%
$animation_duration-toast-stack	300ms
$animation_function-toast-stack	cubic-bezier(0.22, 0.57, 0.02, 1.2)
$color-toast-bg-default	var(--semi-color-bg-3)	提示背景颜色 - 默认
$color-toast-text-default	var(--semi-color-text-0)	提示文字颜色 - 默认
$color-toast_warning-icon	var(--semi-color-warning)	警告提示图标颜色
$color-toast_success-icon	var(--semi-color-success)	成功提示图标颜色
$color-toast_info-icon	var(--semi-color-info)	通知提示图标颜色
$color-toast_danger-icon	var(--semi-color-danger)	错误提示图标颜色
$color-toast_warning_light-bg	var(--semi-color-warning-light-default)	多色样式警告提示背景颜色
$color-toast_warning_light-icon	$color-toast_warning-icon	多色样式警告提示图标颜色
$color-toast_warning_light-border	var(--semi-color-warning)	多色样式警告提示描边颜色
$color-toast_success_light-bg	var(--semi-color-success-light-default)	多色样式成功提示背景颜色
$color-toast_success_light-icon	$color-toast_success-icon	多色样式成功提示图标颜色
$color-toast_success_light-border	var(--semi-color-success)	多色样式成功提示描边颜色
$color-toast_info_light-bg	var(--semi-color-info-light-default)	多色样式通知提示背景颜色
$color-toast_info_light-icon	$color-toast_info-icon	多色样式通知提示图标颜色
$color-toast_info_light-border	var(--semi-color-info)	多色样式通知提示描边颜色
$color-toast_danger_light-bg	var(--semi-color-danger-light-default)	多色样式错误提示背景颜色
$color-toast_danger_light-icon	$color-toast_danger-icon	多色样式错误提示图标颜色
$color-toast_danger_light-border	var(--semi-color-danger)	多色样式错误提示描边颜色
$spacing-toast_wrapper-top	0	通知容器顶部位置
$spacing-toast_content-paddingY	$spacing-base-tight	通知内容垂直内边距
$spacing-toast_content-paddingX	$spacing-tight	通知内容水平内边距
$spacing-toast_content-paddingTop	$spacing-toast_content-paddingY	通知内容 top 内边距
$spacing-toast_content-paddingBottom	$spacing-toast_content-paddingY	通知内容 bottom 内边距
$spacing-toast_content-paddingLeft	$spacing-toast_content-paddingX	通知内容 left 内边距
$spacing-toast_content-paddingRight	$spacing-toast_content-paddingX	通知内容 right 内边距
$spacing-toast_content-margin	$spacing-base-tight	通知内容外边距
$spacing-toast_content_close_btn-marginTop	-2px	通知关闭按钮顶部外边距
$spacing-toast_content_text-marginLeft	$spacing-base-tight	通知文本左侧外边距
$spacing-toast_content_text-marginRight	$spacing-base-tight	通知文本右侧外边距
$spacing-toast-perspective-originY	280px	通知透视原点 Y 轴位置
$spacing-toast-perspective	280px	通知透视距离
$width-toast_wrapper	100%	通知容器整体宽度
$width-toast_light-border	1px	多色样式通知描边宽度
$radius-toast_content	var(--semi-border-radius-medium)	通知圆角
$font-toast_content-fontWeight	$font-weight-bold	通知文本字重