diff --git a/site/docs.html b/site/docs.html
index dd877b9..ae39646 100644
--- a/site/docs.html
+++ b/site/docs.html
@@ -79,6 +79,7 @@
API 文档
-MetonaToast v0.3.0 完整 API 参考。所有基础通知方法（show/success/error/warning/info/loading）支持两种调用形式，均可传入任何 配置项 作为可选第二参数。
+MetonaToast v0.4.0 完整 API 参考。所有基础通知方法（show/success/error/warning/info/loading）支持两种调用形式，均可传入任何 配置项 作为可选第二参数。
show(message, opts?)
@@ -422,13 +423,38 @@ MeToast.removeToast(t.id); // 或按
MeToast.use('keyboard'); // ESC 关闭所有 Toast
MeToast.use('persistence'); // 配置自动保存到 localStorage
-MeToast.use('accessibility'); // 屏幕阅读器实时朗读 toast 内容
-内置插件详情：keyboard 监听 keydown Escape 键；persistence 将配置写入 localStorage 并在页面加载时恢复；accessibility 在 afterShow/afterUpdate 钩子中通过 aria-live 区域朗读 toast 内容。
+MeToast.use('accessibility'); // 屏幕阅读器实时朗读 toast 内容
+MeToast.use('dedupe'); // 相同 type+message 自动去重
+内置插件详情：keyboard 监听 keydown Escape 键；persistence 将配置写入 localStorage 并在页面加载时恢复；accessibility 在 afterShow/afterUpdate 钩子中通过 aria-live 区域朗读 toast 内容；dedupe 在 beforeShow 钩子中检测相同 type+message 的已有 toast，更新它并阻止重复弹出。
destroy()
完全销毁。关闭所有 Toast、移除所有 DOM 容器和注入的样式标签、清空内存缓存。
MeToast.destroy();
+
+React 适配器
+主包保持零依赖。React 适配器通过子路径 @metona-team/metona-toast/react 导入，react 为 optional peerDependency，未使用 React 的项目不受影响。
+// 安装
+npm install @metona-team/metona-toast react
+
+// useToast — 组件卸载时自动移除本组件创建的 Toast
+import { useToast, Toast } from '@metona-team/metona-toast/react';
+
+function SubmitButton() {
+ const toast = useToast();
+ const submit = async () => {
+ const loading = toast.loading('正在提交...');
+ try { await api(); loading.success('提交成功！'); }
+ catch (e) { loading.error('提交失败'); }
+ };
+ return <button onClick={submit}>提交</button>;
+}
+
+// Toast 组件 — props 变化时更新，卸载时自动移除（autoClose 默认 true）
+function SaveIndicator({ saving }) {
+ return saving ? <Toast type="info" message="正在保存..." /> : null;
+}
+
全部配置项
以下配置可用于 configure()、init() 或单个 Toast 方法的 opts 参数。
@@ -441,7 +467,8 @@ MeToast.use('accessibility'); offset | number | 24 | 容器到屏幕边缘的距离(px) |
| pauseOnHover | boolean | true | 鼠标悬停时暂停 duration 倒计时和进度条 |
| closeOnClick | boolean | true | 点击 Toast 任意位置关闭。关闭按钮始终触发关闭 |
-| draggable | boolean | true | 允许拖拽关闭。拖拽超过 120px 触发关闭 |
+| draggable | boolean | true | 允许拖拽关闭。拖拽超过 dragThreshold 触发关闭 |
+| dragThreshold | number | 120 | 拖拽关闭阈值(px)，位移超过该值松手即关闭 |
| showProgress | boolean | true | 显示 duration 倒计时进度条 |
| progressDirection | string | 'horizontal' | 进度条方向：horizontal(底部水平) / vertical(右侧垂直) |
| icon | boolean | true | 显示类型对应图标（success→对勾等） |
diff --git a/site/index.html b/site/index.html
index 648cf53..81790c6 100644
--- a/site/index.html
+++ b/site/index.html
@@ -247,7 +247,7 @@ orderGroup.dismiss(); // 一键关闭
diff --git a/src/api.ts b/src/api.ts
index c19e9e1..2e02752 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast API — meToast 核心 API 对象
* @module api
- * @version 0.3.0
+ * @version 0.4.0
*/
import { Toast, _containerCache } from './toast.js';
@@ -78,7 +78,10 @@ const meToast: MeToast = {
const t = new Toast(merged);
t.create();
- this._toasts.set(t.id, t);
+ // beforeShow/onBeforeShow 拦截（返回 false）时 el 为 null，不注册幽灵实例
+ if (t.el !== null) {
+ this._toasts.set(t.id, t);
+ }
return t;
},
@@ -159,15 +162,22 @@ const meToast: MeToast = {
});
},
+ /**
+ * loading 链式转换 — 原地 update 同一实例（id 稳定，不重建 DOM）
+ * duration 从 0 恢复为默认值，使转换后的 toast 自动关闭
+ */
_resolve(loadingToast: ToastInstance, type: string, message: string, opts: ToastOptions): ToastInstance | null {
- const id = loadingToast.id;
- const old = this._toasts.get(id);
+ const old = this._toasts.get(loadingToast.id);
if (!old) return null;
- const position = old.config.position;
- old.close();
+ old.update({
+ ...opts,
+ type,
+ message,
+ duration: opts.duration ?? (old.config.duration || this._config.duration),
+ } as ToastOptions);
- return this._emit({ ...opts, type, message, position } as ToastOptions);
+ return old;
},
confirm(message: string, opts: ConfirmOptions = {}): Promise {
diff --git a/src/constants.ts b/src/constants.ts
index aca715e..e39346c 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Constants — 常量定义
* @module constants
- * @version 0.3.0
+ * @version 0.4.0
*/
import { ICONS } from './icons.js';
@@ -12,7 +12,7 @@ export { ICONS, LOCALES };
/**
* 版本号 — 唯一来源，发布时只需修改此处
*/
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.0';
/**
* 默认配置
@@ -26,6 +26,7 @@ export const DEFAULTS = Object.freeze({
pauseOnHover: true,
closeOnClick: true,
draggable: true,
+ dragThreshold: 120,
showProgress: true,
progressDirection: 'horizontal' as const,
icon: true,
diff --git a/src/i18n.ts b/src/i18n.ts
index 546213d..1efb5a4 100644
--- a/src/i18n.ts
+++ b/src/i18n.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast i18n — 国际化管理
* @module i18n
- * @version 0.3.0
+ * @version 0.4.0
*/
import { LOCALES } from './constants.js';
diff --git a/src/icons.ts b/src/icons.ts
index b8c38e4..7b0c2d7 100644
--- a/src/icons.ts
+++ b/src/icons.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Icons — 图标SVG定义
* @module icons
- * @version 0.3.0
+ * @version 0.4.0
* @description 107 个内置 SVG 图标
*/
diff --git a/src/index.ts b/src/index.ts
index 235fdab..db60f63 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast — 轻量级Toast通知库
* @module metona-toast
- * @version 0.3.0
+ * @version 0.4.0
* @author thzxx
* @license MIT
*/
diff --git a/src/locales.ts b/src/locales.ts
index 29d6dc4..6017cef 100644
--- a/src/locales.ts
+++ b/src/locales.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Locales — 国际化翻译数据
* @module locales
- * @version 0.3.0
+ * @version 0.4.0
* @description 内置 zh-CN / en-US 完整翻译
*/
diff --git a/src/plugins.ts b/src/plugins.ts
index a1a14b6..562bcae 100644
--- a/src/plugins.ts
+++ b/src/plugins.ts
@@ -1,11 +1,12 @@
/**
* MetonaToast Plugins — 插件系统
* @module plugins
- * @version 0.3.0
+ * @version 0.4.0
*/
import { t } from './i18n.js';
-import type { Plugin, PluginManager as IPluginManager, PluginUtils } from './types.js';
+import { Toast } from './toast.js';
+import type { Plugin, PluginManager as IPluginManager, PluginUtils, ToastInstance } from './types.js';
/**
* 插件管理器
@@ -176,6 +177,36 @@ const presetPlugins: Record = {
setTimeout(() => { if (el.parentNode) el.parentNode.removeChild(el); }, 3000);
},
},
+
+ /**
+ * 去重插件 — 相同 type + message 的 toast 自动合并（更新已有的一条）
+ */
+ dedupe: {
+ name: 'dedupe',
+ version: '1.0.0',
+ description: '相同类型和消息的 Toast 自动去重，更新已有实例而非重复弹出',
+ _off: null as (() => void) | null,
+
+ install(this: Plugin) {
+ const off = Toast.on('beforeShow', (toast: ToastInstance) => {
+ const existing = Array.from(Toast._registry.values()).find(
+ t => !t.closing && t.type === toast.type && t.message === toast.message
+ );
+ if (existing) {
+ existing.update({ title: toast.title || existing.title });
+ return false;
+ }
+ return undefined;
+ });
+ (this as Record)._off = off;
+ },
+
+ uninstall(this: Plugin) {
+ const off = (this as Record)._off as (() => void) | null;
+ if (off) off();
+ (this as Record)._off = null;
+ },
+ },
};
/**
diff --git a/src/react.ts b/src/react.ts
new file mode 100644
index 0000000..3dbc0d5
--- /dev/null
+++ b/src/react.ts
@@ -0,0 +1,122 @@
+/**
+ * MetonaToast React — React 适配器
+ * @module react
+ * @version 0.4.0
+ * @description useToast hook + 声明式 组件。主包保持零依赖，React 为 optional peerDependency
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import MeToast from './index.js';
+import type { ToastInstance, ToastOptions } from './types.js';
+
+/** 支持声明式渲染的 Toast 类型 */
+export type ReactToastType = 'success' | 'error' | 'warning' | 'info' | 'show' | (string & {});
+
+export interface ToastProps extends Omit {
+ message: string;
+ type?: ReactToastType;
+ /** 组件卸载时自动移除该 Toast（默认 true）。设为 false 则 Toast 独立于组件生命周期 */
+ autoClose?: boolean;
+}
+
+const SHOW_METHODS = ['success', 'error', 'warning', 'info', 'show'] as const;
+type ShowMethod = (typeof SHOW_METHODS)[number];
+
+/** 有 id 的可追踪对象（ToastInstance / LoadingControl） */
+interface Tracked {
+ id: string;
+}
+
+const showToast = (method: ShowMethod, message: string, opts: Omit): ToastInstance => {
+ switch (method) {
+ case 'success': return MeToast.success(message, opts);
+ case 'error': return MeToast.error(message, opts);
+ case 'warning': return MeToast.warning(message, opts);
+ case 'info': return MeToast.info(message, opts);
+ default: return MeToast.show(message, opts);
+ }
+};
+
+/**
+ * 创建绑定清理集合的 API — 组件卸载时自动移除本组件创建的 Toast。
+ * 纯函数，便于独立测试与扩展。
+ */
+export const createBoundApi = (cleanup: Set): Record => {
+ const track = (fn: () => T): T => {
+ const result = fn();
+ if (result && result.id) cleanup.add(result.id);
+ return result;
+ };
+
+ const bound: Record = {
+ ...MeToast,
+
+ success: (messageOrOpts: string | ToastOptions, opts?: ToastOptions) =>
+ track(() => MeToast.success(messageOrOpts, opts)),
+ error: (messageOrOpts: string | ToastOptions, opts?: ToastOptions) =>
+ track(() => MeToast.error(messageOrOpts, opts)),
+ warning: (messageOrOpts: string | ToastOptions, opts?: ToastOptions) =>
+ track(() => MeToast.warning(messageOrOpts, opts)),
+ info: (messageOrOpts: string | ToastOptions, opts?: ToastOptions) =>
+ track(() => MeToast.info(messageOrOpts, opts)),
+ show: (messageOrOpts: string | ToastOptions, opts?: ToastOptions) =>
+ track(() => MeToast.show(messageOrOpts, opts)),
+ loading: (messageOrOpts: string | ToastOptions, opts?: ToastOptions) =>
+ track(() => MeToast.loading(messageOrOpts, opts)),
+
+ // 通过 id 关闭时同步清理集合，避免卸载时重复移除
+ dismiss: (id?: string) => {
+ if (id) cleanup.delete(id);
+ return MeToast.dismiss(id);
+ },
+ removeToast: (id: string) => {
+ cleanup.delete(id);
+ return MeToast.removeToast(id);
+ },
+ };
+
+ return bound;
+};
+
+/**
+ * useToast — 返回 MeToast API，但本组件创建的 Toast 会在组件卸载时自动移除。
+ * 适合"通知随组件生命周期"的场景（如表单提交、异步任务页）。
+ */
+export const useToast = (): Record => {
+ const cleanupRef = useRef>(new Set());
+
+ useEffect(() => {
+ const set = cleanupRef.current;
+ return () => {
+ set.forEach(id => MeToast.removeToast(id));
+ set.clear();
+ };
+ }, []);
+
+ return useMemo(() => createBoundApi(cleanupRef.current), []);
+};
+
+/**
+ * Toast — 声明式 Toast 组件。props 变化时更新内容（重新创建实例），
+ * 组件卸载时自动移除（autoClose 默认 true）。
+ */
+export const Toast = (props: ToastProps): null => {
+ const { message, type, autoClose = true, ...rest } = props;
+ const toastRef = useRef(null);
+ const restKey = JSON.stringify(rest);
+
+ useEffect(() => {
+ const method: ShowMethod = SHOW_METHODS.includes(type as ShowMethod) ? (type as ShowMethod) : 'show';
+ toastRef.current = showToast(method, message, rest);
+
+ return () => {
+ if (autoClose) toastRef.current?.remove();
+ toastRef.current = null;
+ };
+ // autoClose 不参与重建依赖：它只影响卸载时的清理行为
+ }, [message, type, restKey]);
+
+ return null;
+};
+
+export { MeToast };
diff --git a/src/styles.ts b/src/styles.ts
index 95d95ac..64aefbe 100644
--- a/src/styles.ts
+++ b/src/styles.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Styles — 样式管理
* @module styles
- * @version 0.3.0
+ * @version 0.4.0
*/
import type { ThemeConfig } from './types.js';
@@ -363,6 +363,41 @@ const generateCSS = (): string => {
transition: transform 0.1s linear;
}
+ /* RTL 镜像：进度条从右向左收缩、side 条移到右侧、类型色条翻转到右边 */
+ [dir="rtl"] .met-bar {
+ transform-origin: right;
+ }
+ [dir="rtl"] .met-side {
+ left: auto;
+ right: 0;
+ border-radius: 0 12px 12px 0;
+ }
+ [dir="rtl"] .met-progress-v {
+ left: auto;
+ right: 0;
+ border-radius: 0 12px 12px 0;
+ }
+ [dir="rtl"] .met-toast.met-success {
+ border-left-width: 1px;
+ border-right: 4px solid #10b981;
+ }
+ [dir="rtl"] .met-toast.met-error {
+ border-left-width: 1px;
+ border-right: 4px solid #ef4444;
+ }
+ [dir="rtl"] .met-toast.met-warning {
+ border-left-width: 1px;
+ border-right: 4px solid #f59e0b;
+ }
+ [dir="rtl"] .met-toast.met-info {
+ border-left-width: 1px;
+ border-right: 4px solid #3b82f6;
+ }
+ [dir="rtl"] .met-toast.met-loading {
+ border-left-width: 1px;
+ border-right: 4px solid #6366f1;
+ }
+
.met-container::-webkit-scrollbar { width: 6px; height: 6px; }
.met-container::-webkit-scrollbar-track { background: transparent; }
.met-container::-webkit-scrollbar-thumb { background: rgba(0,0,0,0.2); border-radius: 3px; }
diff --git a/src/templates.ts b/src/templates.ts
index 4f17038..c8b7872 100644
--- a/src/templates.ts
+++ b/src/templates.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Templates — HTML 模板辅助函数
* @module templates
- * @version 0.3.0
+ * @version 0.4.0
* @description confirm / prompt / progress / action 的 DOM 模板
*/
diff --git a/src/themes.ts b/src/themes.ts
index 4d99794..cde064a 100644
--- a/src/themes.ts
+++ b/src/themes.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Themes — 主题管理
* @module themes
- * @version 0.3.0
+ * @version 0.4.0
*/
import { THEMES } from './constants.js';
diff --git a/src/toast.ts b/src/toast.ts
index 10a228c..4d49942 100644
--- a/src/toast.ts
+++ b/src/toast.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Toast — Toast 类
* @module toast
- * @version 0.3.0
+ * @version 0.4.0
*/
import { generateId, escapeHTML } from './utils.js';
@@ -204,6 +204,8 @@ export class Toast implements ToastInstance {
el.className = `met-container ${position}`;
el.setAttribute('aria-label', 'Notifications');
el.setAttribute('role', 'region');
+ // RTL 语言设置容器文字方向，使内容/关闭按钮/进度条正确镜像
+ if (isRTL) el.setAttribute('dir', 'rtl');
const posStyles: Record = {
'top-left': 'top:0;left:0;align-items:flex-start',
@@ -417,7 +419,8 @@ export class Toast implements ToastInstance {
el.releasePointerCapture(e.pointerId);
el.style.transition = '';
- if (Math.abs(dx) > 120) {
+ const threshold = this.config.dragThreshold ?? 120;
+ if (Math.abs(dx) > threshold) {
el.style.transform = `translate(${dx * 2}px, ${dy}px) rotate(${dx * 0.2}deg)`;
el.style.opacity = '0';
setTimeout(() => this.close(true), 250);
@@ -535,6 +538,18 @@ export class Toast implements ToastInstance {
content.innerHTML = `${safeTitle}${safeMessage}`;
}
+ // duration 变更：重启或停止计时器（loading 0 → N 转换、动态调整时长等场景）
+ if (partial.duration !== undefined && partial.duration !== this.config.duration) {
+ this.config.duration = partial.duration;
+ if (this.rafId !== null) cancelAnimationFrame(this.rafId);
+ this.rafId = null;
+ this.remaining = Math.max(0, partial.duration);
+ if (partial.duration > 0 && !this.paused) {
+ this.startedAt = Date.now();
+ this._startTimer();
+ }
+ }
+
// resetTimerOnUpdate: 更新内容后重置计时器
if (this.config.resetTimerOnUpdate && (this.config.duration || 0) > 0) {
if (this.rafId !== null) cancelAnimationFrame(this.rafId);
diff --git a/src/types.ts b/src/types.ts
index 69a8a1b..e02477d 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast — 核心类型定义
* @module types
- * @version 0.3.0
+ * @version 0.4.0
*/
// ========== 基础类型 ==========
@@ -72,6 +72,7 @@ export interface ToastConfig {
pauseOnHover?: boolean;
closeOnClick?: boolean;
draggable?: boolean;
+ dragThreshold?: number;
showProgress?: boolean;
progressDirection?: ToastProgressDirection;
icon?: boolean;
diff --git a/src/utils.ts b/src/utils.ts
index db3b3d2..715b22e 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast Utils — 工具函数
* @module utils
- * @version 0.3.0
+ * @version 0.4.0
*/
/**
diff --git a/tests/coverage.test.ts b/tests/coverage.test.ts
index 08fe743..5a3bf5c 100644
--- a/tests/coverage.test.ts
+++ b/tests/coverage.test.ts
@@ -1,7 +1,7 @@
/**
* MetonaToast 覆盖率补充测试 — 目标 95%+
* @module tests
- * @version 0.3.0
+ * @version 0.4.0
*/
import MeToast, { Toast, VERSION } from '../src/index';
@@ -809,7 +809,7 @@ describe('api.ts 覆盖率', () => {
test('getStatus 返回完整状态', () => {
const status = MeToast.getStatus();
- expect(status.version).toBe('0.3.0');
+ expect(status.version).toBe('0.4.0');
expect(status.toasts).toBeGreaterThanOrEqual(0);
expect(status.theme).toBeDefined();
expect(status.locale).toBeDefined();
@@ -1089,32 +1089,8 @@ describe('styles.ts 覆盖率', () => {
});
// ==================================================================
-// 9. utils.ts 覆盖率补充
+// 9. utils.ts 覆盖率补充（SSR 分支见 tests/ssr.test.ts — 独立环境隔离）
// ==================================================================
-describe('utils.ts 覆盖率', () => {
- test('escapeHTML SSR 路径（无 document）', () => {
- // 需要绕过 mock document
- const originalDoc = (global as Record).document;
- (global as Record).document = undefined;
- jest.resetModules();
- const { escapeHTML } = require('../src/utils.js');
- const result = escapeHTML('');
- expect(result).not.toContain('');
+ expect(result).not.toContain('