API 文档

安装与引入

# npm 安装
npm install @metona-team/metona-editor

// TypeScript / 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: '',              placeholder: '',

  // 视图
  mode: 'split',          height: 400,
  toolbar: DEFAULT_TOOLBAR, wordCount: true,
  lineNumbers: true,       outline: false,

  // 行为
  autofocus: false,       spellcheck: false,
  readOnly: false,        tabSize: 2,
  historyLimit: 100,      historyDebounce: 400,
  syncScroll: true,       autoBrackets: true,
  zenMode: false,         wordWrap: true,

  // 主题 / 语言
  theme: 'auto',          locale: 'zh-CN',

  // 钩子
  render: null,           highlight: null,
  sanitize: null,

  // 外观
  className: '',          style: {},

  // 插件 / 回调
  plugins: [],
  onChange: null,         onInput: null,
  onFocus: null,          onBlur: null,
  onSave: null,           onModeChange: null,
  onFullscreen: null,    onCreate: null,
  onDestroy: null,        onLinkClick: null,
});

工具栏

// 默认完整工具栏
MeEditor.create(container, { toolbar: true });

// 隐藏
MeEditor.create(container, { toolbar: false });

// 自定义 | 为分隔符
MeEditor.create(container, { toolbar: ['bold', 'italic', '|', 'undo', 'redo'] });

可用动作：

bolditalicstrikethroughunderlinecode h1h2h3quoteulol indentoutdenthr linkimagetable undoredo editsplitpreviewfullscreen

实例 API

内容操作

editor.getValue();                    // => string
editor.setValue(md, { silent });      // => this
editor.getHTML();                     // => string
editor.refresh();                     // 强制重渲染
editor.insert(text, { replace });     // => this
editor.wrap(before, after);           // => this
editor.focus(); blur();

命令执行

editor.exec(action) // => this, 支持链式

历史栈

editor.undo();    editor.redo();
editor.canUndo();  editor.canRedo();

模式 / 全屏 / Zen

editor.setMode('split');  editor.getMode();
editor.toggleFullscreen();  isFullscreen();  exitFullscreen();
editor.toggleZen();  isZen();
editor.toggleWordWrap();  setWordWrap(true);  isWordWrap();

统计与状态

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

启用 / 禁用 / 只读

editor.enable();  disable();  isDisabled();
editor.setReadOnly(true);  isReadOnly();

事件系统

全局钩子

插件管理

editor.use(plugin, options);      // 安装
editor.unuse(name);               // 卸载
editor.getPlugins();              // 已安装列表
editor.addToolbarButton(config);  // 追加按钮

快捷键管理

editor.registerShortcut('Ctrl+Shift+T', handler, 'desc');
editor.unregisterShortcut('Ctrl+Shift+T');
editor.getShortcuts();

生命周期 / Toast

editor.destroy();  isDestroyed();
editor.toast(msg, { type, duration, animation });

静态 API

import MeEditor from '@metona-team/metona-editor';

// 工厂函数
MeEditor.create(container, options);

// 全局默认插件
MeEditor.use('autoSave', { delay: 2000 });
MeEditor.use(customPlugin);

// 全局钩子
MeEditor.on('beforeCreate', (editor) => {});
MeEditor.off('beforeCreate', handler);

// 全局主题 / 语言
MeEditor.setTheme('dark');
MeEditor.setLocale('en-US');

// 解析器独立使用
import { parseMarkdown, parseTokens, renderTokens } from '@metona-team/metona-editor';

解析器语法参考

XSS 防护

所有文本经 escapeHTML 转义，URL 过滤 javascript: / vbscript: / file: / 非图片 data:，提供 sanitize 钩子。

解析器 API

parseTokens / renderTokens

import { parseTokens, renderTokens } from '@metona-team/metona-editor';

const { tokens, footnotes } = parseTokens('# Hello\n\n**world**');
tokens.unshift({ type: 'hr' });  // 渲染前变换
const html = renderTokens(tokens, env, footnotes);

registerBlockHandler

import { registerBlockHandler } from '@metona-team/metona-editor';
registerBlockHandler({
  name: 'custom', priority: 8.5,
  test: (line) => line.match(/^:::/),
  parse: (lines, i, match) => ({ token: { type: 'alert' }, newIndex: j })
});

插件约定

const myPlugin = {
  name: 'myPlugin', description: '我的插件',
  install(editor) { editor.on('change', this._onChange); },
  destroy(editor) { editor.off('change', this._onChange); },
};

预设插件

autoSave

editor.use('autoSave', { key: 'draft-key', delay: 1000 });
editor.restoreDraft();  editor.clearDraft();

exportTool

editor.use('exportTool');
editor.exportMarkdown('doc.md');  editor.exportHTML('doc.html');

searchReplace

editor.use('searchReplace');
// Ctrl+F 查找 / Ctrl+H 替换

imagePaste

editor.use('imagePaste');  // 粘贴图片自动转 base64

shortcutHelp

editor.use('shortcutHelp');  // 按 ? 弹出快捷键面板

fileSystem

editor.use('fileSystem');
editor.openFile();  editor.saveFile();  editor.saveFileAs();

主题系统

// 实例级
editor.setTheme('dark');  editor.getTheme();

// 注册自定义
import { themeUtils } from '@metona-team/metona-editor';
themeUtils.registerTheme('ocean', { extends: 'dark', accent: '#00ddff' });

// 外部跟随
editor.getThemeContext().adopt();  // 从父容器继承

// CSS 变量导出
themeUtils.exportCSSVars();  themeUtils.getCSSVariable('accent');

国际化

// 切换
editor.setLocale('en-US');  MeEditor.setLocale('zh-CN');

// 添加翻译
import { i18nUtils } from '@metona-team/metona-editor';
i18nUtils.addTranslations('ja', { bold: '太字' });

// 远程加载
await i18nUtils.loadRemote('/locales/ja.json', 'ja');

// 格式化
i18nUtils.formatNumber(1234567);
i18nUtils.formatDate('2024-01-15');