diff --git a/site/docs.html b/site/docs.html index 92ec5a6..cd0757e 100644 --- a/site/docs.html +++ b/site/docs.html @@ -24,22 +24,21 @@ .sidebar a:hover, .sidebar a.active { color:var(--accent2); border-left-color:var(--accent); background:rgba(99,102,241,0.06); } .sidebar .section { font-size:11px; text-transform:uppercase; letter-spacing:1px; padding:16px 24px 6px; color:var(--muted); font-weight:600; } - .main { flex:1; padding:40px 48px; max-width:900px; } + .main { flex:1; padding:40px 48px; max-width:950px; } .main h1 { font-size:30px; font-weight:700; margin-bottom:8px; } - .main h2 { font-size:22px; font-weight:700; margin:40px 0 12px; padding-top:20px; border-top:1px solid var(--border); } - .main h3 { font-size:17px; font-weight:600; margin:24px 0 8px; color:var(--accent2); } + .main h2 { font-size:22px; font-weight:700; margin:44px 0 14px; padding-top:22px; border-top:1px solid var(--border); } + .main h3 { font-size:17px; font-weight:600; margin:28px 0 10px; color:var(--accent2); } .main p { margin:8px 0; color:var(--muted); font-size:14px; } - .main table { width:100%; border-collapse:collapse; margin:12px 0; font-size:13px; } - .main th, .main td { text-align:left; padding:8px 14px; border-bottom:1px solid var(--border); } + .main table { width:100%; border-collapse:collapse; margin:14px 0 20px; font-size:13px; } + .main th, .main td { text-align:left; padding:9px 14px; border-bottom:1px solid var(--border); vertical-align:top; } .main th { color:var(--muted); font-weight:500; font-size:11px; text-transform:uppercase; letter-spacing:0.5px; } .main td:first-child { color:var(--accent2); font-family:monospace; font-size:12px; white-space:nowrap; } - .tag { display:inline-block; padding:2px 8px; border-radius:4px; font-size:11px; font-weight:600; } - .tag-method { background:rgba(59,130,246,0.15); color:#60a5fa; } - .tag-config { background:rgba(16,185,129,0.15); color:#34d399; } - .tag-callback { background:rgba(139,92,246,0.15); color:#a78bfa; } + .main td:nth-child(3) { font-family:monospace; font-size:11px; color:var(--muted); } .badge { display:inline-block; padding:1px 7px; border-radius:3px; font-size:10px; font-weight:700; margin-left:6px; vertical-align:middle; } .badge-new { background:rgba(16,185,129,0.2); color:#34d399; } - .badge-v2 { background:rgba(99,102,241,0.2); color:#818cf8; } + .hint { font-size:12px; color:var(--muted); margin-top:2px; } + .return-box { background:rgba(16,185,129,0.08); border:1px solid rgba(16,185,129,0.2); border-radius:8px; padding:14px 18px; margin:12px 0; } + .return-box h4 { font-size:12px; color:#34d399; margin-bottom:6px; text-transform:uppercase; letter-spacing:0.5px; } @media (max-width:768px) { body { flex-direction:column; } @@ -74,6 +73,7 @@
管理方法
group() NEW dismiss() + clear() configure() use() destroy() @@ -87,159 +87,303 @@

API 文档

-

MetonaToast v2.0.0 完整 API 参考。所有方法均支持链式调用和配置覆盖。

+

MetonaToast v2.0.0 完整 API 参考。所有基础通知方法（show/success/error/warning/info/loading）支持两种调用形式，均可传入任何 配置项 作为可选第二参数。

show(message, opts?)

-

显示默认类型的 Toast 通知。

-
// 字符串
+
显示默认类型的 Toast 通知，无特定颜色和图标。

+
+
+
+
+
参数类型默认值说明
messagestring | object—消息字符串，或包含 title/message 等属性的配置对象
optsobject{}可选配置对象，覆盖 全部配置项。仅当 message 为字符串时有效

+
// 字符串形式
 MeToast.show('默认消息');
-
-// 带配置
 MeToast.show('自定义', { duration: 2000, position: 'bottom-center' });
-
-// 对象形式
-MeToast.show({ title: '标题', message: '内容' });

+// 对象形式（所有 opts 作为一级属性）
+MeToast.show({ title: '标题', message: '内容', duration: 3000 });

success(message, opts?)

-

显示成功通知。绿色对勾图标。

+

显示成功通知。绿色对勾图标 #10b981，type = success。

+ + + + +
参数类型默认值说明
messagestring | object—消息字符串或配置对象
optsobject{}可选配置覆盖。type 固定为 success
MeToast.success('保存成功！');
-MeToast.success({ title: '已保存', message: '文件已同步到云端' });
+MeToast.success({ title: '已保存', message: '数据已同步' }); +Met.success('MeToast和Met等价');

error(message, opts?)

-

显示错误通知。红色叉号图标。

-
MeToast.error('网络错误，请重试');
+

显示错误通知。红色叉号图标 #ef4444，type = error。aria-live 设为 assertive。

+ + + + +
参数类型默认值说明
messagestring | object—消息字符串或配置对象
optsobject{}可选配置覆盖。type 固定为 error
+
MeToast.error('网络错误，请重试');
+MeToast.error({ title: '提交失败', message: '服务器不可达' });

warning(message, opts?)

-

显示警告通知。黄色三角图标。

+

显示警告通知。黄色三角图标 #f59e0b，type = warning。

+ + + + +
参数类型默认值说明
messagestring | object—消息字符串或配置对象
optsobject{}可选配置覆盖。type 固定为 warning
MeToast.warning('请注意检查输入内容');

info(message, opts?)

-

显示信息通知。蓝色圆形图标。

-
MeToast.info('系统将于 22:00 进行维护');
+

显示信息通知。蓝色圆形图标 #3b82f6，type = info。

+ + + + +
参数类型默认值说明
messagestring | object—消息字符串或配置对象
optsobject{}可选配置覆盖。type 固定为 info
+
MeToast.info('系统将于 22:00 维护');

loading(message, opts?)

-

显示加载状态。返回一个控制对象，支持链式转换为 success/error/info/warning。

+

显示加载状态。type = loading，duration 强制为 0（不自动关闭），closeButton 和 showProgress 强制为 false。返回 LoadingControl 对象。

+ + + + +
参数类型默认值说明
messagestring | object—加载提示文本或配置对象
optsobject{}可选配置覆盖
const loading = MeToast.loading('正在提交...');
-setTimeout(() => loading.success('提交成功！'), 2000);
-
-// 返回对象方法
-loading.success(msg, opts?)   // 转为成功
-loading.error(msg, opts?)     // 转为错误
-loading.info(msg, opts?)      // 转为信息
-loading.warning(msg, opts?)   // 转为警告
-loading.update(partial)         // 原地更新
-loading.dismiss()                // 关闭
+setTimeout(() => loading.success('提交成功！'), 2000); +
+

返回 LoadingControl

+ + + + + + + + +
方法签名说明
success(msg, opts?) => ToastInstance关闭加载 toast，原地替换为 success 类型
error(msg, opts?) => ToastInstance替换为 error 类型
info(msg, opts?) => ToastInstance替换为 info 类型
warning(msg, opts?) => ToastInstance替换为 warning 类型
update(partial) => MeToast不关闭加载 toast，原地更新其内容（支持 resetTimerOnUpdate）
dismiss()直接关闭加载 toast 不替换
+

promise(promise, opts)

-

自动根据 Promise 状态切换 Toast。显示 loading → 自动 success/error。

-
await MeToast.promise(
-  fetch('/api/data'),
-  {
+
监听 Promise 生命周期。自动显示 loading → 根据 resolve/reject 自动切换 success/error。返回原 Promise，支持 await 获取结果。

+
+
+
+
+
+
+
参数类型默认值说明
promisePromise—要监听的 Promise 对象。非 Promise 会打印错误并返回 rejected Promise
opts.loadingstring"加载中..."加载中显示的文本
opts.successstring"操作成功"resolve 后显示的文本
opts.errorstring"操作失败"reject 后显示的文本

+
try {
+  await MeToast.promise(fetch('/api/data'), {
     loading: '加载中...',
     success: '加载完成！',
     error: '加载失败',
-  }
-);

-
-
-
-
-
-
-
参数类型说明
promisePromise要监听的 Promise 对象
opts.loadingstring加载中文本
opts.successstring成功时文本
opts.errorstring失败时文本

+  });
+} catch (e) { /* promise reject 会继续抛出 */ }

confirm(message, opts?)

-

确认对话框。返回 Promise<boolean>，用户点击确认返回 true。

-
const ok = await MeToast.confirm('确定删除吗？', {
+
确认对话框。返回 Promise<boolean>。内置 10 秒安全超时，超时自动 resolve(false)。

+
+
+
+
+
+
+
+
+
参数类型默认值说明
messagestring—对话框消息。非字符串会打印错误并 resolve(false)
opts.confirmTextstring"确认"确认按钮文字
opts.confirmColorstring"#10b981"确认按钮背景色
opts.cancelTextstring"取消"取消按钮文字
opts.cancelColorstring"#6b7280"取消按钮背景色
opts.typestring"warning"Toast 类型（影响图标和颜色）

+
const ok = await MeToast.confirm('确定删除？', {
   confirmText: '删除',
   confirmColor: '#ef4444',
-  cancelText: '取消',
+  cancelText: '保留',
 });
 if (ok) MeToast.success('已删除');

 
 
prompt(message, opts?)

-
输入对话框。返回 Promise<string|null>，用户取消返回 null。

+
输入对话框。返回 Promise<string|null>。按 Enter 或点击提交按钮返回输入值，取消返回 null。内置 10 秒安全超时。

+
+
+
+
+
+
+
+
+
+
+
+
参数类型默认值说明
messagestring—对话框消息。非字符串会打印错误并 resolve(null)
opts.placeholderstring""输入框占位文字
opts.defaultValuestring""输入框默认值
opts.inputTypestring"text"input 标签 type 属性（如 password/email/number）
opts.submitTextstring"确认"提交按钮文字
opts.submitColorstring"#3b82f6"提交按钮背景色
opts.cancelTextstring"取消"取消按钮文字
opts.cancelColorstring"#6b7280"取消按钮背景色
opts.typestring"info"Toast 类型

 
const name = await MeToast.prompt('请输入姓名', {
   placeholder: '请输入...',
   defaultValue: '张三',
+  submitText: '确定',
 });
-if (name) MeToast.info('你好，' + name + '！');

+if (name) MeToast.info('你好，' + name);

progress(message, opts?)

-

进度条通知。返回控制对象，可调用 setProgress / complete / error。

-
const p = MeToast.progress('上传中...');
-p.setProgress(30);
-p.setProgress(70);
-p.complete('上传完成！');
+
进度条通知。不自动关闭。返回 ProgressControl 对象以手动更新进度。

+
+
+
+
+
+
参数类型默认值说明
messagestring | object—进度提示文本或配置对象
optsobject{}可选配置。type 默认 info
opts.progressColorstring"#3b82f6"进度条填充颜色

+
const p = MeToast.progress('上传中...', { progressColor: '#10b981' });
+p.setProgress(45); // → 45%
+p.setProgress(90); // → 90%
+p.complete('上传完成！'); // → 100% → success
 // 或
 p.error('上传失败');
 p.dismiss();

+

+
返回 ProgressControl

+
+
+
+
+
+
+
方法签名说明
setProgress(percent: number)设置进度 0~100，自动 clamp。更新进度条宽度和百分比文字
complete(message?: string)跳到 100%，300ms 后替换为 success toast，1s 后自动关闭
error(message?: string)替换为 error toast，2s 后自动关闭
dismiss()直接关闭

+

 
 
countdown(message, seconds, opts?)

-
倒计时 Toast。{seconds} 占位符自动替换为剩余秒数。

-
MeToast.countdown('操作将在 {seconds} 秒后执行', 5, {
+
倒计时 Toast。{seconds} 占位符每秒自动替换为剩余秒数。

+
+
+
+
+
+
+
参数类型默认值说明
messagestring—消息文本。支持 {seconds} 占位符。非字符串打印错误并返回空控制对象
secondsnumber10倒计时秒数，最小 1
opts.onCompletefunction—倒计时归零时的回调
opts.typestring"warning"Toast 类型

+
MeToast.countdown('{seconds} 秒后执行', 5, {
   onComplete: () => MeToast.success('已执行'),
-});
-
-// 返回控制对象
-const c = MeToast.countdown('{seconds}s', 10);
-c.cancel();  // 取消并关闭
-c.pause();   // 暂停
-c.resume();  // 恢复

+});

+

+
返回 CountdownControl

+
+
+
+
+
+
方法说明
cancel()清除计时器并关闭 toast
pause()暂停倒计时
resume()恢复倒计时

+

 
 
queue(messages, opts?)

-
队列展示：顺序逐个显示消息。返回可取消的 thenable 对象。

-
const q = MeToast.queue(['步骤一', '步骤二', '步骤三'], {
-  delay: 800,
-  duration: 2000,
-  type: 'info',
-});
-q.cancel(); // 取消队列
-await q;  // 等待队列完成

+
顺序逐个显示消息队列。前一条关闭后延时显示下一条。返回 QueueControl（thenable + cancel）。

+
+
+
+
+
+
+
+
参数类型默认值说明
messagesArray<string|object>—消息数组。可为字符串或带 message/type/duration/onClose 的对象。非数组打印错误并返回空控制对象
opts.delaynumber1000每条消息关闭后到显示下一条的间隔(ms)
opts.durationnumber3000每条消息显示时长(ms)，可被消息级 duration 覆盖
opts.onClosefunction—全部队列完成后的回调。消息级 onClose 和队列级 onClose 都会依次调用
opts.typestring—默认类型

+
const q = MeToast.queue([
+  '步骤一',
+  { message: '步骤二', duration: 5000, type: 'warning' },
+  '步骤三',
+], { delay: 800, duration: 2000, type: 'info' });
+q.cancel(); // 中途取消
+await q;  // 等待完成（thenable 支持 await）

+

+
返回 QueueControl (thenable)

+
+
+
+
+
+
方法说明
.then(fn, rj)Promise.then 代理，支持 await
.catch(rj)Promise.catch 代理
.cancel()设置取消标志，不再显示下一条消息

+

 
 
stack(messages, opts?)

-
堆叠展示：同时错峰显示多条消息。

-
MeToast.stack(['消息1', '消息2', '消息3', '消息4'], {
+
同时错峰显示多条消息。每条间隔 stagger 毫秒依次出现，全部叠加在屏幕上。

+
+
+
+
+
+
参数类型默认值说明
messagesArray<string|object>—消息数组。可为字符串或带 message/type/duration 的对象。非数组打印错误
opts.staggernumber100每条消息之间的显示间隔(ms)
opts.typestring—默认类型

+
MeToast.stack(['消息1', '消息2', { message: '警告', type: 'warning' }], {
   stagger: 150,
   type: 'info',
 });

 
 
action(message, actions, opts?) v2.0

-
Action Toast：内嵌操作按钮的通知。类似 Android Snackbar。

+
Action Toast：内嵌操作按钮。默认 duration=0 不自动关闭，closeButton=true。

+
+
+
+
+
+
参数类型默认值说明
messagestring | object—消息字符串或配置对象
actionsActionButton[][]按钮数组。每个按钮可配 text/onClick/color/style/close
optsobject{}可选配置。duration 默认 0，closeButton 默认 true

+
+
+
+
+
+
+
+
ActionButton 字段类型默认值说明
textstring—（必填）按钮显示文字
onClick(toast) => void—（必填）点击回调函数，参数为当前 toast 实例
colorstring"#6366f1"按钮背景色
styleobject{}按钮内联样式，可覆盖 color（style.background 优先）
closebooleantrue点击后是否自动关闭 toast。设为 false 可多次点击

 
MeToast.action('文件已删除', [
   { text: '撤销', onClick: () => restore(), color: '#3b82f6' },
-  { text: '查看', onClick: () => openFile() },
+  { text: '查看详情', onClick: (t) => openFile(), color: '#10b981', close: false },
 ]);

-
-
-
-
-
-
-
按钮字段类型说明
textstring按钮文本
onClickfunction点击回调，参数为 toast 实例
colorstring按钮背景色，默认 #6366f1
closeboolean点击后是否关闭 toast，默认 true

 
 
 
group(name) v2.0

-
创建 Toast 分组。返回一个自动添加 group 参数的子对象，支持按组管理。

+
创建 Toast 分组，返回 GroupAPI 对象。该对象所有方法自动传入 group: name，按组管理。

+
+
+
+
参数类型说明
namestring分组名称。GroupAPI 和 dismissGroup 通过此名称关联

 
const orders = MeToast.group('orders');
 orders.success('订单已创建');
-orders.error('支付失败');
-orders.count();   // 该组的 toast 数量
-orders.dismiss(); // 关闭整组
-
-// 也可通过主对象关闭
+orders.error('支付失败', { duration: 5000 });
+orders.count();   // 该组当前 toast 数量
+orders.dismiss(); // 关闭该组全部 toast
+// 也支持主对象关闭
 MeToast.dismissGroup('orders');

+

+
返回 GroupAPI

+
+
+
+
+
+
+
+
+
+
+
+
方法说明
show(msg, opts?)等价 MeToast.show，自动注入 group
success(msg, opts?)等价 MeToast.success
error(msg, opts?)等价 MeToast.error
warning(msg, opts?)等价 MeToast.warning
info(msg, opts?)等价 MeToast.info
loading(msg, opts?)等价 MeToast.loading
action(msg, actions, opts?)等价 MeToast.action
dismiss()关闭该组所有 toast
count()返回该组当前 toast 数量

+

 
 
dismiss(id?)

-
关闭 Toast。无参数关闭所有，传 id 关闭指定。

-
MeToast.dismiss();       // 关闭所有
-MeToast.dismiss(toastId); // 关闭指定

-
其他管理方法：count() getToasts() pauseAll() resumeAll() destroy() clear()

+
关闭 Toast。无参数则关闭全部。

+
+
+
+
参数类型说明
idstring可选。Toast 的 id，不传则关闭所有

+
MeToast.dismiss();          // 关闭所有
+MeToast.dismiss(toast.id);  // 关闭指定

+
+
clear(position?)

+
按位置清除 Toast。不传参数清除所有位置。

+
+
+
+
参数类型说明
positionstring可选。位置如 'top-right'，不传则清除全部

+
MeToast.clear();                      // 全部
+MeToast.clear('bottom-right'); // 仅右下角

 
 
configure(opts)

-
全局配置。影响后续所有 Toast。

+
全局配置，影响后续所有 Toast。theme 和 locale 变化会触发相应副作用（应用主题 CSS / 切换语言）。

+
+
+
+
参数类型说明
optsobject包含任意 配置项 的对象

 
MeToast.configure({
   position: 'top-right',
   duration: 4000,
@@ -249,66 +393,64 @@ MeToast.dismiss(toastId); // 关闭指
 });

 
 
use(plugin)

-
安装插件。支持字符串（预设）和对象（自定义）。

+
安装插件。支持字符串（内置预设名）或插件对象。已被拒绝注册的无效插件会打印错误。

+
+
+
+
参数类型说明
pluginstring | object预设名 'keyboard'/'persistence'/'accessibility' 或自定义插件对象 { name, version?, install, uninstall? }

 
MeToast.use('keyboard');      // ESC 关闭所有 Toast
-MeToast.use('persistence');   // 配置持久化到 localStorage
-MeToast.use('accessibility'); // 屏幕阅读器朗读
-
-// 自定义插件
-MeToast.use({
-  name: 'my-plugin',
-  install() {
-    Toast.on('afterShow', (t) => console.log(t.message));
-  },
-});

+MeToast.use('persistence');   // 配置自动保存到 localStorage
+MeToast.use('accessibility'); // 屏幕阅读器实时朗读 toast 内容

+
内置插件详情：keyboard 监听 keydown Escape 键；persistence 将配置写入 localStorage 并在页面加载时恢复；accessibility 在 afterShow/afterUpdate 钩子中通过 aria-live 区域朗读 toast 内容。

 
 
destroy()

-
完全销毁：关闭所有 Toast、移除 DOM 容器和样式标签。

+
完全销毁。关闭所有 Toast、移除所有 DOM 容器和注入的样式标签、清空内存缓存。

 
MeToast.destroy();

 
 
 
全部配置项

-
以下配置可用于 configure() 或单个 Toast 的第二个参数。

+
以下配置可用于 configure()、init() 或单个 Toast 方法的 opts 参数。带 v2.0 标识的为 v2.0 新增。

 
-
+
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

 
配置项类型默认值说明
positionstring'top-right'位置：top-left/center/right、bottom-left/center/right
positionstring'top-right'位置：top-left / top-center / top-right / bottom-left / bottom-center / bottom-right

 
durationnumber4000显示时长(ms)，0=不自动关闭
maxnumber6同时最多显示条数
maxnumber6同一位置最多同时显示条数，超出则关闭最早的

 
gapnumber12Toast 之间的间距(px)
offsetnumber24容器边距(px)
pauseOnHoverbooleantrue悬停时暂停计时
closeOnClickbooleantrue点击 Toast 关闭
draggablebooleantrue允许拖拽关闭
showProgressbooleantrue显示进度条
progressDirectionstring'horizontal'进度条方向：horizontal / vertical
iconbooleantrue显示类型图标
closeButtonbooleantrue显示关闭按钮
themestring'auto'主题：light / dark / auto / warm
animationstring'slide'动画效果（见下方列表）
zIndexnumber9999CSS z-index
widthnumber/string360Toast 宽度(px)
classNamestring''附加 CSS 类名
styleobject{}内联样式对象
localestring'zh-CN'语言代码
resetTimerOnUpdatebooleanfalseupdate()时重置计时器 v2.0
notifyWhenHiddenbooleanfalse页面不可见时发系统通知 v2.0
renderfunction—自定义渲染函数 v2.0
offsetnumber24容器到屏幕边缘的距离(px)
pauseOnHoverbooleantrue鼠标悬停时暂停 duration 倒计时和进度条
closeOnClickbooleantrue点击 Toast 任意位置关闭。关闭按钮始终触发关闭
draggablebooleantrue允许拖拽关闭。拖拽超过 120px 触发关闭
showProgressbooleantrue显示 duration 倒计时进度条
progressDirectionstring'horizontal'进度条方向：horizontal(底部水平) / vertical(右侧垂直)
iconbooleantrue显示类型对应图标（success→对勾等）
closeButtonbooleantrue显示右上角关闭 × 按钮
themestring'auto'主题：light / dark / auto（跟随系统）/ warm / 自定义注册名
animationstring'slide'入场动画名称，支持 CSS 动画列表见下
zIndexnumber9999容器 CSS z-index
widthnumber|string360Toast 宽度。数字表示 px
classNamestring''附加到 Toast 元素上的 CSS 类名
styleobject{}附加到 Toast 元素上的内联样式对象
localestring'zh-CN'语言代码（zh-CN / en-US 等）
resetTimerOnUpdate v2.0booleanfalse调用 update() 时重置 duration 倒计时
notifyWhenHidden v2.0booleanfalse页面不可见时自动通过 Notification API 发送系统通知
render v2.0function—自定义渲染函数 (toast) => htmlString，完全接管 DOM 构建

 

 
 
回调函数

 
-
-
-
-
+
+
+
+

 
回调签名触发时机
onShow(toast) => voidToast 显示后
onClose(toast) => voidToast 关闭后
onClick(toast) => voidToast 被点击时
onUpdate(toast) => voidToast 内容更新后 v2.0
onShow(toast: ToastInstance) => voidToast DOM 创建并播放入场动画后
onClose(toast: ToastInstance) => voidToast DOM 被移除后（离场动画完成时）
onClick(toast: ToastInstance) => voidToast 被点击时（closeOnClick 为 true 时还会自动关闭）
onUpdate v2.0(toast: ToastInstance) => voidToast 内容通过 update() 更新后

 

 
 
动画列表

+
配置 animation 的值，支持以下 CSS 动画。未在此列表中的值将 fallback 到 slide。

 
-
+
@@ -324,7 +466,7 @@ MeToast.use({
 
// 内置主题
 light   — 白色玻璃质感
 dark    — 深色玻璃质感
-auto    — 跟随系统
+auto    — 跟随系统主题设置
 warm    — 暖色调
 
 // 注册自定义主题
@@ -344,7 +486,6 @@ MeToast.themes.switchTheme('ocean'
 
 
-
+
\ No newline at end of file


 
名称效果时长

 
slide从右侧滑入 + 回弹400ms
fade纯淡入 (blur→清晰)500ms
fade纯淡入 + blur→清晰500ms

 
scale弹性放大 (0.55→1.07→1)450ms

 
bounce从天而降四段弹跳650ms

 
flip3D 翻转入场 + 回摆500ms