` |
+| 代码块 | ` ```lang ` | `` |
+| 引用 | `> quote` | `` |
+| 无序列表 | `- item` / `* item` / `+ item` | `- ` |
+| 有序列表 | `1. item` | `
- ` |
+| 任务列表 | `- [x] done` | `
- ` |
+| 水平线 | `---` `***` `___` | `
` |
+| 表格 | `\| a \| b \|` | `
bold
' + +safeUrl('javascript:alert(1)'); // => ''（过滤危险协议） +safeUrl('https://example.com'); // => 'https://example.com' + +slugify('Hello World'); // => 'hello-world' +slugify('你好世界'); // => '你好世界' +``` + +--- + +## 事件系统 + +MetonaEditor 提供两层事件系统： + +### 实例事件 + +```javascript +editor.on('change', (value, editor) => { + console.log('内容变化'); +}); + +editor.on('modeChange', (mode, editor) => { + console.log('模式切换:', mode); +}); + +editor.on('destroy', () => { + console.log('编辑器已销毁'); +}); +``` + +**可用事件**： + +| 事件 | 触发时机 | 回调参数 | +|------|---------|---------| +| `input` | textarea 原生 input | `(value, editor)` | +| `change` | 内容变化（input/setValue/exec） | `(value, editor)` | +| `focus` | 聚焦 | `(editor)` | +| `blur` | 失焦 | `(editor)` | +| `save` | Ctrl+S | `(editor)` | +| `modeChange` | 模式切换 | `(mode, editor)` | +| `fullscreen` | 全屏切换 | `(fullscreen, editor)` | +| `destroy` | 销毁 | `()` | +| `autosave` | autoSave 插件触发 | `({ key, value })` | + +### 静态钩子（全局） + +```javascript +MarkdownEditor.on('beforeCreate', (editor) => { + console.log('实例即将创建'); +}); + +MarkdownEditor.on('afterDestroy', (editor) => { + console.log('实例已销毁'); +}); +``` + +**可用钩子**： + +| 钩子 | 触发时机 | +|------|---------| +| `beforeCreate` | 构造函数初始化前 | +| `afterCreate` | 构造函数初始化完成 | +| `beforeRender` | 每次渲染前 | +| `afterRender` | 每次渲染后 | +| `beforeDestroy` | destroy 前 | +| `afterDestroy` | destroy 后 | + +--- + +## 插件系统 + +### 插件约定 + +```javascript +const myPlugin = { + name: 'myPlugin', + description: '我的自定义插件', + + // 安装时调用，this 指向插件对象本身 + install(editor, options) { + // 在 this 上存放运行时状态 + this._timer = null; + + // 暴露实例方法 + editor.doSomething = () => { + console.log(editor.getValue()); + }; + + // 监听事件 + editor.on('change', this._onChange); + }, + + // 卸载时调用，清理事件与 DOM + destroy(editor) { + if (this._timer) clearTimeout(this._timer); + if (editor && typeof editor.off === 'function') { + editor.off('change', this._onChange); + } + }, +}; +``` + +### 使用插件 + +```javascript +// 实例级安装 +editor.use(myPlugin, { option1: 'value' }); + +// 全局默认插件（所有新实例自动安装） +MeEditor.use(myPlugin); +MeEditor.use(presetPlugins.autoSave, { delay: 2000 }); +``` + +### 预设插件 + +#### autoSave — 自动保存草稿 + +```javascript +editor.use(presetPlugins.autoSave, { + key: 'me-draft-' + editor.id, // localStorage key + delay: 1000, // 防抖延迟（ms） +}); + +// 暴露的 API +editor.getDraftKey(); // 获取存储 key +editor.restoreDraft(); // 从 localStorage 恢复 +editor.clearDraft(); // 清除草稿 +``` + +#### exportTool — 导出文件 + +```javascript +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 — 查找替换 + +```javascript +editor.use(presetPlugins.searchReplace); + +// 快捷键 +// Ctrl+F / Cmd+F — 打开查找面板 +// Ctrl+H / Cmd+H — 打开查找替换面板 +// Enter — 下一个 +// Shift+Enter — 上一个 +// Escape — 关闭 +``` + +### 自定义工具栏按钮 + +```javascript +editor.addToolbarButton({ + name: 'timestamp', + title: '插入时间戳', + icon: '', // SVG 字符串 + action: () => { + editor.insert(`\n${new Date().toISOString()}\n`); + }, + className: 'my-btn', // 可选 +}); +``` + +### PluginManager 与 pluginUtils + +```javascript +import { pluginUtils, PluginManager } from '@metona-team/metona-editor'; + +// 创建独立管理器 +const pm = new PluginManager(); +pm.register('my', myPlugin); +pm.has('my'); // true +pm.get('my'); // myPlugin +pm.enable('my'); +pm.disable('my'); +pm.unregister('my'); +pm.destroy(); + +// pluginUtils 工具集 +pluginUtils.createPlugin({ name: 'x', install: () => {} }); +pluginUtils.validatePlugin(plugin); // => { valid: boolean, errors: string[] } +pluginUtils.getPreset('autoSave'); // => 副本 +pluginUtils.getAllPresets(); // => { autoSave, exportTool, searchReplace } +``` + +--- + +## 主题系统 + +### 内置主题 + +```javascript +MeEditor.setTheme('light'); // 亮色 +MeEditor.setTheme('dark'); // 暗色 +MeEditor.setTheme('warm'); // 暖色 +MeEditor.setTheme('auto'); // 跟随系统（默认） +``` + +### CSS 变量定制 + +```css +:root { + --md-bg: #ffffff; + --md-text: #1f2937; + --md-border: rgba(0, 0, 0, 0.08); + --md-shadow: 0 10px 36px -10px rgba(0,0,0,0.18); + --md-toolbar-bg: rgba(248, 249, 250, 0.92); + --md-textarea-bg: #ffffff; + --md-preview-bg: #ffffff; + --md-code-bg: rgba(243, 244, 246, 1); + --md-code-text: #1f2937; + --md-accent: #3b82f6; + --md-muted: #6b7280; + --md-radius: 10px; + --md-font: -apple-system, "Segoe UI", "PingFang SC", sans-serif; + --md-mono: "SF Mono", "Consolas", monospace; +} +``` + +### 注册自定义主题 + +```javascript +import { themeUtils } from '@metona-team/metona-editor'; + +themeUtils.registerTheme('ocean', { + bg: '#001122', + text: '#aabbcc', + border: '#003344', + accent: '#00ddff', + // 未提供字段从 light 主题继承 +}); + +themeUtils.applyTheme('ocean'); +themeUtils.hasTheme('ocean'); // true +themeUtils.unregisterTheme('ocean'); // 移除（内置主题不可移除） +``` + +### 主题监听 + +```javascript +const unsub = themeUtils.addThemeListener((theme, resolved) => { + console.log('主题切换:', theme, '=>', resolved); +}); +unsub(); // 取消监听 +``` + +### 持久化 + +主题会自动保存到 `localStorage`，key 为 `metona-editor-theme`。`initTheme()` 在库加载时自动调用。 + +--- + +## 国际化 + +### 切换语言 + +```javascript +MeEditor.setLocale('en-US'); +MeEditor.setLocale('zh-CN'); +``` + +### 翻译函数 + +```javascript +import { i18nUtils } from '@metona-team/metona-editor'; + +i18nUtils.t('bold'); // => '粗体'（zh-CN） +i18nUtils.t('bold'); // => 'Bold'（en-US） + +// 插值 +i18nUtils.t('greeting', { name: '世界' }); +// 翻译值 '你好，{name}！' => '你好，世界！' +``` + +### 添加自定义语言 + +```javascript +i18nUtils.addTranslations('ja', { + bold: '太字', + italic: '斜体', + // ...其他翻译 +}); + +MeEditor.setLocale('ja'); +``` + +### 格式化 + +```javascript +i18nUtils.formatNumber(1234567); // => '1,234,567' +i18nUtils.formatCurrency(99.99, 'USD'); // => '$99.99' +i18nUtils.formatDate('2024-01-15'); // => '1/15/2024' +i18nUtils.formatNumber(0.5, { style: 'percent' }); // => '50%' +``` + +### 语言元信息 + +```javascript +i18nUtils.getSupportedLocales(); // => ['zh-CN', 'en-US', ...] +i18nUtils.isLocaleSupported('zh-CN');// => true +i18nUtils.getLocaleName('zh-CN'); // => '简体中文' +i18nUtils.getLocaleDirection('ar'); // => 'rtl' +``` + +### 语言监听 + +```javascript +const unsub = i18nUtils.addLocaleListener((locale) => { + console.log('语言切换:', locale); +}); +unsub(); +``` + +语言会自动保存到 `localStorage`，key 为 `metona-editor-locale`。 + +--- + +## Markdown 解析器 + +MetonaEditor 内置自研轻量解析器，支持 CommonMark 子集 + GFM 扩展： + +### 支持的语法 + +| 语法 | 示例 | 输出 | +|------|------|------| +| 标题 | `# H1` `## H2` | `` |
+| 粗体 | `**bold**` `__bold__` | `` |
+| 斜体 | `*italic*` `_italic_` | `` |
+| 删除线 | `~~text~~` | `` |
+| 行内代码 | `` `code` `` | `` |
+| 代码块 | ` ```lang ` | `` |
+| 引用 | `> quote` | `` |
+| 无序列表 | `- item` / `* item` / `+ item` | `
` |
+| 表格 | `\| a \| b \|` | `