497 lines
33 KiB
HTML
497 lines
33 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<link rel="icon" type="image/x-icon" href="favicon.ico">
|
||
<title>API 文档 — MetonaToast</title>
|
||
<style>
|
||
:root {
|
||
--bg: #0b1121; --surface: #1a2332; --border: #1e2d4d;
|
||
--text: #e2e8f0; --muted: #64748b; --accent: #6366f1; --accent2: #818cf8;
|
||
--radius: 10px;
|
||
}
|
||
* { margin:0; padding:0; box-sizing:border-box; }
|
||
body { font-family:-apple-system,BlinkMacSystemFont,'Segoe UI','PingFang SC','Microsoft YaHei',sans-serif; background:var(--bg); color:var(--text); line-height:1.7; display:flex; min-height:100vh; }
|
||
code { background:rgba(99,102,241,0.12); color:#a5b4fc; padding:1px 6px; border-radius:4px; font-size:0.9em; white-space:nowrap; }
|
||
pre { background:#0a0f1a; border:1px solid var(--border); border-radius:8px; padding:14px 18px; overflow-x:auto; font:13px/1.7 'SF Mono','Cascadia Code','Fira Code',Consolas,monospace; color:#cbd5e1; margin:10px 0; }
|
||
pre .kw { color:#c084fc; } pre .fn { color:#60a5fa; } pre .s { color:#34d399; } pre .cm { color:#475569; }
|
||
a { color:var(--accent2); text-decoration:none; }
|
||
|
||
.sidebar { width:260px; min-width:260px; background:var(--surface); border-right:1px solid var(--border); padding:24px 0; position:sticky; top:0; height:100vh; overflow-y:auto; }
|
||
.sidebar h2 { font-size:15px; padding:0 24px; margin-bottom:16px; color:var(--accent2); }
|
||
.sidebar a { display:block; padding:7px 24px; font-size:13px; color:var(--muted); transition:.15s; border-left:2px solid transparent; }
|
||
.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:950px; }
|
||
.main h1 { font-size:30px; font-weight:700; margin-bottom:8px; }
|
||
.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: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; }
|
||
.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; }
|
||
.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; }
|
||
.sidebar { width:100%; min-width:0; height:auto; position:static; border-right:none; border-bottom:1px solid var(--border); padding:12px 16px; }
|
||
.sidebar a { display:inline-block; padding:4px 10px; border-left:none; }
|
||
.main { padding:24px 20px; }
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<nav class="sidebar">
|
||
<h2>📘 MetonaToast 文档</h2>
|
||
<a href="index.html">← 返回首页</a>
|
||
<a href="demo.html">🎮 在线演示</a>
|
||
<div class="section">基础通知</div>
|
||
<a href="#show">show()</a>
|
||
<a href="#success">success()</a>
|
||
<a href="#error">error()</a>
|
||
<a href="#warning">warning()</a>
|
||
<a href="#info">info()</a>
|
||
<a href="#loading">loading()</a>
|
||
<div class="section">高级功能</div>
|
||
<a href="#promise">promise()</a>
|
||
<a href="#confirm">confirm()</a>
|
||
<a href="#prompt">prompt()</a>
|
||
<a href="#progress">progress()</a>
|
||
<a href="#countdown">countdown()</a>
|
||
<a href="#queue">queue()</a>
|
||
<a href="#stack">stack()</a>
|
||
<a href="#action">action() <span class="badge badge-new">NEW</span></a>
|
||
<div class="section">管理方法</div>
|
||
<a href="#group">group() <span class="badge badge-new">NEW</span></a>
|
||
<a href="#dismiss">dismiss()</a>
|
||
<a href="#clear">clear()</a>
|
||
<a href="#configure">configure()</a>
|
||
<a href="#use">use()</a>
|
||
<a href="#destroy">destroy()</a>
|
||
<div class="section">配置参考</div>
|
||
<a href="#config">全部配置项</a>
|
||
<a href="#callbacks">回调函数</a>
|
||
<a href="#animations">动画列表</a>
|
||
<a href="#themes">主题参考</a>
|
||
</nav>
|
||
|
||
<main class="main">
|
||
|
||
<h1>API 文档</h1>
|
||
<p>MetonaToast v2.0.0 完整 API 参考。所有基础通知方法（show/success/error/warning/info/loading）支持两种调用形式，均可传入任何 <a href="#config">配置项</a> 作为可选第二参数。</p>
|
||
|
||
<!-- ===== 基础通知 ===== -->
|
||
<h2 id="show">show(message, opts?)</h2>
|
||
<p>显示默认类型的 Toast 通知，无特定颜色和图标。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>消息字符串，或包含 title/message 等属性的配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置对象，覆盖 <a href="#config">全部配置项</a>。仅当 message 为字符串时有效</td></tr>
|
||
</table>
|
||
<pre><span class="cm">// 字符串形式</span>
|
||
MeToast.<span class="fn">show</span>(<span class="s">'默认消息'</span>);
|
||
MeToast.<span class="fn">show</span>(<span class="s">'自定义'</span>, { <span class="fn">duration</span>: 2000, <span class="fn">position</span>: <span class="s">'bottom-center'</span> });
|
||
<span class="cm">// 对象形式（所有 opts 作为一级属性）</span>
|
||
MeToast.<span class="fn">show</span>({ <span class="fn">title</span>: <span class="s">'标题'</span>, <span class="fn">message</span>: <span class="s">'内容'</span>, <span class="fn">duration</span>: 3000 });</pre>
|
||
|
||
<h2 id="success">success(message, opts?)</h2>
|
||
<p>显示成功通知。绿色对勾图标 <code>#10b981</code>，type = success。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>消息字符串或配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置覆盖。type 固定为 success</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">success</span>(<span class="s">'保存成功！'</span>);
|
||
MeToast.<span class="fn">success</span>({ <span class="fn">title</span>: <span class="s">'已保存'</span>, <span class="fn">message</span>: <span class="s">'数据已同步'</span> });
|
||
Met.<span class="fn">success</span>(<span class="s">'MeToast和Met等价'</span>);</pre>
|
||
|
||
<h2 id="error">error(message, opts?)</h2>
|
||
<p>显示错误通知。红色叉号图标 <code>#ef4444</code>，type = error。aria-live 设为 assertive。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>消息字符串或配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置覆盖。type 固定为 error</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">error</span>(<span class="s">'网络错误，请重试'</span>);
|
||
MeToast.<span class="fn">error</span>({ <span class="fn">title</span>: <span class="s">'提交失败'</span>, <span class="fn">message</span>: <span class="s">'服务器不可达'</span> });</pre>
|
||
|
||
<h2 id="warning">warning(message, opts?)</h2>
|
||
<p>显示警告通知。黄色三角图标 <code>#f59e0b</code>，type = warning。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>消息字符串或配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置覆盖。type 固定为 warning</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">warning</span>(<span class="s">'请注意检查输入内容'</span>);</pre>
|
||
|
||
<h2 id="info">info(message, opts?)</h2>
|
||
<p>显示信息通知。蓝色圆形图标 <code>#3b82f6</code>，type = info。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>消息字符串或配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置覆盖。type 固定为 info</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">info</span>(<span class="s">'系统将于 22:00 维护'</span>);</pre>
|
||
|
||
<h2 id="loading">loading(message, opts?)</h2>
|
||
<p>显示加载状态。type = loading，duration 强制为 0（不自动关闭），closeButton 和 showProgress 强制为 false。返回 LoadingControl 对象。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>加载提示文本或配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置覆盖</td></tr>
|
||
</table>
|
||
<pre><span class="kw">const</span> loading = MeToast.<span class="fn">loading</span>(<span class="s">'正在提交...'</span>);
|
||
<span class="fn">setTimeout</span>(() => loading.<span class="fn">success</span>(<span class="s">'提交成功！'</span>), 2000);</pre>
|
||
<div class="return-box">
|
||
<h4>返回 LoadingControl</h4>
|
||
<table>
|
||
<tr><th>方法</th><th>签名</th><th>说明</th></tr>
|
||
<tr><td>success</td><td>(msg, opts?) => ToastInstance</td><td>关闭加载 toast，原地替换为 success 类型</td></tr>
|
||
<tr><td>error</td><td>(msg, opts?) => ToastInstance</td><td>替换为 error 类型</td></tr>
|
||
<tr><td>info</td><td>(msg, opts?) => ToastInstance</td><td>替换为 info 类型</td></tr>
|
||
<tr><td>warning</td><td>(msg, opts?) => ToastInstance</td><td>替换为 warning 类型</td></tr>
|
||
<tr><td>update</td><td>(partial) => MeToast</td><td>不关闭加载 toast，原地更新其内容（支持 resetTimerOnUpdate）</td></tr>
|
||
<tr><td>dismiss</td><td>()</td><td>直接关闭加载 toast 不替换</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<!-- ===== 高级功能 ===== -->
|
||
<h2 id="promise">promise(promise, opts)</h2>
|
||
<p>监听 Promise 生命周期。自动显示 loading → 根据 resolve/reject 自动切换 success/error。返回原 Promise，支持 await 获取结果。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>promise</td><td>Promise</td><td>—</td><td>要监听的 Promise 对象。非 Promise 会打印错误并返回 rejected Promise</td></tr>
|
||
<tr><td>opts.loading</td><td>string</td><td>"加载中..."</td><td>加载中显示的文本</td></tr>
|
||
<tr><td>opts.success</td><td>string</td><td>"操作成功"</td><td>resolve 后显示的文本</td></tr>
|
||
<tr><td>opts.error</td><td>string</td><td>"操作失败"</td><td>reject 后显示的文本</td></tr>
|
||
</table>
|
||
<pre><span class="kw">try</span> {
|
||
<span class="kw">await</span> MeToast.<span class="fn">promise</span>(<span class="fn">fetch</span>(<span class="s">'/api/data'</span>), {
|
||
<span class="fn">loading</span>: <span class="s">'加载中...'</span>,
|
||
<span class="fn">success</span>: <span class="s">'加载完成！'</span>,
|
||
<span class="fn">error</span>: <span class="s">'加载失败'</span>,
|
||
});
|
||
} <span class="kw">catch</span> (<span class="fn">e</span>) { <span class="cm">/* promise reject 会继续抛出 */</span> }</pre>
|
||
|
||
<h2 id="confirm">confirm(message, opts?)</h2>
|
||
<p>确认对话框。返回 <code>Promise<boolean></code>。内置 10 秒安全超时，超时自动 resolve(false)。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string</td><td>—</td><td>对话框消息。非字符串会打印错误并 resolve(false)</td></tr>
|
||
<tr><td>opts.confirmText</td><td>string</td><td>"确认"</td><td>确认按钮文字</td></tr>
|
||
<tr><td>opts.confirmColor</td><td>string</td><td>"#10b981"</td><td>确认按钮背景色</td></tr>
|
||
<tr><td>opts.cancelText</td><td>string</td><td>"取消"</td><td>取消按钮文字</td></tr>
|
||
<tr><td>opts.cancelColor</td><td>string</td><td>"#6b7280"</td><td>取消按钮背景色</td></tr>
|
||
<tr><td>opts.type</td><td>string</td><td>"warning"</td><td>Toast 类型（影响图标和颜色）</td></tr>
|
||
</table>
|
||
<pre><span class="kw">const</span> ok = <span class="kw">await</span> MeToast.<span class="fn">confirm</span>(<span class="s">'确定删除？'</span>, {
|
||
<span class="fn">confirmText</span>: <span class="s">'删除'</span>,
|
||
<span class="fn">confirmColor</span>: <span class="s">'#ef4444'</span>,
|
||
<span class="fn">cancelText</span>: <span class="s">'保留'</span>,
|
||
});
|
||
<span class="kw">if</span> (ok) MeToast.<span class="fn">success</span>(<span class="s">'已删除'</span>);</pre>
|
||
|
||
<h2 id="prompt">prompt(message, opts?)</h2>
|
||
<p>输入对话框。返回 <code>Promise<string|null></code>。按 Enter 或点击提交按钮返回输入值，取消返回 null。内置 10 秒安全超时。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string</td><td>—</td><td>对话框消息。非字符串会打印错误并 resolve(null)</td></tr>
|
||
<tr><td>opts.placeholder</td><td>string</td><td>""</td><td>输入框占位文字</td></tr>
|
||
<tr><td>opts.defaultValue</td><td>string</td><td>""</td><td>输入框默认值</td></tr>
|
||
<tr><td>opts.inputType</td><td>string</td><td>"text"</td><td>input 标签 type 属性（如 password/email/number）</td></tr>
|
||
<tr><td>opts.submitText</td><td>string</td><td>"确认"</td><td>提交按钮文字</td></tr>
|
||
<tr><td>opts.submitColor</td><td>string</td><td>"#3b82f6"</td><td>提交按钮背景色</td></tr>
|
||
<tr><td>opts.cancelText</td><td>string</td><td>"取消"</td><td>取消按钮文字</td></tr>
|
||
<tr><td>opts.cancelColor</td><td>string</td><td>"#6b7280"</td><td>取消按钮背景色</td></tr>
|
||
<tr><td>opts.type</td><td>string</td><td>"info"</td><td>Toast 类型</td></tr>
|
||
</table>
|
||
<pre><span class="kw">const</span> name = <span class="kw">await</span> MeToast.<span class="fn">prompt</span>(<span class="s">'请输入姓名'</span>, {
|
||
<span class="fn">placeholder</span>: <span class="s">'请输入...'</span>,
|
||
<span class="fn">defaultValue</span>: <span class="s">'张三'</span>,
|
||
<span class="fn">submitText</span>: <span class="s">'确定'</span>,
|
||
});
|
||
<span class="kw">if</span> (name) MeToast.<span class="fn">info</span>(<span class="s">'你好，'</span> + name);</pre>
|
||
|
||
<h2 id="progress">progress(message, opts?)</h2>
|
||
<p>进度条通知。不自动关闭。返回 ProgressControl 对象以手动更新进度。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>进度提示文本或配置对象</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置。type 默认 info</td></tr>
|
||
<tr><td>opts.progressColor</td><td>string</td><td>"#3b82f6"</td><td>进度条填充颜色</td></tr>
|
||
</table>
|
||
<pre><span class="kw">const</span> p = MeToast.<span class="fn">progress</span>(<span class="s">'上传中...'</span>, { <span class="fn">progressColor</span>: <span class="s">'#10b981'</span> });
|
||
p.<span class="fn">setProgress</span>(45); <span class="cm">// → 45%</span>
|
||
p.<span class="fn">setProgress</span>(90); <span class="cm">// → 90%</span>
|
||
p.<span class="fn">complete</span>(<span class="s">'上传完成！'</span>); <span class="cm">// → 100% → success</span>
|
||
<span class="cm">// 或</span>
|
||
p.<span class="fn">error</span>(<span class="s">'上传失败'</span>);
|
||
p.<span class="fn">dismiss</span>();</pre>
|
||
<div class="return-box">
|
||
<h4>返回 ProgressControl</h4>
|
||
<table>
|
||
<tr><th>方法</th><th>签名</th><th>说明</th></tr>
|
||
<tr><td>setProgress</td><td>(percent: number)</td><td>设置进度 0~100，自动 clamp。更新进度条宽度和百分比文字</td></tr>
|
||
<tr><td>complete</td><td>(message?: string)</td><td>跳到 100%，300ms 后替换为 success toast，1s 后自动关闭</td></tr>
|
||
<tr><td>error</td><td>(message?: string)</td><td>替换为 error toast，2s 后自动关闭</td></tr>
|
||
<tr><td>dismiss</td><td>()</td><td>直接关闭</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<h2 id="countdown">countdown(message, seconds, opts?)</h2>
|
||
<p>倒计时 Toast。<code>{seconds}</code> 占位符每秒自动替换为剩余秒数。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string</td><td>—</td><td>消息文本。支持 <code>{seconds}</code> 占位符。非字符串打印错误并返回空控制对象</td></tr>
|
||
<tr><td>seconds</td><td>number</td><td>10</td><td>倒计时秒数，最小 1</td></tr>
|
||
<tr><td>opts.onComplete</td><td>function</td><td>—</td><td>倒计时归零时的回调</td></tr>
|
||
<tr><td>opts.type</td><td>string</td><td>"warning"</td><td>Toast 类型</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">countdown</span>(<span class="s">'{seconds} 秒后执行'</span>, 5, {
|
||
<span class="fn">onComplete</span>: () => MeToast.<span class="fn">success</span>(<span class="s">'已执行'</span>),
|
||
});</pre>
|
||
<div class="return-box">
|
||
<h4>返回 CountdownControl</h4>
|
||
<table>
|
||
<tr><th>方法</th><th>说明</th></tr>
|
||
<tr><td>cancel()</td><td>清除计时器并关闭 toast</td></tr>
|
||
<tr><td>pause()</td><td>暂停倒计时</td></tr>
|
||
<tr><td>resume()</td><td>恢复倒计时</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<h2 id="queue">queue(messages, opts?)</h2>
|
||
<p>顺序逐个显示消息队列。前一条关闭后延时显示下一条。返回 QueueControl（thenable + cancel）。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>messages</td><td>Array<string|object></td><td>—</td><td>消息数组。可为字符串或带 message/type/duration/onClose 的对象。非数组打印错误并返回空控制对象</td></tr>
|
||
<tr><td>opts.delay</td><td>number</td><td>1000</td><td>每条消息关闭后到显示下一条的间隔(ms)</td></tr>
|
||
<tr><td>opts.duration</td><td>number</td><td>3000</td><td>每条消息显示时长(ms)，可被消息级 duration 覆盖</td></tr>
|
||
<tr><td>opts.onClose</td><td>function</td><td>—</td><td>全部队列完成后的回调。消息级 onClose 和队列级 onClose 都会依次调用</td></tr>
|
||
<tr><td>opts.type</td><td>string</td><td>—</td><td>默认类型</td></tr>
|
||
</table>
|
||
<pre><span class="kw">const</span> q = MeToast.<span class="fn">queue</span>([
|
||
<span class="s">'步骤一'</span>,
|
||
{ <span class="fn">message</span>: <span class="s">'步骤二'</span>, <span class="fn">duration</span>: 5000, <span class="fn">type</span>: <span class="s">'warning'</span> },
|
||
<span class="s">'步骤三'</span>,
|
||
], { <span class="fn">delay</span>: 800, <span class="fn">duration</span>: 2000, <span class="fn">type</span>: <span class="s">'info'</span> });
|
||
q.<span class="fn">cancel</span>(); <span class="cm">// 中途取消</span>
|
||
<span class="kw">await</span> q; <span class="cm">// 等待完成（thenable 支持 await）</span></pre>
|
||
<div class="return-box">
|
||
<h4>返回 QueueControl (thenable)</h4>
|
||
<table>
|
||
<tr><th>方法</th><th>说明</th></tr>
|
||
<tr><td>.then(fn, rj)</td><td>Promise.then 代理，支持 await</td></tr>
|
||
<tr><td>.catch(rj)</td><td>Promise.catch 代理</td></tr>
|
||
<tr><td>.cancel()</td><td>设置取消标志，不再显示下一条消息</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<h2 id="stack">stack(messages, opts?)</h2>
|
||
<p>同时错峰显示多条消息。每条间隔 stagger 毫秒依次出现，全部叠加在屏幕上。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>messages</td><td>Array<string|object></td><td>—</td><td>消息数组。可为字符串或带 message/type/duration 的对象。非数组打印错误</td></tr>
|
||
<tr><td>opts.stagger</td><td>number</td><td>100</td><td>每条消息之间的显示间隔(ms)</td></tr>
|
||
<tr><td>opts.type</td><td>string</td><td>—</td><td>默认类型</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">stack</span>([<span class="s">'消息1'</span>, <span class="s">'消息2'</span>, { <span class="fn">message</span>: <span class="s">'警告'</span>, <span class="fn">type</span>: <span class="s">'warning'</span> }], {
|
||
<span class="fn">stagger</span>: 150,
|
||
<span class="fn">type</span>: <span class="s">'info'</span>,
|
||
});</pre>
|
||
|
||
<h2 id="action">action(message, actions, opts?) <span class="badge badge-new">v2.0</span></h2>
|
||
<p>Action Toast：内嵌操作按钮。默认 duration=0 不自动关闭，closeButton=true。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>message</td><td>string | object</td><td>—</td><td>消息字符串或配置对象</td></tr>
|
||
<tr><td>actions</td><td>ActionButton[]</td><td>[]</td><td>按钮数组。每个按钮可配 text/onClick/color/style/close</td></tr>
|
||
<tr><td>opts</td><td>object</td><td>{}</td><td>可选配置。duration 默认 0，closeButton 默认 true</td></tr>
|
||
</table>
|
||
<table>
|
||
<tr><th>ActionButton 字段</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>text</td><td>string</td><td>—（必填）</td><td>按钮显示文字</td></tr>
|
||
<tr><td>onClick</td><td>(toast) => void</td><td>—（必填）</td><td>点击回调函数，参数为当前 toast 实例</td></tr>
|
||
<tr><td>color</td><td>string</td><td>"#6366f1"</td><td>按钮背景色</td></tr>
|
||
<tr><td>style</td><td>object</td><td>{}</td><td>按钮内联样式，可覆盖 color（style.background 优先）</td></tr>
|
||
<tr><td>close</td><td>boolean</td><td>true</td><td>点击后是否自动关闭 toast。设为 false 可多次点击</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">action</span>(<span class="s">'文件已删除'</span>, [
|
||
{ <span class="fn">text</span>: <span class="s">'撤销'</span>, <span class="fn">onClick</span>: () => <span class="fn">restore</span>(), <span class="fn">color</span>: <span class="s">'#3b82f6'</span> },
|
||
{ <span class="fn">text</span>: <span class="s">'查看详情'</span>, <span class="fn">onClick</span>: (t) => <span class="fn">openFile</span>(), <span class="fn">color</span>: <span class="s">'#10b981'</span>, <span class="fn">close</span>: false },
|
||
]);</pre>
|
||
|
||
<!-- ===== 管理方法 ===== -->
|
||
<h2 id="group">group(name) <span class="badge badge-new">v2.0</span></h2>
|
||
<p>创建 Toast 分组，返回 GroupAPI 对象。该对象所有方法自动传入 <code>group: name</code>，按组管理。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>说明</th></tr>
|
||
<tr><td>name</td><td>string</td><td>分组名称。GroupAPI 和 dismissGroup 通过此名称关联</td></tr>
|
||
</table>
|
||
<pre><span class="kw">const</span> orders = MeToast.<span class="fn">group</span>(<span class="s">'orders'</span>);
|
||
orders.<span class="fn">success</span>(<span class="s">'订单已创建'</span>);
|
||
orders.<span class="fn">error</span>(<span class="s">'支付失败'</span>, { <span class="fn">duration</span>: 5000 });
|
||
orders.<span class="fn">count</span>(); <span class="cm">// 该组当前 toast 数量</span>
|
||
orders.<span class="fn">dismiss</span>(); <span class="cm">// 关闭该组全部 toast</span>
|
||
<span class="cm">// 也支持主对象关闭</span>
|
||
MeToast.<span class="fn">dismissGroup</span>(<span class="s">'orders'</span>);</pre>
|
||
<div class="return-box">
|
||
<h4>返回 GroupAPI</h4>
|
||
<table>
|
||
<tr><th>方法</th><th>说明</th></tr>
|
||
<tr><td>show(msg, opts?)</td><td>等价 MeToast.show，自动注入 group</td></tr>
|
||
<tr><td>success(msg, opts?)</td><td>等价 MeToast.success</td></tr>
|
||
<tr><td>error(msg, opts?)</td><td>等价 MeToast.error</td></tr>
|
||
<tr><td>warning(msg, opts?)</td><td>等价 MeToast.warning</td></tr>
|
||
<tr><td>info(msg, opts?)</td><td>等价 MeToast.info</td></tr>
|
||
<tr><td>loading(msg, opts?)</td><td>等价 MeToast.loading</td></tr>
|
||
<tr><td>action(msg, actions, opts?)</td><td>等价 MeToast.action</td></tr>
|
||
<tr><td>dismiss()</td><td>关闭该组所有 toast</td></tr>
|
||
<tr><td>count()</td><td>返回该组当前 toast 数量</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<h2 id="dismiss">dismiss(id?)</h2>
|
||
<p>关闭 Toast。无参数则关闭全部。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>说明</th></tr>
|
||
<tr><td>id</td><td>string</td><td>可选。Toast 的 id，不传则关闭所有</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">dismiss</span>(); <span class="cm">// 关闭所有</span>
|
||
MeToast.<span class="fn">dismiss</span>(toast.id); <span class="cm">// 关闭指定</span></pre>
|
||
|
||
<h2 id="clear">clear(position?)</h2>
|
||
<p>按位置清除 Toast。不传参数清除所有位置。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>说明</th></tr>
|
||
<tr><td>position</td><td>string</td><td>可选。位置如 'top-right'，不传则清除全部</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">clear</span>(); <span class="cm">// 全部</span>
|
||
MeToast.<span class="fn">clear</span>(<span class="s">'bottom-right'</span>); <span class="cm">// 仅右下角</span></pre>
|
||
|
||
<h2 id="configure">configure(opts)</h2>
|
||
<p>全局配置，影响后续所有 Toast。theme 和 locale 变化会触发相应副作用（应用主题 CSS / 切换语言）。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>说明</th></tr>
|
||
<tr><td>opts</td><td>object</td><td>包含任意 <a href="#config">配置项</a> 的对象</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">configure</span>({
|
||
<span class="fn">position</span>: <span class="s">'top-right'</span>,
|
||
<span class="fn">duration</span>: 4000,
|
||
<span class="fn">theme</span>: <span class="s">'dark'</span>,
|
||
<span class="fn">animation</span>: <span class="s">'slide'</span>,
|
||
<span class="fn">locale</span>: <span class="s">'zh-CN'</span>,
|
||
});</pre>
|
||
|
||
<h2 id="use">use(plugin)</h2>
|
||
<p>安装插件。支持字符串（内置预设名）或插件对象。已被拒绝注册的无效插件会打印错误。</p>
|
||
<table>
|
||
<tr><th>参数</th><th>类型</th><th>说明</th></tr>
|
||
<tr><td>plugin</td><td>string | object</td><td>预设名 'keyboard'/'persistence'/'accessibility' 或自定义插件对象 { name, version?, install, uninstall? }</td></tr>
|
||
</table>
|
||
<pre>MeToast.<span class="fn">use</span>(<span class="s">'keyboard'</span>); <span class="cm">// ESC 关闭所有 Toast</span>
|
||
MeToast.<span class="fn">use</span>(<span class="s">'persistence'</span>); <span class="cm">// 配置自动保存到 localStorage</span>
|
||
MeToast.<span class="fn">use</span>(<span class="s">'accessibility'</span>); <span class="cm">// 屏幕阅读器实时朗读 toast 内容</span></pre>
|
||
<p class="hint">内置插件详情：keyboard 监听 keydown Escape 键；persistence 将配置写入 localStorage 并在页面加载时恢复；accessibility 在 afterShow/afterUpdate 钩子中通过 aria-live 区域朗读 toast 内容。</p>
|
||
|
||
<h2 id="destroy">destroy()</h2>
|
||
<p>完全销毁。关闭所有 Toast、移除所有 DOM 容器和注入的样式标签、清空内存缓存。</p>
|
||
<pre>MeToast.<span class="fn">destroy</span>();</pre>
|
||
|
||
<!-- ===== 配置参考 ===== -->
|
||
<h2 id="config">全部配置项</h2>
|
||
<p>以下配置可用于 <code>configure()</code>、<code>init()</code> 或单个 Toast 方法的 opts 参数。带 <span class="badge badge-new">v2.0</span> 标识的为 v2.0 新增。</p>
|
||
<table>
|
||
<tr><th>配置项</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||
<tr><td>position</td><td>string</td><td>'top-right'</td><td>位置：top-left / top-center / top-right / bottom-left / bottom-center / bottom-right</td></tr>
|
||
<tr><td>duration</td><td>number</td><td>4000</td><td>显示时长(ms)，0=不自动关闭</td></tr>
|
||
<tr><td>max</td><td>number</td><td>6</td><td>同一位置最多同时显示条数，超出则关闭最早的</td></tr>
|
||
<tr><td>gap</td><td>number</td><td>12</td><td>Toast 之间的间距(px)</td></tr>
|
||
<tr><td>offset</td><td>number</td><td>24</td><td>容器到屏幕边缘的距离(px)</td></tr>
|
||
<tr><td>pauseOnHover</td><td>boolean</td><td>true</td><td>鼠标悬停时暂停 duration 倒计时和进度条</td></tr>
|
||
<tr><td>closeOnClick</td><td>boolean</td><td>true</td><td>点击 Toast 任意位置关闭。关闭按钮始终触发关闭</td></tr>
|
||
<tr><td>draggable</td><td>boolean</td><td>true</td><td>允许拖拽关闭。拖拽超过 120px 触发关闭</td></tr>
|
||
<tr><td>showProgress</td><td>boolean</td><td>true</td><td>显示 duration 倒计时进度条</td></tr>
|
||
<tr><td>progressDirection</td><td>string</td><td>'horizontal'</td><td>进度条方向：horizontal(底部水平) / vertical(右侧垂直)</td></tr>
|
||
<tr><td>icon</td><td>boolean</td><td>true</td><td>显示类型对应图标（success→对勾等）</td></tr>
|
||
<tr><td>closeButton</td><td>boolean</td><td>true</td><td>显示右上角关闭 × 按钮</td></tr>
|
||
<tr><td>theme</td><td>string</td><td>'auto'</td><td>主题：light / dark / auto（跟随系统）/ warm / 自定义注册名</td></tr>
|
||
<tr><td>animation</td><td>string</td><td>'slide'</td><td>入场动画名称，支持 CSS 动画列表见下</td></tr>
|
||
<tr><td>zIndex</td><td>number</td><td>9999</td><td>容器 CSS z-index</td></tr>
|
||
<tr><td>width</td><td>number|string</td><td>360</td><td>Toast 宽度。数字表示 px</td></tr>
|
||
<tr><td>className</td><td>string</td><td>''</td><td>附加到 Toast 元素上的 CSS 类名</td></tr>
|
||
<tr><td>style</td><td>object</td><td>{}</td><td>附加到 Toast 元素上的内联样式对象</td></tr>
|
||
<tr><td>locale</td><td>string</td><td>'zh-CN'</td><td>语言代码（zh-CN / en-US 等）</td></tr>
|
||
<tr><td>resetTimerOnUpdate <span class="badge badge-new">v2.0</span></td><td>boolean</td><td>false</td><td>调用 update() 时重置 duration 倒计时</td></tr>
|
||
<tr><td>notifyWhenHidden <span class="badge badge-new">v2.0</span></td><td>boolean</td><td>false</td><td>页面不可见时自动通过 Notification API 发送系统通知</td></tr>
|
||
<tr><td>render <span class="badge badge-new">v2.0</span></td><td>function</td><td>—</td><td>自定义渲染函数 <code>(toast) => htmlString</code>，完全接管 DOM 构建</td></tr>
|
||
</table>
|
||
|
||
<h2 id="callbacks">回调函数</h2>
|
||
<table>
|
||
<tr><th>回调</th><th>签名</th><th>触发时机</th></tr>
|
||
<tr><td>onShow</td><td>(toast: ToastInstance) => void</td><td>Toast DOM 创建并播放入场动画后</td></tr>
|
||
<tr><td>onClose</td><td>(toast: ToastInstance) => void</td><td>Toast DOM 被移除后（离场动画完成时）</td></tr>
|
||
<tr><td>onClick</td><td>(toast: ToastInstance) => void</td><td>Toast 被点击时（closeOnClick 为 true 时还会自动关闭）</td></tr>
|
||
<tr><td>onUpdate <span class="badge badge-new">v2.0</span></td><td>(toast: ToastInstance) => void</td><td>Toast 内容通过 update() 更新后</td></tr>
|
||
</table>
|
||
|
||
<h2 id="animations">动画列表</h2>
|
||
<p>配置 <code>animation</code> 的值，支持以下 CSS 动画。未在此列表中的值将 fallback 到 slide。</p>
|
||
<table>
|
||
<tr><th>名称</th><th>效果</th><th>时长</th></tr>
|
||
<tr><td>slide</td><td>从右侧滑入 + 回弹</td><td>400ms</td></tr>
|
||
<tr><td>fade</td><td>纯淡入 + blur→清晰</td><td>500ms</td></tr>
|
||
<tr><td>scale</td><td>弹性放大 (0.55→1.07→1)</td><td>450ms</td></tr>
|
||
<tr><td>bounce</td><td>从天而降四段弹跳</td><td>650ms</td></tr>
|
||
<tr><td>flip</td><td>3D 翻转入场 + 回摆</td><td>500ms</td></tr>
|
||
<tr><td>rotate</td><td>旋转摇摆进入</td><td>500ms</td></tr>
|
||
<tr><td>zoom</td><td>从中心爆发式弹出</td><td>500ms</td></tr>
|
||
<tr><td>slideUp</td><td>从下方弹入</td><td>400ms</td></tr>
|
||
<tr><td>slideDown</td><td>从上方弹入</td><td>400ms</td></tr>
|
||
<tr><td>slideLeft</td><td>从左侧滑入</td><td>400ms</td></tr>
|
||
<tr><td>slideRight</td><td>从右侧滑入</td><td>400ms</td></tr>
|
||
</table>
|
||
|
||
<h2 id="themes">主题参考</h2>
|
||
<pre><span class="cm">// 内置主题</span>
|
||
light <span class="cm">— 白色玻璃质感</span>
|
||
dark <span class="cm">— 深色玻璃质感</span>
|
||
auto <span class="cm">— 跟随系统主题设置</span>
|
||
warm <span class="cm">— 暖色调</span>
|
||
|
||
<span class="cm">// 注册自定义主题</span>
|
||
MeToast.themes.<span class="fn">registerTheme</span>(<span class="s">'ocean'</span>, {
|
||
<span class="fn">bg</span>: <span class="s">'rgba(240,249,255,0.96)'</span>,
|
||
<span class="fn">text</span>: <span class="s">'#0c4a6e'</span>,
|
||
<span class="fn">border</span>: <span class="s">'rgba(14,165,233,0.2)'</span>,
|
||
<span class="fn">shadow</span>: <span class="s">'0 10px 36px -10px rgba(14,165,233,0.18)'</span>,
|
||
<span class="fn">hoverShadow</span>: <span class="s">'0 14px 48px -10px rgba(14,165,233,0.22)'</span>,
|
||
<span class="fn">progressBg</span>: <span class="s">'rgba(14,165,233,0.1)'</span>,
|
||
<span class="fn">closeHoverBg</span>: <span class="s">'rgba(14,165,233,0.1)'</span>,
|
||
});
|
||
MeToast.themes.<span class="fn">switchTheme</span>(<span class="s">'ocean'</span>);</pre>
|
||
|
||
</main>
|
||
|
||
<script src="../dist/metona-toast.js"></script>
|
||
<script>
|
||
MeToast.configure({ position: 'top-right', duration: 4000, theme: 'dark', animation: 'slide' });
|
||
document.querySelectorAll('.sidebar a[href^="#"]').forEach(a => {
|
||
a.addEventListener('click', () => {
|
||
document.querySelectorAll('.sidebar a').forEach(x => x.classList.remove('active'));
|
||
a.classList.add('active');
|
||
});
|
||
});
|
||
</script>
|
||
</body>
|
||
</html> |