From 10cfe0066b94622918e810ee7573d6bd483e1549 Mon Sep 17 00:00:00 2001 From: thzxx Date: Thu, 23 Jul 2026 22:57:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20MetonaEditor=20?= =?UTF-8?q?=E5=92=8C=20MetonaToast=20=E5=8F=82=E8=80=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/metona-editor-demo.html | 419 +++++++++++++++++++++++ docs/metona-editor-docs.html | 621 +++++++++++++++++++++++++++++++++++ docs/metona-toast-demo.html | 417 +++++++++++++++++++++++ docs/metona-toast-docs.html | 497 ++++++++++++++++++++++++++++ 4 files changed, 1954 insertions(+) create mode 100644 docs/metona-editor-demo.html create mode 100644 docs/metona-editor-docs.html create mode 100644 docs/metona-toast-demo.html create mode 100644 docs/metona-toast-docs.html diff --git a/docs/metona-editor-demo.html b/docs/metona-editor-demo.html new file mode 100644 index 0000000..1a01f5b --- /dev/null +++ b/docs/metona-editor-demo.html @@ -0,0 +1,419 @@ + + + + + +MetonaEditor · 功能演示 + + + +
+
+

+ MetonaEditor 功能演示 + ← 返回首页 + 📖 文档 +

+
+ 主题 +
+ + + +
+ 语言 +
+ + +
+ 模式 +
+ +
+
+
+ +
+
+ + 状态:运行中 +
+
模式:split
+
主题:light
+
语言:zh-CN
+
字数:0
+
全屏:否
+
+ +
+ +
+
+
+ API 控制台 + 0 次调用 +
+
+
+ + + + + + + + + + + + + + + + + + + +
+
+ +
+
+ 事件流（实时） + 0 个事件 +
+
+
+
+ +
+ 快捷键提示： + 编辑区内按 Ctrl+B 加粗、Ctrl+I 斜体、Ctrl+K 插入链接、 + Ctrl+Z 撤销、Ctrl+S 触发保存、Ctrl+F 查找、Ctrl+H 替换、 + Tab 缩进、Esc 关闭面板。 +
+
+ + + + + diff --git a/docs/metona-editor-docs.html b/docs/metona-editor-docs.html new file mode 100644 index 0000000..9bca68b --- /dev/null +++ b/docs/metona-editor-docs.html @@ -0,0 +1,621 @@ + + + + + +MetonaEditor · 文档 + + + + + + +
+

文档

+

MetonaEditor v0.1.3 完整 API、配置与使用指南

+
+ +
+
+ + +
+ + +
+

安装与引入

+ +
# npm 安装
+npm install @metona-team/metona-editor
+
+# ES Module
+import MeEditor from '@metona-team/metona-editor';
+const editor = MeEditor.create('#editor', {
+  value: '# Hello World',
+  mode: 'split',
+});
+
+# 浏览器 UMD
+<script src="dist/metona-editor.js"></script>
+<script>
+const editor = MeEditor.create('#editor');
+</script>
+
+ + +
+

全部配置项

+

所有配置均为可选，以下是默认值：

+ +
MeEditor.create(container, {
+  // 内容
+  value: '',              // 初始 Markdown 文本
+  placeholder: '',        // 占位符
+
+  // 视图
+  mode: 'split',          // 'edit' | 'split' | 'preview'
+  height: 400,            // 数字为 px，字符串原样使用
+  toolbar: DEFAULT_TOOLBAR, // 工具栏配置，false 隐藏
+  wordCount: true,        // 字数统计状态栏
+
+  // 行为
+  autofocus: false,       // 自动聚焦
+  spellcheck: false,      // 拼写检查
+  readOnly: false,        // 只读模式
+  historyLimit: 100,      // 历史栈上限
+  historyDebounce: 400,   // 历史防抖延迟（ms）
+  syncScroll: true,       // 分屏模式同步滚动
+  tabSize: 2,             // 制表符空格数（0 表示 \t）
+
+  // 主题与国际化
+  theme: 'auto',          // 'light' | 'dark' | 'auto' | 'warm' | 自定义
+  locale: 'zh-CN',        // 'zh-CN' | 'en-US' | 自定义
+
+  // 自定义渲染
+  render: null,           // (md, env) => html
+  highlight: null,        // (code, lang) => html
+  sanitize: null,         // (html) => safeHtml
+
+  // 外观
+  className: '',          // 容器额外 class
+  style: {},              // 内联样式
+
+  // 插件与回调
+  plugins: [],            // 实例级插件数组
+  onChange: null,         // (value, editor) => void
+  onInput: null,          // (value, editor) => void
+  onFocus: null,          // (editor) => void
+  onBlur: null,           // (editor) => void
+  onSave: null,           // (value, editor) => void
+  onModeChange: null,     // (mode, editor) => void
+  onFullscreen: null,    // (fullscreen, editor) => void
+  onCreate: null,         // (editor) => void
+  onDestroy: null,        // (editor) => void
+});
+
+ + +
+

工具栏配置

+ +
// 默认工具栏（完整按钮）
+MeEditor.create(container, { toolbar: true });
+
+// 隐藏工具栏
+MeEditor.create(container, { toolbar: false });
+
+// 自定义工具栏 — '|' 为分隔符
+MeEditor.create(container, {
+  toolbar: ['bold', 'italic', '|', 'h1', 'h2', '|', 'undo', 'redo'],
+});
+ +

可用动作：

+

+bolditalicstrikethroughunderlinecode +h1h2h3quoteulol +indentoutdenthr +linkimagetable +undoredo +editsplitpreviewfullscreen +

+
+ + +
+

实例 API

+ +

内容操作

+
editor.getValue();                    // 获取 Markdown 文本
+editor.setValue(md, { silent });      // 设置内容，silent 不触发 change
+editor.getHTML();                     // 获取渲染后的 HTML
+editor.refresh();                     // 强制刷新预览（内容未变时）
+editor.insert(text, { replace });     // 光标处插入 / 替换选区
+editor.wrap(before, after);           // 选区包裹
+editor.focus();                       // 聚焦
+editor.blur();                        // 失焦
+
+ +
+

命令执行

+
editor.exec(action, ...args);         // 执行命令，返回 this 链式调用
+
+editor.exec('bold').exec('h1');        // 链式调用
+ + + + + + + + + + + + + + + + + + + +
action效果快捷键
bold加粗 **text**Ctrl+B
italic斜体 *text*Ctrl+I
strikethrough删除线 ~~text~~—
underline下划线 <u>text</u>Ctrl+U
code行内代码 `text`Ctrl+E
h1/h2/h3标题 # / ## / ###Ctrl+1/2/3
quote引用 >Ctrl+Q
ul/ol无序/有序列表—
indent/outdent缩进/反缩进Tab/Shift+Tab
hr水平线 ---—
link插入链接 [text](url)Ctrl+K
image插入图片 ![alt](url)—
table插入表格—
undo/redo撤销/重做Ctrl+Z / Ctrl+Y
edit/split/preview切换模式—
fullscreen切换全屏—
+
+ +
+

历史栈

+
editor.undo();                        // 撤销
+editor.redo();                        // 重做
+editor.canUndo();                     // 是否可撤销
+editor.canRedo();                     // 是否可重做
+
+ +
+

模式与全屏

+
editor.setMode('split');              // 设置模式：edit | split | preview
+editor.getMode();                     // 获取当前模式
+editor.toggleFullscreen();            // 切换全屏
+editor.exitFullscreen();              // 退出全屏
+editor.isFullscreen();                // 是否全屏
+
+ +
+

统计与状态

+
editor.getStats();
+// => { characters, words, chineseChars, englishWords, lines, readingTime }
+
+editor.getStatus();
+// => { id, mode, theme, locale, fullscreen, readOnly, disabled, destroyed, plugins }
+
+ +
+

启用/禁用/只读

+
editor.enable();                      // 启用
+editor.disable();                     // 禁用
+editor.isDisabled();                  // 是否禁用
+editor.setReadOnly(true);             // 只读模式
+editor.isReadOnly();                  // 是否只读
+
+ +
+

事件系统

+ + + + + + + + + + + + + + +
事件名触发时机回调参数
inputtextarea 原生 input(value, editor)
change内容变化(value, editor)
focus聚焦(editor)
blur失焦(editor)
saveCtrl+S(value, editor)
modeChange模式切换(mode, editor)
fullscreen全屏切换(fullscreen, editor)
destroy销毁()
autosaveautoSave 保存({ key, value })
beforeRender渲染前(editor)
afterRender渲染后(editor)
+ +

全局钩子（所有实例共享）

+ + + + + + + + +
钩子触发时机
beforeCreate构造函数初始化前
afterCreate构造函数初始化完成
beforeRender每次渲染前（全局）
afterRender每次渲染后（全局）
beforeDestroydestroy 前
afterDestroydestroy 后
+
+ +
+

插件管理

+
editor.use(plugin, options);          // 安装插件
+editor.getPlugins();                  // 获取已安装插件列表
+editor.addToolbarButton(config);      // 追加工具栏按钮
+
+ +
+

生命周期

+
editor.destroy();                     // 销毁实例
+editor.isDestroyed();                 // 是否已销毁
+
+ + +
+

静态 API

+ +
import MeEditor from '@metona-team/metona-editor';
+
+// 工厂函数
+MeEditor.create(container, options);
+
+// 全局默认插件
+MeEditor.use(presetPlugins.autoSave, { delay: 2000 });
+MeEditor.use('searchReplace');
+MeEditor.use(customPlugin);
+
+// 全局事件钩子
+MeEditor.on('beforeCreate', (editor) => {});
+MeEditor.off('beforeCreate', handler);
+
+// 主题与语言
+MeEditor.setTheme('dark');
+MeEditor.setLocale('en-US');
+
+// 状态查询
+MeEditor.getStatus(); // => { version, theme, locale, globalPlugins, presetPlugins }
+
+// 销毁全局资源
+MeEditor.destroy();
+
+// 内置解析器
+import { parseMarkdown, safeUrl, slugify } from '@metona-team/metona-editor';
+parseMarkdown('# Hello');           // => '<h1 id="hello">Hello</h1>'
+safeUrl('javascript:alert(1)');     // => ''
+slugify('Hello World');             // => 'hello-world'
+
+ + +
+

解析器语法参考

+ + + + + + + + + + + + + + + + + + + + + + + +
语法示例输出
标题# H1 ~ ###### H6<h1> ~ <h6>
段落纯文本<p>
粗体**bold** __bold__<strong>
斜体*italic* _italic_<em>
删除线~~text~~<del>
高亮标记==text==<mark>
上标x^2^<sup>
下标H~2~O<sub>
行内代码`code`<code>
代码块```lang<pre><code>
引用> quote<blockquote>
无序列表- item<ul><li>
有序列表1. item<ol><li>
任务列表- [x] done<li class="me-task-item">
水平线--- *** ___<hr>
表格| a | b |<table>（支持 :---: 列对齐）
链接[text](url)<a>
图片![alt](url)<img>
自动链接<https://...><a>
Emoji:smile: :rocket:😊 🚀（80+ 常用）
+ +

XSS 防护

+

所有文本经 HTML 转义。URL 自动过滤 javascript: vbscript: file: 及非图片 data: 协议。

+
+ + +
+

插件约定

+ +
const myPlugin = {
+  name: 'myPlugin',
+  description: '我的自定义插件',
+
+  install(editor, options) {
+    // this 指向插件对象本身
+    this._timer = null;
+    editor.on('change', this._onChange);
+  },
+
+  destroy(editor) {
+    if (this._timer) clearTimeout(this._timer);
+    editor.off('change', this._onChange);
+  },
+};
+
+ +
+

预设插件

+ +

autoSave — 自动保存草稿

+
editor.use(presetPlugins.autoSave, {
+  key: 'me-draft-' + editor.id,  // localStorage key
+  delay: 1000,                    // 防抖延迟（ms）
+});
+editor.restoreDraft();             // 恢复草稿
+editor.clearDraft();               // 清除草稿
+editor.getDraftKey();              // 获取存储 key
+ +

exportTool — 导出文件

+
editor.use(presetPlugins.exportTool);
+editor.exportMarkdown('my-doc.md');
+editor.exportHTML('my-doc.html', {
+  title: '文档标题',
+  css: 'body { font-family: sans-serif; }',
+  lang: 'zh-CN',
+});
+ +

searchReplace — 查找替换

+
editor.use(presetPlugins.searchReplace);
+// Ctrl+F → 查找  Ctrl+H → 替换
+// Enter → 下一个  Shift+Enter → 上一个  Escape → 关闭
+ +

imagePaste — 粘贴图片转 base64

+
editor.use(presetPlugins.imagePaste);
+// 在编辑区 Ctrl+V 粘贴剪贴板图片
+// 自动插入 ![](data:image/png;base64,...)
+
+ + +
+

主题系统

+ +
// 切换主题
+MeEditor.setTheme('light');         // 亮色
+MeEditor.setTheme('dark');          // 暗色
+MeEditor.setTheme('warm');          // 暖色
+MeEditor.setTheme('auto');          // 自动（默认）
+
+// 注册自定义主题
+import { themeUtils } from '@metona-team/metona-editor';
+themeUtils.registerTheme('ocean', {
+  bg: '#001122', text: '#aabbcc', accent: '#00ddff',
+});
+themeUtils.applyTheme('ocean');
+ +

CSS 变量：主题变量限定在 .me-wrapper 元素上，不污染全局样式。支持 @media print 打印样式。

+
+ + +
+

国际化

+ +
// 切换语言
+MeEditor.setLocale('en-US');
+MeEditor.setLocale('zh-CN');
+
+// 翻译函数
+import { i18nUtils } from '@metona-team/metona-editor';
+i18nUtils.t('bold');                 // => '粗体'（zh-CN）
+i18nUtils.t('bold');                 // => 'Bold'（en-US）
+
+// 添加语言
+i18nUtils.addTranslations('ja', { bold: '太字', italic: '斜体' });
+
+// 格式化
+i18nUtils.formatNumber(1234567);              // => '1,234,567'
+i18nUtils.formatCurrency(99.99, 'USD');       // => '$99.99'
+i18nUtils.formatDate('2024-01-15');           // => '1/15/2024'
+
+ +
+
+
+ + + + + + + diff --git a/docs/metona-toast-demo.html b/docs/metona-toast-demo.html new file mode 100644 index 0000000..677e342 --- /dev/null +++ b/docs/metona-toast-demo.html @@ -0,0 +1,417 @@ + + + + + + +在线演示 — MetonaToast + + + + + + +
+

在线演示

+

覆盖项目全部功能的交互演示 — 点击即可体验

+
+ +
+ + +
+
📢 基础通知
+
+ + + + + +
+
+
+ + + + + + +
+
+
+ + +
+
🔄 Loading 链式转换
+
+ + + + +
+
+ + +
+
💬 对话框
+
+ + + + +
+
+ + +
+
📊 进度 & 倒计时
+
+ + + + +
+
+ + +
+
📋 队列 & 堆叠
+
+ + + + +
+
+ + +
+
⚡ Action Toast v2.0
+
+ + + +
+
+ + +
+
📁 分组管理 v2.0
+
+ + + + +
+
+ + +
+
🎭 11种动画效果
+
+ + + + + + + + + + + +
+
+ + +
+
📍 全部位置
+
+ + + + + + +
+
+ + +
+
🎨 主题切换 & 自定义
+
+ + + + + +
+
+ + +
+
🔌 插件系统
+
+ + + + +
+
+ + +
+
🆕 v2.0 新功能 resetTimer · onUpdate · render · notify
+
+ + + + +
+
+ + +
+
🔧 Toast 管理
+
+ + + + + + + +
+
+
+ + + + +
+
+
+ + +
+
✋ 交互特性
+
+ + + + + +
+
+ + +
+
🌍 国际化 & 格式化
+
+ + + +
+
+ + +
+
🎨 107种预设图标 — 点击任意图标发送Toast
+
+
+ +
+ + + + + + + diff --git a/docs/metona-toast-docs.html b/docs/metona-toast-docs.html new file mode 100644 index 0000000..55efa52 --- /dev/null +++ b/docs/metona-toast-docs.html @@ -0,0 +1,497 @@ + + + + + + +API 文档 — MetonaToast + + + + + + +
+ +

API 文档

+

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

+ + +

show(message, opts?)

+

显示默认类型的 Toast 通知，无特定颜色和图标。

+ + + + +
参数类型默认值说明
messagestring | object—消息字符串，或包含 title/message 等属性的配置对象
optsobject{}可选配置对象，覆盖 全部配置项。仅当 message 为字符串时有效
+
// 字符串形式
+MeToast.show('默认消息');
+MeToast.show('自定义', { duration: 2000, position: 'bottom-center' });
+// 对象形式（所有 opts 作为一级属性）
+MeToast.show({ title: '标题', message: '内容', duration: 3000 });
+ +

success(message, opts?)

+

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

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

error(message, opts?)

+

显示错误通知。红色叉号图标 #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?)

+

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

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

loading(message, opts?)

+

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

+ + + + +
参数类型默认值说明
messagestring | object—加载提示文本或配置对象
optsobject{}可选配置覆盖
+
const loading = MeToast.loading('正在提交...');
+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 生命周期。自动显示 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: '加载失败',
+  });
+} catch (e) { /* promise reject 会继续抛出 */ }
+ +

confirm(message, opts?)

+

确认对话框。返回 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: '保留',
+});
+if (ok) MeToast.success('已删除');
+ +

prompt(message, opts?)

+

输入对话框。返回 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);
+ +

progress(message, opts?)

+

进度条通知。不自动关闭。返回 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} 占位符每秒自动替换为剩余秒数。

+ + + + + + +
参数类型默认值说明
messagestring—消息文本。支持 {seconds} 占位符。非字符串打印错误并返回空控制对象
secondsnumber10倒计时秒数，最小 1
opts.onCompletefunction—倒计时归零时的回调
opts.typestring"warning"Toast 类型
+
MeToast.countdown('{seconds} 秒后执行', 5, {
+  onComplete: () => MeToast.success('已执行'),
+});
+
+

返回 CountdownControl

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

queue(messages, opts?)

+

顺序逐个显示消息队列。前一条关闭后延时显示下一条。返回 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?)

+

同时错峰显示多条消息。每条间隔 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：内嵌操作按钮。默认 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: (t) => openFile(), color: '#10b981', close: false },
+]);
+ + +

group(name) v2.0

+

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

+ + + +
参数类型说明
namestring分组名称。GroupAPI 和 dismissGroup 通过此名称关联
+
const orders = MeToast.group('orders');
+orders.success('订单已创建');
+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。无参数则关闭全部。

+ + + +
参数类型说明
idstring可选。Toast 的 id，不传则关闭所有
+
MeToast.dismiss();          // 关闭所有
+MeToast.dismiss(toast.id);  // 关闭指定
+ +

clear(position?)

+

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

+ + + +
参数类型说明
positionstring可选。位置如 'top-right'，不传则清除全部
+
MeToast.clear();                      // 全部
+MeToast.clear('bottom-right'); // 仅右下角
+ +

configure(opts)

+

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

+ + + +
参数类型说明
optsobject包含任意 配置项 的对象
+
MeToast.configure({
+  position: 'top-right',
+  duration: 4000,
+  theme: 'dark',
+  animation: 'slide',
+  locale: 'zh-CN',
+});
+ +

use(plugin)

+

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

+ + + +
参数类型说明
pluginstring | object预设名 'keyboard'/'persistence'/'accessibility' 或自定义插件对象 { name, version?, install, uninstall? }
+
MeToast.use('keyboard');      // ESC 关闭所有 Toast
+MeToast.use('persistence');   // 配置自动保存到 localStorage
+MeToast.use('accessibility'); // 屏幕阅读器实时朗读 toast 内容
+

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

+ +

destroy()

+

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

+
MeToast.destroy();
+ + +

全部配置项

+

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

+ + + + + + + + + + + + + + + + + + + + + + + + +
配置项类型默认值说明
positionstring'top-right'位置：top-left / top-center / top-right / bottom-left / bottom-center / bottom-right
durationnumber4000显示时长(ms)，0=不自动关闭
maxnumber6同一位置最多同时显示条数，超出则关闭最早的
gapnumber12Toast 之间的间距(px)
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: 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。

+ + + + + + + + + + + + + +
名称效果时长
slide从右侧滑入 + 回弹400ms
fade纯淡入 + blur→清晰500ms
scale弹性放大 (0.55→1.07→1)450ms
bounce从天而降四段弹跳650ms
flip3D 翻转入场 + 回摆500ms
rotate旋转摇摆进入500ms
zoom从中心爆发式弹出500ms
slideUp从下方弹入400ms
slideDown从上方弹入400ms
slideLeft从左侧滑入400ms
slideRight从右侧滑入400ms
+ +

主题参考

+
// 内置主题
+light   — 白色玻璃质感
+dark    — 深色玻璃质感
+auto    — 跟随系统主题设置
+warm    — 暖色调
+
+// 注册自定义主题
+MeToast.themes.registerTheme('ocean', {
+  bg: 'rgba(240,249,255,0.96)',
+  text: '#0c4a6e',
+  border: 'rgba(14,165,233,0.2)',
+  shadow: '0 10px 36px -10px rgba(14,165,233,0.18)',
+  hoverShadow: '0 14px 48px -10px rgba(14,165,233,0.22)',
+  progressBg: 'rgba(14,165,233,0.1)',
+  closeHoverBg: 'rgba(14,165,233,0.1)',
+});
+MeToast.themes.switchTheme('ocean');
+ +
+ + + + + \ No newline at end of file