Files
MetonaToast/site/docs.html
T

356 lines
21 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<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:900px; }
.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 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 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; }
.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; }
@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="#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 参考。所有方法均支持链式调用和配置覆盖。</p>
<!-- ===== 基础通知 ===== -->
<h2 id="show">show(message, opts?)</h2>
<p>显示默认类型的 Toast 通知。</p>
<pre><span class="cm">// 字符串</span>
MeToast.<span class="fn">show</span>(<span class="s">'默认消息'</span>);
<span class="cm">// 带配置</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">// 对象形式</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> });</pre>
<h2 id="success">success(message, opts?)</h2>
<p>显示成功通知。绿色对勾图标。</p>
<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> });</pre>
<h2 id="error">error(message, opts?)</h2>
<p>显示错误通知。红色叉号图标。</p>
<pre>MeToast.<span class="fn">error</span>(<span class="s">'网络错误,请重试'</span>);</pre>
<h2 id="warning">warning(message, opts?)</h2>
<p>显示警告通知。黄色三角图标。</p>
<pre>MeToast.<span class="fn">warning</span>(<span class="s">'请注意检查输入内容'</span>);</pre>
<h2 id="info">info(message, opts?)</h2>
<p>显示信息通知。蓝色圆形图标。</p>
<pre>MeToast.<span class="fn">info</span>(<span class="s">'系统将于 22:00 进行维护'</span>);</pre>
<h2 id="loading">loading(message, opts?)</h2>
<p>显示加载状态。返回一个控制对象,支持链式转换为 success/error/info/warning。</p>
<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);
<span class="cm">// 返回对象方法</span>
loading.<span class="fn">success</span>(msg, opts?) <span class="cm">// 转为成功</span>
loading.<span class="fn">error</span>(msg, opts?) <span class="cm">// 转为错误</span>
loading.<span class="fn">info</span>(msg, opts?) <span class="cm">// 转为信息</span>
loading.<span class="fn">warning</span>(msg, opts?) <span class="cm">// 转为警告</span>
loading.<span class="fn">update</span>(partial) <span class="cm">// 原地更新</span>
loading.<span class="fn">dismiss</span>() <span class="cm">// 关闭</span></pre>
<!-- ===== 高级功能 ===== -->
<h2 id="promise">promise(promise, opts)</h2>
<p>自动根据 Promise 状态切换 Toast。显示 loading → 自动 success/error。</p>
<pre><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>,
}
);</pre>
<table>
<tr><th>参数</th><th>类型</th><th>说明</th></tr>
<tr><td>promise</td><td>Promise</td><td>要监听的 Promise 对象</td></tr>
<tr><td>opts.loading</td><td>string</td><td>加载中文本</td></tr>
<tr><td>opts.success</td><td>string</td><td>成功时文本</td></tr>
<tr><td>opts.error</td><td>string</td><td>失败时文本</td></tr>
</table>
<h2 id="confirm">confirm(message, opts?)</h2>
<p>确认对话框。返回 <code>Promise&lt;boolean&gt;</code>,用户点击确认返回 true。</p>
<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&lt;string|null&gt;</code>,用户取消返回 null。</p>
<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="kw">if</span> (name) MeToast.<span class="fn">info</span>(<span class="s">'你好,'</span> + name + <span class="s">''</span>);</pre>
<h2 id="progress">progress(message, opts?)</h2>
<p>进度条通知。返回控制对象,可调用 setProgress / complete / error。</p>
<pre><span class="kw">const</span> p = MeToast.<span class="fn">progress</span>(<span class="s">'上传中...'</span>);
p.<span class="fn">setProgress</span>(30);
p.<span class="fn">setProgress</span>(70);
p.<span class="fn">complete</span>(<span class="s">'上传完成!'</span>);
<span class="cm">// 或</span>
p.<span class="fn">error</span>(<span class="s">'上传失败'</span>);
p.<span class="fn">dismiss</span>();</pre>
<h2 id="countdown">countdown(message, seconds, opts?)</h2>
<p>倒计时 Toast。<code>{seconds}</code> 占位符自动替换为剩余秒数。</p>
<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>),
});
<span class="cm">// 返回控制对象</span>
<span class="kw">const</span> c = MeToast.<span class="fn">countdown</span>(<span class="s">'{seconds}s'</span>, 10);
c.<span class="fn">cancel</span>(); <span class="cm">// 取消并关闭</span>
c.<span class="fn">pause</span>(); <span class="cm">// 暂停</span>
c.<span class="fn">resume</span>(); <span class="cm">// 恢复</span></pre>
<h2 id="queue">queue(messages, opts?)</h2>
<p>队列展示:顺序逐个显示消息。返回可取消的 thenable 对象。</p>
<pre><span class="kw">const</span> q = MeToast.<span class="fn">queue</span>([<span class="s">'步骤一'</span>, <span class="s">'步骤二'</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">// 等待队列完成</span></pre>
<h2 id="stack">stack(messages, opts?)</h2>
<p>堆叠展示:同时错峰显示多条消息。</p>
<pre>MeToast.<span class="fn">stack</span>([<span class="s">'消息1'</span>, <span class="s">'消息2'</span>, <span class="s">'消息3'</span>, <span class="s">'消息4'</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:内嵌操作按钮的通知。类似 Android Snackbar。</p>
<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>: () => <span class="fn">openFile</span>() },
]);</pre>
<table>
<tr><th>按钮字段</th><th>类型</th><th>说明</th></tr>
<tr><td>text</td><td>string</td><td>按钮文本</td></tr>
<tr><td>onClick</td><td>function</td><td>点击回调,参数为 toast 实例</td></tr>
<tr><td>color</td><td>string</td><td>按钮背景色,默认 #6366f1</td></tr>
<tr><td>close</td><td>boolean</td><td>点击后是否关闭 toast,默认 true</td></tr>
</table>
<!-- ===== 管理方法 ===== -->
<h2 id="group">group(name) <span class="badge badge-new">v2.0</span></h2>
<p>创建 Toast 分组。返回一个自动添加 <code>group</code> 参数的子对象,支持按组管理。</p>
<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>);
orders.<span class="fn">count</span>(); <span class="cm">// 该组的 toast 数量</span>
orders.<span class="fn">dismiss</span>(); <span class="cm">// 关闭整组</span>
<span class="cm">// 也可通过主对象关闭</span>
MeToast.<span class="fn">dismissGroup</span>(<span class="s">'orders'</span>);</pre>
<h2 id="dismiss">dismiss(id?)</h2>
<p>关闭 Toast。无参数关闭所有,传 id 关闭指定。</p>
<pre>MeToast.<span class="fn">dismiss</span>(); <span class="cm">// 关闭所有</span>
MeToast.<span class="fn">dismiss</span>(toastId); <span class="cm">// 关闭指定</span></pre>
<p>其他管理方法:<code>count()</code> <code>getToasts()</code> <code>pauseAll()</code> <code>resumeAll()</code> <code>destroy()</code> <code>clear()</code></p>
<h2 id="configure">configure(opts)</h2>
<p>全局配置。影响后续所有 Toast。</p>
<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>
<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">// 屏幕阅读器朗读</span>
<span class="cm">// 自定义插件</span>
MeToast.<span class="fn">use</span>({
<span class="fn">name</span>: <span class="s">'my-plugin'</span>,
<span class="fn">install</span>() {
Toast.<span class="fn">on</span>(<span class="s">'afterShow'</span>, (t) => <span class="fn">console</span>.log(t.message));
},
});</pre>
<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> 或单个 Toast 的第二个参数。</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/center/right、bottom-left/center/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>悬停时暂停计时</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>允许拖拽关闭</td></tr>
<tr><td>showProgress</td><td>boolean</td><td>true</td><td>显示进度条</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>显示类型图标</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>动画效果(见下方列表)</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>附加 CSS 类名</td></tr>
<tr><td>style</td><td>object</td><td>{}</td><td>内联样式对象</td></tr>
<tr><td>locale</td><td>string</td><td>'zh-CN'</td><td>语言代码</td></tr>
<tr><td>resetTimerOnUpdate</td><td>boolean</td><td>false</td><td>update()时重置计时器 <span class="badge badge-new">v2.0</span></td></tr>
<tr><td>notifyWhenHidden</td><td>boolean</td><td>false</td><td>页面不可见时发系统通知 <span class="badge badge-new">v2.0</span></td></tr>
<tr><td>render</td><td>function</td><td></td><td>自定义渲染函数 <span class="badge badge-new">v2.0</span></td></tr>
</table>
<h2 id="callbacks">回调函数</h2>
<table>
<tr><th>回调</th><th>签名</th><th>触发时机</th></tr>
<tr><td>onShow</td><td>(toast) => void</td><td>Toast 显示后</td></tr>
<tr><td>onClose</td><td>(toast) => void</td><td>Toast 关闭后</td></tr>
<tr><td>onClick</td><td>(toast) => void</td><td>Toast 被点击时</td></tr>
<tr><td>onUpdate</td><td>(toast) => void</td><td>Toast 内容更新后 <span class="badge badge-new">v2.0</span></td></tr>
</table>
<h2 id="animations">动画列表</h2>
<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>