Floating Round Toast

一个轻量级、易用的前端圆角悬浮通知库，基于 TypeScript 开发。

录屏如下。

特性

• 美观设计 - 圆角 Toast 通知，美观大方
• 多种类型 - 支持成功、警告、错误、信息等多种类型
• 动画效果 - 平滑的队列、进入和退出动画
• 高度可配置 - 支持自定义颜色、字号、样式、位置、持续时间等，甚至可以插入 html 与动画
• 轻量级 - 体积小巧，无外部依赖
• 灵活的API - 支持链式调用和全局管理

安装

# npm
npm install floating-round-toast

# yarn
yarn add floating-round-toast

# pnpm
pnpm add floating-round-toast

快速开始

基础用法

import toast from 'floating-round-toast';

// 显示成功消息
toast.success('操作成功！');

// 显示错误消息
toast.error('出错了！');

// 显示警告消息
toast.warning('请注意！');

// 显示信息消息
toast.info('提示信息');

// 显示加载消息（不会自动关闭）
const loadingId = toast.loading('正在加载...');

// 3秒后手动关闭加载消息
setTimeout(() => {
  toast.hide(loadingId);
}, 3000);

高级用法

import toast from 'floating-round-toast';

// 显示自定义toast
toast.show({
  message: '自定义消息',
  type: 'success',
  duration: 5000,
  position: 'top-right',
  onClick: () => {
    console.log('Toast被点击了');
  }
});

// 全局配置
toast.config({
  defaultDuration: 4000,
  defaultType: 'info',
  defaultPosition: 'bottom-right',
  maxToasts: 3,
  spacing: 16,
  bottomOffset: 20 // 自定义底线偏移
});

// 获取当前活跃toast信息
console.log('活跃toast数量:', toast.activeToastsCount);
console.log('活跃toast IDs:', toast.activeToastIds);

// 隐藏所有toast
toast.hideAll();

ES模块用法

import { toast, ToastManager } from 'floating-round-toast';

// 使用默认管理器
toast.success('Hello World!');

// 创建自定义管理器实例
const customManager = new ToastManager({
  defaultPosition: 'top-left',
  maxToasts: 2,
  bottomOffset: 30
});

customManager.show({
  message: '自定义管理器消息:',
  type: 'warning'
});

HTML直接引入

<!-- 通过CDN引入 -->
<script src="https://unpkg.com/floating-round-toast/dist/index.umd.js"></script>
<link rel="stylesheet" href="https://unpkg.com/floating-round-toast/dist/toast.css">

<script>
  // 使用默认导出
  FloatingRoundToast.default.success('Hello from CDN!');

  // 或者使用具名导出
  FloatingRoundToast.toast.error('出错了！');
</script>

API 参考

ToastOptions

interface ToastOptions {
  message: string;                    // 消息内容
  duration?: number;                  // 显示时长(ms)，默认3000，0表示不自动关闭
  type?: ToastType;                   // Toast类型，默认'default'
  position?: ToastPosition;           // 显示位置，默认'bottom-right'
  html?: boolean;                     // 是否支持HTML，默认false
  onClick?: () => void;               // 点击回调
  className?: string;                 // 自定义CSS类名
}

ToastType

type ToastType = 'success' | 'warning' | 'error' | 'info' | 'default';

ToastPosition

type ToastPosition = 'bottom-right'; // 目前仅支持右下角

GlobalConfig

interface GlobalConfig {
  defaultDuration?: number;           // 默认显示时长
  defaultType?: ToastType;            // 默认类型
  defaultPosition?: ToastPosition;    // 默认位置
  maxToasts?: number;                 // 最大显示数量
  spacing?: number;                   // toast间距(px)
  bottomOffset?: number;              // 基准底线偏移(px)，默认20
}

API 方法

toast.show(options)

显示指定选项的toast，返回toast ID

toast.success(message, duration?)

显示成功类型toast

toast.warning(message, duration?)

显示警告类型toast

toast.error(message, duration?)

显示错误类型toast

toast.info(message, duration?)

显示信息类型toast

toast.loading(message?)

显示加载类型toast，不会自动关闭

toast.hide(toastId)

隐藏指定ID的toast

toast.hideAll()

隐藏所有toast

toast.config(config)

设置全局配置

自定义样式

CSS变量

:root {
  --toast-border-radius: 60px;
  --toast-font-size: 14px;
  --toast-padding: 10px 80px 10px 40px;
  --toast-shadow: 2px 2px 8px rgba(0, 0, 0, 0.2);
}

自定义类名

toast.show({
  message: '自定义样式',
  className: 'my-custom-toast'
});

.my-custom-toast {
  background: linear-gradient(45deg, #667eea 0%, #764ba2 100%);
  border: 2px solid #fff;
}

全局方法

// 设置全局底线偏移
toast.setGlobalBottomOffset(30);

// 获取当前全局底线偏移
const currentOffset = toast.getGlobalBottomOffset();
console.log('当前偏移:', currentOffset);

浏览器支持

• Chrome ≥ 60
• Firefox ≥ 55
• Safari ≥ 12
• Edge ≥ 79

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 运行示例
# 在浏览器中打开 examples/example.html

许可证

MIT

贡献

欢迎提交 Issue 或 Pull Request！