MetonaTeam/MetonaToast
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bbff631f4fb88c9dd13ecf6cc443c51ead843220
MetonaToast/dist/metona-toast.d.ts
T
tianhao bbff631f4f release: v0.4.0 — React 适配器、loading链式id稳定、dragThreshold、RTL适配、dedupe插件 
- React 适配器子包：@metona-team/metona-toast/react — useToast() hook + 声明式 <Toast /> 组件，组件卸载自动清理；react 为 optional peerDependency，主包保持零依赖
- loading 链式转换改原地 update：id 稳定不重建 DOM，转换后 duration 恢复默认自动关闭；update() 支持 duration 变更动态重启计时器
- _emit 幽灵实例修复：beforeShow 拦截后的 toast 不再注册进 _toasts
- dragThreshold 配置项（默认 120px，原硬编码）；RTL 容器 dir 属性 + 进度条/side 条/色条镜像
- dedupe 预设插件：相同 type+message 自动去重，支持 uninstall
- jest 环境隔离测试独立成 tests/ssr.test.ts（resetModules 不再污染共享模块状态）；新增 tests/setup.ts 补 TextEncoder
- 文档：README/docs.html 补 React 适配器、dedupe、dragThreshold；CHANGELOG 更新；328 测试全过
2026-08-08 14:45:19 +08:00

564 lines
21 KiB
TypeScript
Raw Blame History

/**
* MetonaToast — 核心类型定义
* @module types
* @version 0.4.0
*/
/** Toast 通知类型（107种内置图标类型） */
type ToastType = 'default' | 'success' | 'error' | 'warning' | 'info' | 'loading' | 'check' | 'x' | 'alert' | 'question' | 'star' | 'heart' | 'bell' | 'mail' | 'settings' | 'user' | 'home' | 'search' | 'plus' | 'minus' | 'edit' | 'trash' | 'download' | 'upload' | 'share' | 'link' | 'external' | 'clock' | 'calendar' | 'map' | 'compass' | 'globe' | 'wifi' | 'cloud' | 'sun' | 'moon' | 'zap' | 'activity' | 'cpu' | 'database' | 'server' | 'terminal' | 'code' | 'git' | 'package' | 'layers' | 'grid' | 'list' | 'filter' | 'sort' | 'refresh' | 'sync' | 'power' | 'battery' | 'bluetooth' | 'volume' | 'mic' | 'camera' | 'image' | 'video' | 'music' | 'file' | 'folder' | 'clipboard' | 'save' | 'print' | 'eye' | 'eyeOff' | 'lock' | 'unlock' | 'shield' | 'key' | 'flag' | 'bookmark' | 'tag' | 'gift' | 'award' | 'target' | 'crosshair' | 'move' | 'maximize' | 'minimize' | 'copy' | 'cut' | 'paste' | 'rotateCw' | 'rotateCcw' | 'zoomIn' | 'zoomOut' | 'crop' | 'sliders' | 'toggleLeft' | 'toggleRight' | 'checkCircle' | 'xCircle' | 'alertCircle' | 'infoCircle' | 'helpCircle' | 'alertTriangle' | 'checkSquare' | 'square' | 'circle' | 'triangle' | 'hexagon' | 'octagon' | 'pentagon' | 'diamond';
/** Toast 显示位置 */
type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
/** Toast 主题 */
type ToastTheme = 'light' | 'dark' | 'auto' | 'warm' | (string & {});
/** Toast 动画类型 */
type ToastAnimation = 'slide' | 'fade' | 'scale' | 'bounce' | 'flip' | 'rotate' | 'zoom' | 'slideUp' | 'slideDown' | 'slideLeft' | 'slideRight' | (string & {});
/** 进度条方向 */
type ToastProgressDirection = 'horizontal' | 'vertical';
interface TypeColor {
fg: string;
bg: string;
}
interface ToastConfig {
position?: ToastPosition;
duration?: number;
max?: number;
gap?: number;
offset?: number;
pauseOnHover?: boolean;
closeOnClick?: boolean;
draggable?: boolean;
dragThreshold?: number;
showProgress?: boolean;
progressDirection?: ToastProgressDirection;
icon?: boolean;
closeButton?: boolean;
theme?: ToastTheme;
animation?: ToastAnimation;
zIndex?: number;
width?: number | string;
className?: string;
style?: Record<string, string>;
onShow?: ((toast: ToastInstance) => void) | null;
onBeforeShow?: ((toast: ToastInstance) => boolean | void) | null;
onClose?: ((toast: ToastInstance) => void) | null;
onClick?: ((toast: ToastInstance) => void) | null;
onUpdate?: ((toast: ToastInstance) => void) | null;
render?: ((toast: ToastInstance) => string) | null;
resetTimerOnUpdate?: boolean;
notifyWhenHidden?: boolean;
onError?: ((errorInfo: ErrorInfo) => void) | null;
group?: string | null;
locale?: string;
plugins?: Array<string | Plugin>;
}
interface ErrorInfo {
hook?: string;
source?: string;
error: Error;
toast?: ToastInstance;
}
interface ToastOptions extends Partial<ToastConfig> {
type?: string;
title?: string;
message?: string;
content?: string;
html?: string;
iconHTML?: string;
id?: string;
}
interface ToastInstance {
id: string;
type: string;
title: string;
message: string;
html: string;
iconHTML: string;
config: ToastConfig;
el: HTMLElement | null;
barEl: HTMLElement | null;
rafId: number | null;
remaining: number;
startedAt: number;
paused: boolean;
closing: boolean;
group: string | null;
_cleanups: Array<() => void>;
_palette(): {
theme: string;
c: TypeColor;
t: Partial<ThemeConfig>;
};
create(): this;
update(partial: Partial<ToastOptions>): this;
updatePosition(position: string): this;
remove(): void;
close(immediate?: boolean): void;
_pause(): void;
_resume(): void;
_destroy(): void;
}
interface LoadingControl {
id: string;
success(message?: string, opts?: ToastOptions): ToastInstance | null;
error(message?: string, opts?: ToastOptions): ToastInstance | null;
info(message?: string, opts?: ToastOptions): ToastInstance | null;
warning(message?: string, opts?: ToastOptions): ToastInstance | null;
update(partial: Partial<ToastOptions>): unknown;
dismiss(): void;
}
interface ProgressControl {
id: string;
setProgress(percent: number): void;
complete(message?: string): void;
error(message?: string): void;
dismiss(): void;
}
interface CountdownControl {
id: string;
cancel(): void;
pause(): void;
resume(): void;
}
interface ActionControl {
id: string;
toast: ToastInstance;
dismiss(): void;
}
interface QueueControl {
then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<void | TResult>;
cancel(): void;
}
interface GroupAPI {
_group: string;
show: (...args: unknown[]) => ToastInstance;
success: (...args: unknown[]) => ToastInstance;
error: (...args: unknown[]) => ToastInstance;
warning: (...args: unknown[]) => ToastInstance;
info: (...args: unknown[]) => ToastInstance;
loading: (...args: unknown[]) => LoadingControl;
action: (...args: unknown[]) => ActionControl;
dismiss(): void;
count(): number;
}
interface ActionButton {
text: string;
onClick: (toast: ToastInstance) => void;
color?: string;
style?: Record<string, string>;
close?: boolean;
}
interface PromiseOptions extends ToastOptions {
loading?: string;
success?: string;
error?: string;
}
interface ConfirmOptions extends ToastOptions {
confirmText?: string;
confirmColor?: string;
cancelText?: string;
cancelColor?: string;
}
interface PromptOptions extends ToastOptions {
inputType?: string;
placeholder?: string;
defaultValue?: string;
submitText?: string;
submitColor?: string;
cancelText?: string;
cancelColor?: string;
}
interface ProgressOptions extends ToastOptions {
progressColor?: string;
}
interface CountdownOptions extends ToastOptions {
onComplete?: (() => void) | null;
}
interface QueueOptions extends ToastOptions {
delay?: number;
}
interface StackOptions extends ToastOptions {
stagger?: number;
}
interface InitOptions {
config?: Partial<ToastConfig>;
theme?: ToastTheme;
locale?: string;
plugins?: Array<string | Plugin>;
}
interface StatusInfo {
version: string;
toasts: number;
theme: string;
locale: string;
plugins: string[];
animations: number;
}
interface AnimationConfig {
enter: Record<string, string | number>;
leave: Record<string, string | number>;
duration: number;
easing: string;
name?: string;
delay?: number;
iterations?: number;
direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
fillMode?: 'none' | 'forwards' | 'backwards' | 'both';
}
interface AnimationUtils {
register(name: string, config: Partial<AnimationConfig>): void;
unregister(name: string): void;
get(name: string): AnimationConfig | null;
getAnimationNames(): string[];
getActiveCount(): number;
cancelAll(): void;
reset(): void;
destroy(): void;
}
interface ThemeConfig {
bg: string;
text: string;
border: string;
shadow: string;
hoverShadow: string;
progressBg: string;
closeHoverBg: string;
backdropFilter?: string;
}
interface ThemePreview {
name: string;
resolved: string;
colors: {
background: string;
text: string;
border: string;
};
isDark: boolean;
isLight: boolean;
isAuto: boolean;
}
interface ThemeUtils {
getSystemTheme(): 'light' | 'dark';
resolveTheme(theme: string): string;
getThemeConfig(theme: string): ThemeConfig;
applyTheme(theme: string): void;
getCurrentTheme(): string;
getResolvedTheme(): string;
switchTheme(theme: string): void;
toggleTheme(): void;
resetToAuto(): void;
initTheme(): void;
watchSystemTheme(): void;
unwatchSystemTheme(): void;
addThemeListener(listener: (theme: string, resolved: string) => void): () => void;
removeThemeListener(listener: (theme: string, resolved: string) => void): void;
clearThemeListeners(): void;
registerTheme(name: string, config: ThemeConfig): void;
unregisterTheme(name: string): void;
getAllThemes(): Record<string, ThemeConfig>;
getThemeNames(): string[];
hasTheme(name: string): boolean;
getThemePreview(theme: string): ThemePreview;
generateThemeCSS(theme: string): string;
applyThemeCSS(theme: string): void;
removeThemeCSS(): void;
saveTheme(theme: string): void;
loadTheme(): string;
}
interface LocaleInfo {
code: string;
name: string;
direction: 'ltr' | 'rtl';
isSupported: boolean;
isCurrent: boolean;
isFallback: boolean;
}
interface I18nUtils {
t(key: string, params?: Record<string, string | number>): string;
plural(key: string, count: number, params?: Record<string, string | number>): string;
getCurrentLocale(): string;
setCurrentLocale(locale: string): void;
switchLocale(locale: string): void;
getFallbackLocale(): string;
setFallbackLocale(locale: string): void;
hasTranslation(key: string): boolean;
getTranslations(locale: string): Record<string, unknown>;
addTranslations(locale: string, translations: Record<string, unknown>): void;
removeTranslation(locale: string, key: string): void;
clearTranslations(locale: string): void;
getSupportedLocales(): string[];
isLocaleSupported(locale: string): boolean;
getLocaleName(locale: string): string;
getLocaleDirection(locale: string): 'ltr' | 'rtl';
getLocaleInfo(locale: string): LocaleInfo;
getAllLocaleInfo(): LocaleInfo[];
formatNumber(number: number, options?: Intl.NumberFormatOptions): string;
formatCurrency(amount: number, currency?: string, options?: Intl.NumberFormatOptions): string;
formatPercent(value: number, options?: Intl.NumberFormatOptions): string;
formatDate(date: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
formatTime(date: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
formatRelativeTime(date: Date | number | string, options?: Intl.RelativeTimeFormatOptions): string;
formatList(list: string[], options?: Record<string, unknown>): string;
formatPlural(count: number, options?: Intl.PluralRulesOptions): string;
addLocaleListener(listener: (locale: string) => void): () => void;
removeLocaleListener(listener: (locale: string) => void): void;
clearLocaleListeners(): void;
initI18n(): void;
saveLocale(locale: string): void;
loadLocale(): string;
getDefaultLocale(): string;
}
interface Plugin {
name: string;
version?: string;
description?: string;
hooks?: Record<string, (...args: unknown[]) => void>;
middleware?: (...args: unknown[]) => unknown;
install?: (manager: PluginManager) => void | Record<string, unknown> | null;
uninstall?: (manager: PluginManager) => void;
init?: (manager: PluginManager) => void;
destroy?: (manager: PluginManager) => void;
installed?: boolean;
enabled?: boolean;
[key: string]: unknown;
}
interface PluginManager {
register(name: string, plugin: Plugin): PluginManager;
unregister(name: string): PluginManager;
get(name: string): Plugin | null;
has(name: string): boolean;
getAll(): Plugin[];
getNames(): string[];
enable(name: string): PluginManager;
disable(name: string): PluginManager;
isEnabled(name: string): boolean;
destroy(): void;
}
interface PluginUtils {
createManager(): PluginManager;
register(name: string, plugin: Plugin): PluginManager;
unregister(name: string): PluginManager;
get(name: string): Plugin | null;
has(name: string): boolean;
getAll(): Plugin[];
getNames(): string[];
enable(name: string): PluginManager;
disable(name: string): PluginManager;
isEnabled(name: string): boolean;
getPreset(name: string): Plugin | null;
getAllPresets(): Record<string, Plugin>;
createPlugin(config: Partial<Plugin>): Plugin;
validatePlugin(plugin: Partial<Plugin>): {
valid: boolean;
errors: string[];
};
}
interface MeToast {
version: string;
_toasts: Map<string, ToastInstance>;
_config: ToastConfig;
_destroyed?: boolean;
_emit(opts: ToastOptions): ToastInstance;
_remove(id: string): void;
_resolve(loadingToast: ToastInstance, type: string, message: string, opts: ToastOptions): ToastInstance | null;
_groupCount(name: string): number;
configure(opts: Partial<ToastConfig>): MeToast;
init(options?: InitOptions): MeToast;
destroy(): void;
getStatus(): StatusInfo;
getConfig(): ToastConfig;
updateConfig(config: Partial<ToastConfig>): MeToast;
resetConfig(): MeToast;
show(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
success(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
error(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
warning(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
info(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
loading(messageOrOpts: string | ToastOptions, opts?: ToastOptions): LoadingControl;
promise<T>(promise: Promise<T>, opts?: PromiseOptions): Promise<T>;
confirm(message: string, opts?: ConfirmOptions): Promise<boolean>;
prompt(message: string, opts?: PromptOptions): Promise<string | null>;
progress(messageOrOpts: string | ToastOptions, opts?: ProgressOptions): ProgressControl;
countdown(message: string, seconds?: number, opts?: CountdownOptions): CountdownControl;
action(messageOrOpts: string | ToastOptions, actions?: ActionButton[], opts?: ToastOptions): ActionControl;
queue(messages: Array<string | ToastOptions>, opts?: QueueOptions): QueueControl;
stack(messages: Array<string | ToastOptions>, opts?: StackOptions): void;
group(name: string): GroupAPI;
dismissGroup(name: string): void;
find(id: string): ToastInstance | undefined;
dismiss(id?: string): void;
removeToast(id: string): void;
clear(position?: ToastPosition): void;
getToasts(): ToastInstance[];
count(): number;
hasToasts(): boolean;
getToast(id: string): ToastInstance | null;
closeAll(): void;
clearAll(): void;
pauseAll(): void;
resumeAll(): void;
updateAll(partial: Partial<ToastOptions>): void;
findToasts(predicate: (toast: ToastInstance) => boolean): ToastInstance[];
findByType(type: ToastType): ToastInstance[];
findByPosition(position: ToastPosition): ToastInstance[];
getAll(): Map<string, ToastInstance>;
use(plugin: string | Plugin, options?: Record<string, unknown>): MeToast;
animations: AnimationUtils;
themes: ThemeUtils;
i18n: I18nUtils;
plugins: PluginUtils;
presetPlugins: Record<string, Plugin>;
}
declare global {
interface Window {
MeToast: MeToast;
Met: MeToast;
}
}
/**
* MetonaToast Toast — Toast 类
* @module toast
* @version 0.4.0
*/
/**
* Toast 类 — 核心通知组件
*/
declare class Toast implements ToastInstance {
static _hooks: Map<string, Array<(toast: Toast) => boolean | void>>;
static _registry: Map<string, Toast>;
private static _onError;
private static _removeToast;
/**
* 设置 Toast 类级别的回调函数
*/
static setCallbacks(callbacks: {
onError?: ((errorInfo: ErrorInfo) => void) | null;
removeToast?: ((id: string) => void) | null;
}): void;
static on(name: string, fn: (toast: Toast) => boolean | void): () => void;
static off(name: string, fn: (toast: Toast) => boolean | void): void;
/**
* 触发钩子 — 如果任意钩子返回 false 则整体返回 false
* toast 参数可选：全局事件（configChange/themeChange 等）不关联具体 toast
*/
static trigger(name: string, toast?: Toast | null): boolean;
id: string;
type: string;
title: string;
message: string;
html: string;
iconHTML: string;
config: ToastConfig;
el: HTMLElement | null;
barEl: HTMLElement | null;
rafId: number | null;
remaining: number;
startedAt: number;
paused: boolean;
closing: boolean;
group: string | null;
_cleanups: Array<() => void>;
constructor(opts: ToastOptions);
_palette(): {
theme: string;
c: TypeColor;
t: Partial<ThemeConfig>;
};
create(): this;
_getContainer(): HTMLElement;
_limitToasts(container: HTMLElement): void;
_buildClassName(theme: string): string;
_applyStyles(el: HTMLElement, _theme: string, _t: Partial<ThemeConfig>): void;
_buildContent(el: HTMLElement, c: TypeColor): void;
_bindEvents(el: HTMLElement): void;
_bindDrag(el: HTMLElement): void;
_startTimer(resuming?: boolean): void;
_pause(): void;
_resume(): void;
update(partial: Partial<ToastOptions>): this;
/**
* 运行时移动 Toast 到新位置
*/
updatePosition(position: string): this;
/**
* 立即从 DOM 和内存中移除（不触发离场动画）
*/
remove(): void;
close(immediate?: boolean): void;
_destroy(): void;
}
/**
* MetonaToast Constants — 常量定义
* @module constants
* @version 0.4.0
*/
/**
* 版本号 — 唯一来源，发布时只需修改此处
*/
declare const VERSION = "0.4.0";
/**
* 增强的 MeToast 对象 — 在 meToast 基础上注入子模块
*/
declare const enhancedMeToast: {
version: string;
animations: AnimationUtils;
themes: ThemeUtils;
i18n: I18nUtils;
plugins: PluginUtils;
presetPlugins: Record<string, Plugin>;
_toasts: Map<string, ToastInstance>;
_config: ToastConfig;
_destroyed?: boolean;
_emit(opts: ToastOptions): ToastInstance;
_remove(id: string): void;
_resolve(loadingToast: ToastInstance, type: string, message: string, opts: ToastOptions): ToastInstance | null;
_groupCount(name: string): number;
configure(opts: Partial<ToastConfig>): MeToast;
init(options?: InitOptions): MeToast;
destroy(): void;
getStatus(): StatusInfo;
getConfig(): ToastConfig;
updateConfig(config: Partial<ToastConfig>): MeToast;
resetConfig(): MeToast;
show(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
success(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
error(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
warning(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
info(messageOrOpts: string | ToastOptions, opts?: ToastOptions): ToastInstance;
loading(messageOrOpts: string | ToastOptions, opts?: ToastOptions): LoadingControl;
promise<T>(promise: Promise<T>, opts?: PromiseOptions): Promise<T>;
confirm(message: string, opts?: ConfirmOptions): Promise<boolean>;
prompt(message: string, opts?: PromptOptions): Promise<string | null>;
progress(messageOrOpts: string | ToastOptions, opts?: ProgressOptions): ProgressControl;
countdown(message: string, seconds?: number, opts?: CountdownOptions): CountdownControl;
action(messageOrOpts: string | ToastOptions, actions?: ActionButton[], opts?: ToastOptions): ActionControl;
queue(messages: Array<string | ToastOptions>, opts?: QueueOptions): QueueControl;
stack(messages: Array<string | ToastOptions>, opts?: StackOptions): void;
group(name: string): GroupAPI;
dismissGroup(name: string): void;
find(id: string): ToastInstance | undefined;
dismiss(id?: string): void;
removeToast(id: string): void;
clear(position?: ToastPosition): void;
getToasts(): ToastInstance[];
count(): number;
hasToasts(): boolean;
getToast(id: string): ToastInstance | null;
closeAll(): void;
clearAll(): void;
pauseAll(): void;
resumeAll(): void;
updateAll(partial: Partial<ToastOptions>): void;
findToasts(predicate: (toast: ToastInstance) => boolean): ToastInstance[];
findByType(type: ToastType): ToastInstance[];
findByPosition(position: ToastPosition): ToastInstance[];
getAll(): Map<string, ToastInstance>;
use(plugin: string | Plugin, options?: Record<string, unknown>): MeToast;
};
export { ActionButton, ActionControl, AnimationConfig, AnimationUtils, ConfirmOptions, CountdownControl, CountdownOptions, ErrorInfo, GroupAPI, I18nUtils, InitOptions, LoadingControl, LocaleInfo, enhancedMeToast as MeToast, enhancedMeToast as Met, Plugin, PluginManager, PluginUtils, ProgressControl, ProgressOptions, PromiseOptions, PromptOptions, QueueControl, QueueOptions, StackOptions, StatusInfo, ThemeConfig, ThemePreview, ThemeUtils, Toast, ToastAnimation, ToastConfig, ToastInstance, ToastOptions, ToastPosition, ToastProgressDirection, ToastTheme, ToastType, TypeColor, VERSION, enhancedMeToast as default, enhancedMeToast as meToast };
Reference in New Issue View Git Blame Copy Permalink