![\"Vditor\"](\"https://b3log.org/images/brand/vditor-128.png\")
\n\n\n易于使用的 Markdown 编辑器，为适配不同的应用场景而生\n
\n
![](\"https://img.shields.io/badge/license-MIT-orange.svg?style=flat-square\"){kind=icon}
\n![\"npm](\"https://img.shields.io/bundlephobia/minzip/vditor?style=flat-square&color=blueviolet\")
\n![](\"https://img.shields.io/npm/v/vditor.svg?style=flat-square\")
\n
![](\"https://img.shields.io/npm/dt/vditor.svg?style=flat-square&color=97ca00\")
\n![](\"https://hits.b3log.org/Vanessa219/vditor.svg\")
\n
![](\"https://img.shields.io/github/watchers/Vanessa219/vditor.svg?label=Watchers&style=social\")
\n![](\"https://img.shields.io/github/stars/Vanessa219/vditor.svg?label=Stars&style=social\")
\n![](\"https://img.shields.io/github/forks/Vanessa219/vditor.svg?label=Forks&style=social\")
\n![](\"https://img.shields.io/github/followers/vanessa219.svg?label=Followers&style=social\")
\n\n\n\n
\n易于使用的 Markdown 编辑器，为适配不同的应用场景而生\n
\n\n
\n\n\n
\n\n\n\n\n
\n🔥 欢迎观摩我们的另一个开源项目 思源笔记\n
\n\n## 💡 简介\n\n[Vditor](https://b3log.org/vditor) 是一款浏览器端的 Markdown 编辑器，支持所见即所得、即时渲染（类似 Typora）和分屏预览模式。它使用 TypeScript 实现，支持原生 JavaScript 以及 Vue、React、Angular 和 Svelte 等框架。\n\n欢迎到 [Vditor 官方讨论区](https://ld246.com/tag/vditor)了解更多。同时也欢迎关注 B3log 开源社区微信公众号 `B3log开源`：\n\n\n\n## 🗺️ 背景\n\n随着 Markdown 排版方式的普及，越来越多的应用开始集成 Markdown 编辑器。目前主流可集成的 Markdown 编辑器现状如下：\n\n* 有的仅支持分屏预览，即编辑区和预览区分离\n* 有的同时支持所见即所得和分屏预览，但所见即所得模式下不能完整支持 Markdown 语法排版\n* 几乎没有类似 Typora 的即时渲染\n\n而这三点恰好对应了三种应用场景：\n\n* 分屏预览：适配传统的 Markdown 使用场景，适合大屏下编辑排版\n* 所见即所得：对不熟悉 Markdown 的用户友好，熟悉 Markdown 的用户也可以无缝使用\n* 即时渲染：理论上这是最为优雅的 Markdown 编辑方式，让熟悉 Markdown 的用户能够更专注于内容创作\n\n所以，一个能够**适配应用场景**的 Markdown 编辑器至关重要，它需要考虑到：\n\n* 传统 Markdown 用户的使用场景，提供分屏预览\n* 富文本编辑用户的使用场景，提供所见即所得\n* 高阶 Markdown 用户的使用场景，提供即时渲染\n\nVditor 在这些方面做了努力，希望能为现代化的通用 Markdown 编辑领域做出一些贡献。\n\n## ✨ 特性\n\n* 支持三种编辑模式：所见即所得（wysiwyg）、即时渲染（ir）、分屏预览（sv）\n* 支持大纲、数学公式、脑图、图表、流程图、甘特图、时序图、数字波形图、五线谱、[多媒体](https://ld246.com/article/1589813914768)、语音阅读、标题锚点、代码高亮及复制、graphviz 渲染、[plantuml](https://plantuml.com)UML图\n* 导出、图片懒加载、任务列表、多平台预览、多主题切换、复制到微信公众号/知乎功能\n* 实现 CommonMark 和 GFM 规范，可对 Markdown 进行格式化和语法树查看，并支持[10+项](https://ld246.com/article/1549638745630#options-preview-markdown)配置\n* 工具栏包含 36+ 项操作，除支持扩展外还可对每一项中的[快捷键](https://ld246.com/article/1582778815353)、提示、提示位置、图标、点击事件、类名、子工具栏进行自定义\n* 表情/at/话题等自动补全扩展\n* 可使用拖拽、剪切板粘贴上传，显示实时上传进度，支持 CORS 跨域上传\n* 实时保存内容，防止意外丢失\n* 录音支持，用户可直接发布语音\n* 粘贴 HTML 自动转换为 Markdown，如粘贴中包含外链图片可通过指定接口上传到服务器\n* 支持主窗口大小拖拽、字符计数\n* 多主题支持，内置黑白绿三套主题\n* 多语言支持，内置中、英、韩文本地化\n* 支持主流浏览器，对移动端友好\n\n\n\n\n\n## 🔮 编辑模式\n\n### 所见即所得（WYSIWYG）\n\n*所见即所得*模式对不熟悉 Markdown 的用户较为友好，熟悉 Markdown 的话也可以无缝使用。\n\n\n\n### 即时渲染（IR）\n\n*即时渲染*模式对熟悉 Typora 的用户应该不会感到陌生，理论上这是最优雅的 Markdown 编辑方式。\n\n\n\n### 分屏预览（SV）\n\n传统的*分屏预览*模式适合大屏下的 Markdown 编辑。\n\n\n\n## 🍱 语法支持\n\n* 所有 CommonMark 语法：分隔线、ATX 标题、Setext 标题、缩进代码块、围栏代码块、HTML 块、链接引用定义、段落、块引用、列表、反斜杠转义、HTML 实体、行级代码、强调、加粗、链接、图片、行级 HTML、硬换行、软换行和纯文本。\n* 所有 GFM 语法：表格、任务列表项、删除线、自动链接、XSS 过滤\n* 常用 Markdown 扩展语法：脚注、ToC、自定义标题 ID\n* 图表语法\n * 流程图、时序图、甘特图，通过 Mermaid 支持\n * Graphviz\n * 数字波形图，通过 WaveDrom 支持\n * 折线图、饼图、脑图等，通过 ECharts 支持\n* 五线谱：通过 abc.js 支持\n* 数学公式：数学公式块、行级数学公式，通过 MathJax 和 KaTeX 支持\n* YAML Front Matter\n* 中文语境优化\n * 中西文之间插入空格\n * 术语拼写修正\n * 中文后跟英文逗号句号等标点替换为中文对应标点\n\n以上大部分特性可以通过开关配置是否启用，开发者可根据自己的应用场景选择搭配。\n\n## 🗃 案例\n\n* [Sym](https://github.com/88250/symphony) 一款用 Java 实现的现代化社区（论坛/BBS/社交网络/博客）平台\n* [Solo](https://github.com/88250/solo) & [Pipe](https://github.com/88250/pipe) B3log 分布式社区的博客端节点，欢迎加入下一代社区网络\n* [Tditor](https://tditor.com) 基于React、Vditor、Springboot，一款打造极致文字创作体验的在线Markdown编辑平台\n* [Arya](https://github.com/nicejade/markdown-online-editor) 基于 Vue、Vditor，所构建的在线 Markdown 编辑器\n* [更多案例](https://github.com/Vanessa219/vditor/network/dependents?package_id=UGFja2FnZS0zMTY2Mzg4MzE%3D)\n\n## 🛠️ 使用文档\n\n### CommonJS\n\n* 安装依赖\n\n```shell\nnpm install vditor --save\n```\n\n* 在代码中引入并初始化对象，可参考 [index.js](https://github.com/Vanessa219/vditor/blob/master/demo/index.js)\n\n```ts\nimport Vditor from 'vditor'\nimport \"~vditor/src/assets/less/index\"\n\nconst vditor = new Vditor(id, {options...})\n```\n\n### HTML script\n\n* 在 HTML 中插入 CSS 和 JavaScript，可参考 [demo](https://b3log.org/vditor/demo/index.html)\n\n```html\n\n\n\n```\n\n### 示例代码\n\n* [官方示例](https://b3log.org/vditor/demo/index.html) / [示例源码](https://github.com/Vanessa219/b3log-index/tree/master/src/vditor)\n* [CommonJS Editor](https://github.com/Vanessa219/vditor/blob/master/demo/index.js)\n* [CommonJS Render](https://github.com/Vanessa219/vditor/blob/master/demo/render.js)\n* [在Svelte中使用](https://github.com/HerbertHe/svelte-vditor-demo)\n\n### 主题\n\n#### 编辑器主题\n\n编辑器所展现的外观。内置classic，dark 2 套主题。\n\n* 编辑器初始化时可通过 `options.theme` 设置内置主题\n* 初始化完成后可通过 `setTheme` 更新编辑器主题\n* 可通过修改 [index.less](https://github.com/Vanessa219/vditor/blob/master/src/assets/less/index.less) 中的变量对主题颜色进行定制\n* 可参考现有结构和类名在原有基础上进行修改\n\n#### 内容主题\n\nMarkdown 输出的 HTML 所展现的外观。内置 ant-design, light，dark，wechat 4 套主题。支持内容主题扩展接口。\n\n* 需在显示元素上添加 `class=\"vditor-reset\"`\n* 编辑器初始化时可通过 `options.preview.theme` 设置内置或自己开发的主题列表\n* 内容渲染初始化时可通过 `IPreviewOptions.theme` 设置内置或自己开发的主题\n* 初始化完成后可通过 `setTheme` 或 `setContentTheme` 更新内容主题\n\n#### 代码主题\n\n代码块所展现的外观。内置 github 等 36 套主题。\n\n* 编辑器初始化时可通过 `options.preview.hljs` 对代码块样式、行号、是否启用进行设置\n* 内容渲染初始化时可通过 `IPreviewOptions.hljs` 对代码块样式、行号、是否启用进行设置\n* 初始化完成后可通过 `setTheme` 或 `setCodeTheme` 更新代码主题\n\n### API\n\n#### id\n\n可填入元素 `id` 或元素自身 `HTMLElement`\n\n⚠️：当填入元素自身的 `HTMLElement` 时需设置 `options.cache.id` 或将 `options.cache.enable` 设置为 `false`\n\n#### options\n\n| | 说明 | 默认值 |\n| - | - | - |\n| i18n | 多语言，参见 ITips | - |\n| undoDelay | 历史记录间隔 | - |\n| after | 编辑器异步渲染完成后的回调方法 | - |\n| height | 编辑器总高度 | 'auto' |\n| minHeight | 编辑区域最小高度 | - |\n| width | 编辑器总宽度，支持 % | 'auto' |\n| placeholder | 输入区域为空时的提示 | '' |\n| lang | 语言种类：de_DE, en_US, es_ES, fr_FR, ja_JP, ko_KR, pt_BR, ru_RU, sv_SE, vi_VN, zh_CN, zh_TW | 'zh_CN' |\n| input(value: string) | 输入后触发 | - |\n| focus(value: string) | 聚焦后触发 | - |\n| blur(value: string) | 失焦后触发 | - |\n| keydown(event: KeyboardEvent) | 按下后触发 | - |\n| esc(value: string) | esc 按下后触发 | - |\n| ctrlEnter(value: string) | ⌘/ctrl+enter 按下后触发 | - |\n| select(value: string) | 编辑器中选中文字后触发 | - |\n| unSelect() | 编辑器中未选中文字后触发 | - |\n| tab | tab 键操作字符串，支持 `\\t` 及任意字符串 | - |\n| typewriterMode | 是否启用打字机模式 | false |\n| cdn | 配置自建 CDN 地址 | `https://unpkg.com/vditor@${VDITOR_VERSION}` |\n| mode | 可选模式：sv, ir, wysiwyg | 'ir' |\n| debugger | 是否显示日志 | false |\n| value | 编辑器初始化值 | '' |\n| theme | 主题：classic, dark | 'classic' |\n| icon | 图标风格：ant, material | 'ant' |\n| customRenders: {language: string, render: (element: HTMLElement, vditor: IVditor) => void}[] | 自定义渲染器 | [] |\n| customWysiwygToolbar(type: TWYSISYGToolbar, element: HTMLElement): void | 对 wysiwyg 模式下的工具栏进行自定义 | - |\n| customWysiwygMobileToolbar(type: TWYSISYGToolbar, element: HTMLElement): void | 对移动端 wysiwyg 模式下的工具栏进行自定义，未添加菜单项时不显示入口 | - |\n\n#### options.toolbar\n\n* 工具栏，可使用 name 进行简写： `toolbar: ['emoji', 'br', 'bold', '|', 'line']` 。默认值参见 [src/ts/util/Options.ts](https://github.com/Vanessa219/vditor/blob/master/src/ts/util/Options.ts)\n* name 可枚举为： `emoji`，`headings`，`bold`，`italic`，`strike`，`|`，`line`，`quote`，`list`，`ordered-list`，`check` ,`outdent` ,`indent`，`code`，`inline-code`，`insert-after`，`insert-before` ,`undo`，`redo`，`upload`，`link`，`table`，`record`，`edit-mode`，`both`，`preview`，`fullscreen`，`outline`，`code-theme`，`content-theme`，`export`, `devtools`，`info`，`help`，`br`\n* 当 `name` 不在枚举中时，可以添加自定义按钮，格式如下：\n\n```js\nnew Vditor('vditor', {\n toolbar: [\n {\n hotkey: '⇧⌘S',\n name: 'sponsor',\n tipPosition: 's',\n tip: '成为赞助者',\n className: 'right',\n icon: '',\n click () {alert('捐赠地址：https://ld246.com/sponsor')},\n }],\n})\n```\n\n| | 说明 | 默认值 |\n| - | - | - |\n| name | 唯一标示 | - |\n| icon | svg 图标 | - |\n| tip | 提示 | - |\n| tipPosition | 提示位置：'n', 'ne', 'nw', 's', 'se', 'sw', 'w', 'e' | - |\n| hotkey | 快捷键，格式为⇧⌘/⌘/⌥⌘| - |\n| suffix | 插入编辑器中的后缀 | - |\n| prefix | 插入编辑器中的前缀 | - |\n| click(event: Event, vditor: IVditor) | 自定义按钮点击时触发的事件 | - |\n| className | 样式名 | '' |\n| toolbar?: Array