showSnackbar

showSnackbar() 是以程序方式显示短暂通知的入口。它会将 Snackbar 渲染到应用 OverlayHost 管理的共享堆栈中，等待其关闭后返回结果。

前置条件

调用 useOverlays() 或 createOverlayService(host) 返回的函数前，请创建控制器并渲染 <OverlayHost :host="overlays" />。仅程序化浮层需要 host；声明式 Snackbar 实例不需要。Vue 和 Nuxt 配置请参阅 OverlayHost。

基本用法

import { useOverlays } from '@chillet/m3-vue';
const { showSnackbar } = useOverlays(); // 在 setup 期间捕获。

await showSnackbar({
  message: '已保存',
});

配置默认值

安装 M3VuePlugin 时可设置应用级默认值，这些值会应用于后续的 showSnackbar() 调用。支持 refs 和 getter，单次调用时传入的选项始终优先。

import { M3VuePlugin } from '@chillet/m3-vue';

app.use(M3VuePlugin, {
  snackbarDefaults: {
    dismissible: false,
    duration: 6_000,
    position: 'bottom-end',
  },
});

组件子树默认值

在祖先组件中调用 provideSnackbarDefaults()，再在后代组件中通过 useSnackbar() 捕获最近的默认值。返回的函数可在事件处理器中稍后调用。导入的 showSnackbar(host, options) 使用其显式 host 对应的默认值。调用 useSnackbar() 前，请通过 provideOverlayHost() 或 OverlayHost 默认插槽提供 host。

<!-- NotificationArea.vue -->
<script setup lang="ts">
import { provideSnackbarDefaults } from '@chillet/m3-vue';

provideSnackbarDefaults({
  dismissible: false,
  position: 'top-end',
});
</script>

<template>
  <slot />
</template>

<!-- DescendantComponent.vue -->
<script setup lang="ts">
import { useSnackbar } from '@chillet/m3-vue';

const showSnackbar = useSnackbar();

function notify() {
  void showSnackbar({ message: '已保存' });
}
</script>

优先级顺序为：内置默认值、应用插件默认值、最近子树默认值，最后是单次调用时传入的选项。

返回值

Snackbar 关闭时 Promise 会返回结果。

• 点击操作时返回 action.value，默认值为 'action'。
• 点击关闭按钮时返回 dismissValue，默认值为 'dismiss'。
• 自动超时时返回 timeoutValue，默认值为 'timeout'。

如果在浏览器环境之外调用、目标 host 不存在或已处置，或 action.onClick 抛出错误或返回被拒绝的 Promise，则该 Promise 会被拒绝。

选项

以下表格由源代码类型生成，并与 API 变更保持同步。

ShowSnackbarOptions

字段	类型	必填	说明	默认值
message	string | undefined	否	Supporting text displayed inside the snackbar.	-
action	SnackbarAction | undefined	否	Optional action button.	-
duration	number | null | undefined	否	Milliseconds before the snackbar closes automatically. Use `null` to disable auto close.	-
timeoutValue	string | undefined	否	Value returned when the snackbar closes automatically.	-
dismissValue	string | undefined	否	Value returned when the dismiss button closes the snackbar.	-
position	SnackbarPosition | undefined	否	Where the snackbar stack is placed in the viewport.	-
actionOnNewLine	boolean | undefined	否	Whether the action should be placed on a separate line.	false
dismissible	boolean | undefined	否	Whether to show a dismiss button.	false
dismissButtonLabel	string | undefined	否	Accessible label for the dismiss button.	"Dismiss notification"

ShowSnackbarDefaults

字段	类型	必填	说明	默认值
duration	number | null | undefined	否	Milliseconds before the snackbar closes automatically. Use `null` to disable auto close.	-
timeoutValue	string | undefined	否	Value returned when the snackbar closes automatically.	-
dismissValue	string | undefined	否	Value returned when the dismiss button closes the snackbar.	-
position	SnackbarPosition | undefined	否	Where the snackbar stack is placed in the viewport.	-
actionOnNewLine	boolean | undefined	否	Whether the action should be placed on a separate line.	false
dismissible	boolean | undefined	否	Whether to show a dismiss button.	false
dismissButtonLabel	string | undefined	否	Accessible label for the dismiss button.	"Dismiss notification"

SnackbarAction

字段	类型	必填	说明	默认值
label	string	是	Label shown in the action area.	-
value	string | undefined	否	Value returned when the action closes the snackbar.	-
disabled	boolean | undefined	否	Whether the action button is disabled.	-
autofocus	boolean | undefined	否	Whether the action button should autofocus when rendered.	-
closeOnClick	boolean | undefined	否	Whether clicking the action should close the snackbar.	-
onClick	(() => void | boolean | Promise<void | boolean>) | undefined	否	Optional callback invoked before the snackbar closes. Return `false` to keep it open.	-

行为说明

• 程序化 Snackbar 默认带有关闭按钮。设置 dismissible: false 可将其隐藏。
• 可以同时显示多个 Snackbar。
• 堆栈按 host 和 position 分开，因此顶部和底部位置互不干扰。
• Snackbar 操作从 OverlayHost 继承应用级 provide 和 CSS 自定义属性。
• 悬停或聚焦 Snackbar 时会暂停自动关闭计时器。
• 离开 Snackbar 后会继续剩余时间，而不是重新开始完整计时。

手动渲染 Snackbar 时，请参阅 Snackbar。