vditor

<img alt="Vditor" src="https://b3log.org/images/brand/vditor-128.png" /> 易于使用的 Markdown 编辑器，为适配不同的应用场景而生 <a title="MIT" target="_blank" href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a> <a title="npm bundle size" target="_blank" href="https://www.npmjs.com/package/vditor"><img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/vditor?style=flat-square&color=blueviolet"></a> <a title="Version" target="_blank" href="https://www.npmjs.com/package/vditor"><img src="https://img.shields.io/npm/v/vditor.svg?style=flat-square"></a> <a title="Downloads" target="_blank" href="https://www.npmjs.com/package/vditor"><img src="https://img.shields.io/npm/dt/vditor.svg?style=flat-square&color=97ca00"></a> <a title="jsdelivr" target="_blank" href="https://www.jsdelivr.com/package/npm/vditor"><img src="https://data.jsdelivr.com/v1/package/npm/vditor/badge"/></a> <a title="Hits" target="_blank" href="https://github.com/88250/hits"><img src="https://hits.b3log.org/Vanessa219/vditor.svg"></a> <a title="GitHub Watchers" target="_blank" href="https://github.com/Vanessa219/vditor/watchers"><img src="https://img.shields.io/github/watchers/Vanessa219/vditor.svg?label=Watchers&style=social"></a> <a title="GitHub Stars" target="_blank" href="https://github.com/Vanessa219/vditor/stargazers"><img src="https://img.shields.io/github/stars/Vanessa219/vditor.svg?label=Stars&style=social"></a> <a title="GitHub Forks" target="_blank" href="https://github.com/Vanessa219/vditor/network/members"><img src="https://img.shields.io/github/forks/Vanessa219/vditor.svg?label=Forks&style=social"></a> <a title="Author GitHub Followers" target="_blank" href="https://github.com/vanessa219"><img src="https://img.shields.io/github/followers/vanessa219.svg?label=Followers&style=social"></a> <a href="https://github.com/Vanessa219/vditor/blob/master/README_en_US.md">English</a>  |  <a href="https://b3log.org/vditor/demo/index.html">Demo</a>

💡 简介

Vditor 是一款浏览器端的 Markdown 编辑器，支持所见即所得、即时渲染（类似 Typora）和分屏预览模式。它使用 TypeScript 实现，支持原生 JavaScript 以及 Vue、React、Angular 和 Svelte 等框架。

欢迎到 Vditor 官方讨论区了解更多。同时也欢迎关注 B3log 开源社区微信公众号 B3log开源：

🗺️ 背景

随着 Markdown 排版方式的普及，越来越多的应用开始集成 Markdown 编辑器。目前主流可集成的 Markdown 编辑器现状如下：

有的仅支持分屏预览，即编辑区和预览区分离
有的同时支持所见即所得和分屏预览，但所见即所得模式下不能完整支持 Markdown 语法排版
几乎没有类似 Typora 的即时渲染

而这三点恰好对应了三种应用场景：

分屏预览：适配传统的 Markdown 使用场景，适合大屏下编辑排版
所见即所得：对不熟悉 Markdown 的用户友好，熟悉 Markdown 的用户也可以无缝使用
即时渲染：理论上这是最为优雅的 Markdown 编辑方式，让熟悉 Markdown 的用户能够更专注于内容创作

所以，一个能够适配应用场景的 Markdown 编辑器至关重要，它需要考虑到：

传统 Markdown 用户的使用场景，提供分屏预览
富文本编辑用户的使用场景，提供所见即所得
高阶 Markdown 用户的使用场景，提供即时渲染

Vditor 在这些方面做了努力，希望能为现代化的通用 Markdown 编辑领域做出一些贡献。

✨ 特性

支持三种编辑模式：所见即所得（wysiwyg）、即时渲染（ir）、分屏预览（sv）
支持大纲、数学公式、脑图、图表、流程图、甘特图、时序图、五线谱、多媒体、语音阅读、标题锚点、代码高亮及复制、graphviz 渲染、plantumlUML图
导出、图片懒加载、任务列表、多平台预览、多主题切换、复制到微信公众号/知乎功能
实现 CommonMark 和 GFM 规范，可对 Markdown 进行格式化和语法树查看，并支持10+项配置
工具栏包含 36+ 项操作，除支持扩展外还可对每一项中的快捷键、提示、提示位置、图标、点击事件、类名、子工具栏进行自定义
表情/at/话题等自动补全扩展
可使用拖拽、剪切板粘贴上传，显示实时上传进度，支持 CORS 跨域上传
实时保存内容，防止意外丢失
录音支持，用户可直接发布语音
粘贴 HTML 自动转换为 Markdown，如粘贴中包含外链图片可通过指定接口上传到服务器
支持主窗口大小拖拽、字符计数
多主题支持，内置黑白绿三套主题
多语言支持，内置中、英、韩文本地化
支持主流浏览器，对移动端友好

🔮 编辑模式

所见即所得（WYSIWYG）

所见即所得模式对不熟悉 Markdown 的用户较为友好，熟悉 Markdown 的话也可以无缝使用。

vditor-wysiwyg

即时渲染（IR）

即时渲染模式对熟悉 Typora 的用户应该不会感到陌生，理论上这是最优雅的 Markdown 编辑方式。

vditor-ir

分屏预览（SV）

传统的分屏预览模式适合大屏下的 Markdown 编辑。

vditor-sv

🍱 语法支持

所有 CommonMark 语法：分隔线、ATX 标题、Setext 标题、缩进代码块、围栏代码块、HTML 块、链接引用定义、段落、块引用、列表、反斜杠转义、HTML 实体、行级代码、强调、加粗、链接、图片、行级 HTML、硬换行、软换行和纯文本。
所有 GFM 语法：表格、任务列表项、删除线、自动链接、XSS 过滤
常用 Markdown 扩展语法：脚注、ToC、自定义标题 ID
图表语法
- 流程图、时序图、甘特图，通过 Mermaid 支持
- Graphviz
- 折线图、饼图、脑图等，通过 ECharts 支持
五线谱：通过 abc.js 支持
数学公式：数学公式块、行级数学公式，通过 MathJax 和 KaTeX 支持
YAML Front Matter
中文语境优化
- 中西文之间插入空格
- 术语拼写修正
- 中文后跟英文逗号句号等标点替换为中文对应标点

以上大部分特性可以通过开关配置是否启用，开发者可根据自己的应用场景选择搭配。

🗃 案例

Sym 一款用 Java 实现的现代化社区（论坛/BBS/社交网络/博客）平台
Solo & Pipe B3log 分布式社区的博客端节点，欢迎加入下一代社区网络
Tditor 基于React、Vditor、Springboot，一款打造极致文字创作体验的在线Markdown编辑平台
Arya 基于 Vue、Vditor，所构建的在线 Markdown 编辑器
更多案例

🛠️ 使用文档

CommonJS

安装依赖

npm install vditor --save

在代码中引入并初始化对象，可参考 index.js

import Vditor from 'vditor'
import "~vditor/src/assets/less/index"

const vditor = new Vditor(id, {options...})

HTML script

在 HTML 中插入 CSS 和 JavaScript，可参考 demo

<!-- ⚠️生产环境请指定版本号，如 https://unpkg.com/vditor@x.x.x/dist... -->
<link rel="stylesheet" href="https://unpkg.com/vditor/dist/index.css" />
<script src="https://unpkg.com/vditor/dist/index.min.js"></script>

示例代码

主题

编辑器主题

编辑器所展现的外观。内置classic，dark 2 套主题。

编辑器初始化时可通过 options.theme 设置内置主题
初始化完成后可通过 setTheme 更新编辑器主题
可通过修改 index.less 中的变量对主题颜色进行定制
可参考现有结构和类名在原有基础上进行修改

内容主题

Markdown 输出的 HTML 所展现的外观。内置 ant-design, light，dark，wechat 4 套主题。支持内容主题扩展接口。

需在显示元素上添加 class="vditor-reset"
编辑器初始化时可通过 options.preview.theme 设置内置或自己开发的主题列表
内容渲染初始化时可通过 IPreviewOptions.theme 设置内置或自己开发的主题
初始化完成后可通过 setTheme 或 setContentTheme 更新内容主题

代码主题

代码块所展现的外观。内置 github 等 36 套主题。

编辑器初始化时可通过 options.preview.hljs 对代码块样式、行号、是否启用进行设置
内容渲染初始化时可通过 IPreviewOptions.hljs 对代码块样式、行号、是否启用进行设置
初始化完成后可通过 setTheme 或 setCodeTheme 更新代码主题

API

id

可填入元素 id 或元素自身 HTMLElement

⚠️：当填入元素自身的 HTMLElement 时需设置 options.cache.id 或将 options.cache.enable 设置为 false

options

	说明	默认值
i18n	多语言，参见 ITips	-
undoDelay	历史记录间隔	-
after	编辑器异步渲染完成后的回调方法	-
height	编辑器总高度	'auto'
minHeight	编辑区域最小高度	-
width	编辑器总宽度，支持 %	'auto'
placeholder	输入区域为空时的提示	''
lang	语言种类：en_US, fr_FR, pt_BR, ja_JP, ko_KR, ru_RU, sv_SE, zh_CN, zh_TW	'zh_CN'
input(value: string)	输入后触发	-
focus(value: string)	聚焦后触发	-
blur(value: string)	失焦后触发	-
keydown(event: KeyboardEvent)	按下后触发	-
esc(value: string)	<kbd>esc</kbd> 按下后触发	-
ctrlEnter(value: string)	<kbd>⌘/ctrl+enter</kbd> 按下后触发	-
select(value: string)	编辑器中选中文字后触发	-
tab	<kbd>tab</kbd> 键操作字符串，支持 `\t` 及任意字符串	-
typewriterMode	是否启用打字机模式	false
cdn	配置自建 CDN 地址	`https://unpkg.com/vditor@${VDITOR_VERSION}`
mode	可选模式：sv, ir, wysiwyg	'ir'
debugger	是否显示日志	false
value	编辑器初始化值	''
theme	主题：classic, dark	'classic'
icon	图标风格：ant, material	'ant'
customRenders: {language: string, render: (element: HTMLElement, vditor: IVditor) => void}[]	自定义渲染器	[]