docs: API文档17个方法全部补全参数表、返回值、类型、默认值

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 @@
   <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>
@@ -87,159 +87,303 @@
 <main class="main">
 
 <h1>API 文档</h1>
-<p>MetonaToast v2.0.0 完整 API 参考。所有方法均支持链式调用和配置覆盖。</p>
+<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>
-<pre><span class="cm">// 字符串</span>
+<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>);
-
-<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>
+<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>显示成功通知。绿色对勾图标。</p>
+<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> });</pre>
+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>显示错误通知。红色叉号图标。</p>
-<pre>MeToast.<span class="fn">error</span>(<span class="s">'网络错误，请重试'</span>);</pre>
+<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>显示警告通知。黄色三角图标。</p>
+<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>显示信息通知。蓝色圆形图标。</p>
-<pre>MeToast.<span class="fn">info</span>(<span class="s">'系统将于 22:00 进行维护'</span>);</pre>
+<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>显示加载状态。返回一个控制对象，支持链式转换为 success/error/info/warning。</p>
+<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);
-
-<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>
+<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 状态切换 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>),
-  {
+<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>,
-  }
-);</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>
+  });
+} <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&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>, {
+<p>确认对话框。返回 <code>Promise&lt;boolean&gt;</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="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>
+<p>输入对话框。返回 <code>Promise&lt;string|null&gt;</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 + <span class="s">'！'</span>);</pre>
+<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>进度条通知。返回控制对象，可调用 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>);
+<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>
-<pre>MeToast.<span class="fn">countdown</span>(<span class="s">'操作将在 {seconds} 秒后执行'</span>, 5, {
+<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>),
-});
-
-<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>
+});</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>队列展示：顺序逐个显示消息。返回可取消的 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>
+<p>顺序逐个显示消息队列。前一条关闭后延时显示下一条。返回 QueueControl（thenable + cancel）。</p>
+<table>
+<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
+<tr><td>messages</td><td>Array&lt;string|object&gt;</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>堆叠展示：同时错峰显示多条消息。</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>], {
+<p>同时错峰显示多条消息。每条间隔 stagger 毫秒依次出现，全部叠加在屏幕上。</p>
+<table>
+<tr><th>参数</th><th>类型</th><th>默认值</th><th>说明</th></tr>
+<tr><td>messages</td><td>Array&lt;string|object&gt;</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：内嵌操作按钮的通知。类似 Android Snackbar。</p>
+<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>: () => <span class="fn">openFile</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>
-<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>
+<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>);
-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>
+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。无参数关闭所有，传 id 关闭指定。</p>
+<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>(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>
+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。</p>
+<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,
@@ -249,66 +393,64 @@ MeToast.<span class="fn">dismiss</span>(toastId); <span class="cm">// 关闭指
 });</pre>
 
 <h2 id="use">use(plugin)</h2>
-<p>安装插件。支持字符串（预设）和对象（自定义）。</p>
+<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">// 屏幕阅读器朗读</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>
+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>
+<p>完全销毁。关闭所有 Toast、移除所有 DOM 容器和注入的样式标签、清空内存缓存。</p>
 <pre>MeToast.<span class="fn">destroy</span>();</pre>
 
 <!-- ===== 配置参考 ===== -->
 <h2 id="config">全部配置项</h2>
-<p>以下配置可用于 <code>configure()</code> 或单个 Toast 的第二个参数。</p>
+<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/center/right、bottom-left/center/right</td></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>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>
+<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) => 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>
+<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>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>
@@ -324,7 +466,7 @@ MeToast.<span class="fn">use</span>({
 <pre><span class="cm">// 内置主题</span>
 light   <span class="cm">— 白色玻璃质感</span>
 dark    <span class="cm">— 深色玻璃质感</span>
-auto    <span class="cm">— 跟随系统</span>
+auto    <span class="cm">— 跟随系统主题设置</span>
 warm    <span class="cm">— 暖色调</span>
 
 <span class="cm">// 注册自定义主题</span>
@@ -344,7 +486,6 @@ MeToast.themes.<span class="fn">switchTheme</span>(<span class="s">'ocean'</span
 <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'));