Vue Sonner – 专为Vue3设计的现代化Toast通知库，优雅API+丰富动画

简介

Vue Sonner 是一个专为 Vue 3 设计的现代化 Toast 通知库，提供了优雅的 API 和丰富的自定义选项。它支持多种通知类型、动画效果、位置配置等，是构建用户友好界面的理想选择。

特性

• 🚀 专为 Vue 3 设计，支持 Composition API
• 🎨 现代化设计，支持暗色主题
• 📱 响应式布局，移动端友好
• ⚡ 轻量级，零依赖
• 🎭 丰富的动画效果
• 🔧 高度可定制

安装

# 使用 npm
npm install vue-sonner

# 使用 yarn
yarn add vue-sonner

# 使用 pnpm
pnpm add vue-sonner

基本配置

全局注册

在 main.ts 中注册插件：

import { createApp } from "vue";
import { VueSonner } from "vue-sonner";
import App from "./App.vue";

import "vue-sonner/style.css"; // 引入样式文件
import { Toaster } from "vue-sonner";

const app = createApp(App);
app.component("Toaster", Toaster); // 全局注册 Toaster 组件
app.mount("#app");

组件中使用

<template>
  <div>
    <Toaster />
    <button @click="showToast">显示通知</button>
    <button @click="showSuccess">成功通知</button>
    <button @click="showError">错误通知</button>
  </div>
</template>

<script setup>
import { toast, Toaster } from "vue-sonner";

const showToast = () => {
  toast("这是一条普通通知");
};

const showSuccess = () => {
  toast.success("操作成功！");
};

const showError = () => {
  toast.error("操作失败！");
};
</script>

核心 API

toast() 函数

// 基本用法
toast("消息内容");

// 带选项
toast("消息内容", {
  duration: 5000,
  position: "top-center",
  action: {
    label: "撤销",
    onClick: () => console.log("撤销操作"),
  },
});

通知类型

// 成功通知
toast.success("操作成功！");

// 错误通知
toast.error("操作失败！");

// 警告通知
toast.warning("请注意！");

// 信息通知
toast.info("提示信息");

// 加载通知
toast.loading("正在处理...");

通知选项

选项名	类型	说明
id	string | number	通知唯一标识，可用于更新/关闭
title	string	通知标题
description	string	通知描述内容
duration	number	显示时长（毫秒），默认 4000
position	ToastPosition	通知显示位置
action	ToastAction	操作按钮配置
cancel	ToastAction	取消按钮配置
dismissible	boolean	是否可手动关闭
important	boolean	是否为重要通知
unstyled	boolean	是否禁用默认样式
class	string	自定义类名
style	CSSProperties	自定义内联样式
icon	Component	自定义图标
closeButton	boolean	是否显示关闭按钮
onDismiss	() => void	通知被关闭时的回调
onAutoClose	() => void	通知自动关闭时的回调

位置配置

位置值	说明
top-left	左上角
top-center	顶部居中
top-right	右上角
bottom-left	左下角
bottom-center	底部居中
bottom-right	右下角
center-left	居中偏左
center	居中
center-right	居中偏右

高级用法

自定义通知

<template>
  <button @click="showCustomToast">自定义通知</button>
</template>

<script setup>
import { toast } from "vue-sonner";

const showCustomToast = () => {
  toast("自定义通知", {
    class: "custom-toast",
    style: {
      background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
      color: "white",
      borderRadius: "12px",
    },
  });
};
</script>

<style>
.custom-toast {
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.2);
}
</style>

自定义倒计时通知

<template>
  <button @click="openCountdownToast">显示倒计时提示</button>
</template>

<script lang="ts" setup>
import { toast } from "vue-sonner";

const openCountdownToast = () => {
  let countdown = 60;

  // 创建loading toast并获取其ID
  const toastId = toast.loading(`倒计时: ${countdown}秒`, {
    duration: Infinity, // 设置为无限时长，手动控制关闭
  });

  // 创建定时器，每秒更新一次
  const timer = setInterval(() => {
    countdown--;

    if (countdown > 0) {
      // 更新toast内容
      toast.loading(`倒计时: ${countdown}秒`, {
        id: toastId,
        duration: Infinity,
      });
    } else {
      // 倒计时结束，显示成功消息并关闭
      toast.success("倒计时完成！", {
        id: toastId,
        duration: 2000,
      });
      clearInterval(timer);
    }
  }, 1000);
};
</script>

持久化通知

// 不自动关闭
toast("重要通知", {
  duration: Infinity,
  dismissible: false,
});

// 标记为重要
toast("重要通知", {
  important: true,
});

通知队列管理

// 获取所有通知
const toasts = toast.getToasts();

// 关闭特定通知
toast.dismiss("toast-id");

// 关闭所有通知
toast.dismiss();

// 更新通知
toast.update("toast-id", {
  title: "更新后的标题",
  description: "更新后的描述",
});

主题配置

全局主题

// main.ts
app.use(VueSonner, {
  theme: "dark", // 'light' | 'dark' | 'system'
  position: "top-right",
  duration: 4000,
  closeButton: true,
  richColors: true,
});

CSS 变量自定义

:root {
  --toast-bg: #ffffff;
  --toast-color: #333333;
  --toast-border: #e5e7eb;
  --toast-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}

[data-sonner-toaster][data-theme="dark"] {
  --toast-bg: #1f2937;
  --toast-color: #f9fafb;
  --toast-border: #374151;
}

常见问题

Q: 如何禁用默认样式？

A: 设置 unstyled: true 选项，然后使用自定义 CSS。

Q: 如何实现通知的国际化？

A: 使用 i18n 库配合 toast 函数，动态传入翻译后的文本。

Q: 如何自定义动画效果？

A: 通过 CSS 类名和 class 选项，结合 CSS 动画实现自定义效果。

总结

Vue Sonner 是一个功能强大、易于使用的 Vue 3 Toast 通知库。它提供了丰富的 API 和灵活的配置选项，能够满足各种通知需求。通过合理使用，可以为用户提供更好的交互体验。