1. Vditor编辑器概述
1.1 编辑器的基本功能
Vditor 是一款功能强大的浏览器端 Markdown 编辑器，它提供了多种编辑模式和丰富的功能，使得用户可以高效地进行文本编辑和格式化。以下是 Vditor 的一些基本功能：
- 所见即所得（WYSIWYG）：用户在编辑时可以直接看到最终的渲染效果，类似于使用富文本编辑器，但支持 Markdown 语法。
- 即时渲染（IR）：类似于 Typora 的渲染模式，用户在输入 Markdown 文本时，编辑器会实时将其渲染为 HTML 格式，提供即时的视觉反馈。
- 分屏预览（SV）：编辑器提供一个分屏界面，一边是 Markdown 源码，另一边是实时渲染的 HTML 预览，方便用户对照编辑和预览。
- 语法高亮：支持 Markdown 语法的高亮显示，帮助用户更清晰地识别和编辑文本。
- 扩展功能：支持多种 Markdown 扩展语法，如表格、任务列表、代码块等，以及自定义工具栏和快捷键。
1.2 支持的渲染模式
Vditor 提供了三种主要的渲染模式，每种模式都有其独特的特点和适用场景：
- 所见即所得（WYSIWYG）模式：在这种模式下，用户在编辑文本时，编辑器会实时显示最终的渲染效果，类似于使用富文本编辑器。这种模式适合不熟悉 Markdown 语法的用户，或者需要频繁调整格式和布局的场景。
- 即时渲染（IR）模式：这种模式下，用户在输入 Markdown 文本时，编辑器会实时将其渲染为 HTML 格式，提供即时的视觉反馈。这种模式适合需要快速查看渲染效果的用户。
- 分屏预览（SV）模式：在这种模式下，编辑器分为两个部分，一边是 Markdown 源码，另一边是实时渲染的 HTML 预览。这种模式适合需要同时查看和编辑源码和渲染效果的用户。
1.3 技术实现与支持框架
Vditor 使用 TypeScript 实现，这使得它在类型安全和代码维护方面具有优势。此外，Vditor 支持多种前端框架，包括：
- 原生 JavaScript：可以直接在任何支持 JavaScript 的网页中使用。
- Vue：提供了 Vue 组件，方便在 Vue 项目中集成和使用。
- React：提供了 React 组件，可以在 React 项目中轻松集成。
- Angular：提供了 Angular 组件，支持在 Angular 项目中使用。
这些支持框架的实现，使得 Vditor 能够适应不同的开发环境和需求，为开发者提供了极大的灵活性和便利性。
通过上述介绍，我们可以看到 Vditor 不仅功能强大，而且具有高度的灵活性和可扩展性，能够满足不同用户和开发者的需求。 ## 2. 编辑模式详解
Vditor 提供了三种主要的编辑模式，分别是所见即所得（WYSIWYG）、即时渲染（IR）和分屏预览（SV）。每种模式都有其独特的特点和适用场景，用户可以根据自己的需求选择最合适的模式。
2.1 所见即所得（WYSIWYG）
所见即所得（What You See Is What You Get）模式是一种直观的编辑方式，用户在编辑时可以直接看到最终的渲染效果，无需预览即可知道文档的最终呈现形式。这种模式对于不熟悉 Markdown 语法的用户非常友好，同时也适合那些希望快速编辑文档的用户。
初始化代码示例
new Vditor('vditor', {"height": 360,"cache": { "enable": false },"value": "## 所见即所得（WYSIWYG）\n所见即所得模式对不熟悉 Markdown 的用户较为友好，熟悉 Markdown 的话也可以无缝使用。","mode": "wysiwyg"
});
特点
- 直观性：用户在编辑时可以直接看到最终的渲染效果。
- 易用性：适合不熟悉 Markdown 语法的用户。
- 无缝切换：熟悉 Markdown 的用户也可以无缝使用。
2.2 即时渲染（IR）
即时渲染（Instant Rendering）模式类似于 Typora 的编辑方式，用户在输入 Markdown 语法的同时，编辑器会实时渲染出最终的文档效果。这种模式理论上是最优雅的 Markdown 编辑方式，适合那些希望在编辑过程中就能看到文档最终效果的用户。
初始化代码示例
new Vditor('vditor', {"height": 360,"cache": { "enable": false },"value": "## 即时渲染（IR）\n即时渲染模式对熟悉 Typora 的用户应该不会感到陌生，理论上这是最优雅的 Markdown 编辑方式。","mode": "ir"
});
特点
- 实时渲染：用户在输入 Markdown 语法的同时，编辑器会实时渲染出最终的文档效果。
- 优雅性：理论上是最优雅的 Markdown 编辑方式。
- 熟悉感：对熟悉 Typora 的用户应该不会感到陌生。
2.3 分屏预览（SV）
分屏预览（Split View）模式将编辑区域和预览区域分开显示，用户在编辑 Markdown 文档的同时，可以在另一侧看到文档的实时预览效果。这种模式适合在大屏幕下进行 Markdown 编辑，用户可以同时看到编辑内容和预览效果，便于进行内容调整和格式优化。
初始化代码示例
new Vditor('vditor', {"height": 360,"cache": { "enable": false },"value": "## 分屏预览（SV）\n传统的分屏预览模式适合大屏下的 Markdown 编辑。","mode": "sv","preview": { "mode": "both" }
});
特点
- 分屏显示：编辑区域和预览区域分开显示。
- 实时预览：用户在编辑 Markdown 文档的同时，可以在另一侧看到文档的实时预览效果。
- 适合大屏：适合在大屏幕下进行 Markdown 编辑。
通过以上三种编辑模式的详细介绍，用户可以根据自己的需求选择最合适的编辑方式。无论是初学者还是资深用户，Vditor 都能提供高效、便捷的 Markdown 编辑体验。 ## 3. 语法支持与扩展功能
Vditor 编辑器不仅支持标准的 Markdown 语法，还扩展了多种语法和功能，以满足更丰富的编辑需求。以下是 Vditor 支持的主要语法和扩展功能。
3.1 CommonMark 语法
CommonMark 是一种标准化的 Markdown 语法规范，旨在消除不同 Markdown 解析器之间的差异。Vditor 严格遵循 CommonMark 规范，确保用户在不同平台上都能获得一致的渲染效果。
3.1.1 标题
在 CommonMark 中，标题通过在文本前添加 # 来定义，# 的数量表示标题的级别。例如：
# 一级标题
## 二级标题
### 三级标题
3.1.2 列表
列表分为有序列表和无序列表。无序列表使用 -、+ 或 * 作为列表项标记，有序列表使用数字加 . 作为列表项标记。例如：
- 无序列表项1
- 无序列表项21. 有序列表项1
2. 有序列表项2
3.1.3 代码块
代码块可以通过在代码前后添加三个反引号（```）来定义，也可以通过缩进四个空格或一个制表符来定义。例如：
```javascript
console.log('Hello, Vditor!');
```
3.2 GFM 语法
GFM（GitHub Flavored Markdown） 是 GitHub 对标准 Markdown 的扩展，增加了一些实用的功能。Vditor 支持 GFM 语法，使得用户可以更方便地编写适合在 GitHub 上展示的文档。
3.2.1 任务列表
任务列表允许用户创建带有复选框的列表项。例如：
- [x] 已完成任务
- [ ] 未完成任务
3.2.2 表格
GFM 支持通过简单的语法创建表格。例如：
| 列1 | 列2 | 列3 |
| --- | --- | --- |
| 数据1 | 数据2 | 数据3 |
3.2.3 删除线
删除线可以通过在文本前后添加两个波浪线（~~）来实现。例如：
~~被删除的文本~~
3.3 Markdown 扩展语法
Vditor 还支持多种 Markdown 扩展语法，以提供更丰富的编辑功能。
3.3.1 数学公式
Vditor 支持通过 LaTeX 语法插入数学公式。例如：
$$
E = mc^2
$$
3.3.2 流程图
Vditor 支持通过特定的语法插入流程图。例如：
```mermaid
graph TD;A-->B;A-->C;B-->D;C-->D;
#### 3.3.3 甘特图Vditor 支持通过特定的语法插入甘特图。例如：```markdown
```mermaid
ganttdateFormat YYYY-MM-DDtitle 甘特图示例section 任务1任务1 :a1, 2024-01-01, 30dsection 任务2任务2 :after a1, 20d
### 3.4 工具栏扩展与自定义Vditor 的工具栏提供了丰富的操作选项，并且支持扩展和自定义。#### 3.4.1 工具栏操作Vditor 的工具栏包含 36+ 项操作，包括加粗、斜体、插入链接、插入图片等常用操作。例如：```javascript
new Vditor('vditor', {toolbar: [{name: 'bold',tip: '加粗',tipPosition: 's'},{name: 'italic',tip: '斜体',tipPosition: 's'}]
});
3.4.2 自定义工具栏
用户可以自定义工具栏的每一项，包括快捷键、提示、提示位置、图标、点击事件、类名、子工具栏等。例如：
new Vditor('vditor', {toolbar: [{name: 'custom',tip: '自定义操作',tipPosition: 's',icon: '<svg>...</svg>',click: function() {// 自定义操作}}]
});
通过以上介绍，我们可以看到 Vditor 编辑器不仅支持标准的 Markdown 语法，还提供了丰富的扩展功能和灵活的工具栏自定义选项，使得用户可以更高效地进行文档编辑和内容创作。 ## 4. 在Vue中的应用
Vditor 是一款功能强大的 Markdown 编辑器，支持多种渲染模式，并且可以轻松集成到 Vue 项目中。本节将详细介绍如何在 Vue2 和 Vue3 项目中安装、配置和使用 Vditor 组件。
4.1 Vue2中的安装与配置
在 Vue2 项目中使用 Vditor，首先需要安装 Vditor 依赖包。可以通过 npm 或 yarn 进行安装：
npm install vditor --save
或
yarn add vditor
安装完成后，可以在 Vue 组件中引入并初始化 Vditor。以下是一个简单的示例：
<template><div id="vditor"></div>
</template><script>
import Vditor from 'vditor'
import 'vditor/dist/index.css'export default {mounted() {this.initVditor()},methods: {initVditor() {const vditor = new Vditor('vditor', {height: 300,placeholder: '请输入内容...',toolbar: ['emoji','headings','bold','italic','strike','link','|','list','ordered-list','check','outdent','indent','|','quote','line','code','inline-code','insert-before','insert-after','|','upload','record','table','|','undo','redo','|','fullscreen','preview','outline','code-theme','content-theme','export','devtools','info','help'],after() {vditor.setValue('欢迎使用 Vditor!')}})}}
}
</script>
4.2 Vue3中的安装与配置
在 Vue3 项目中使用 Vditor，安装和引入的方式与 Vue2 类似。首先安装 Vditor：
npm install vditor --save
或
yarn add vditor
然后在 Vue3 组件中引入并初始化 Vditor：
<template><div ref="vditor"></div>
</template><script>
import { ref, onMounted } from 'vue'
import Vditor from 'vditor'
import 'vditor/dist/index.css'export default {setup() {const vditor = ref(null)onMounted(() => {initVditor()})const initVditor = () => {vditor.value = new Vditor(vditor.value, {height: 300,placeholder: '请输入内容...',toolbar: ['emoji','headings','bold','italic','strike','link','|','list','ordered-list','check','outdent','indent','|','quote','line','code','inline-code','insert-before','insert-after','|','upload','record','table','|','undo','redo','|','fullscreen','preview','outline','code-theme','content-theme','export','devtools','info','help'],after() {vditor.value.setValue('欢迎使用 Vditor!')}})}return { vditor }}
}
</script>
4.3 Vditor组件的详细使用
Vditor 提供了丰富的配置选项和 API 方法，可以根据需要进行自定义。以下是一些常用的配置和方法：
4.3.1 工具栏配置
Vditor 的工具栏可以通过 toolbar 选项进行自定义。例如，添加自定义按钮：
toolbar: ['emoji','headings','bold','italic','strike','link','|','list','ordered-list','check','outdent','indent','|','quote','line','code','inline-code','insert-before','insert-after','|','upload','record','table','|','undo','redo','|','fullscreen','preview','outline','code-theme','content-theme','export','help',{name: 'custom',tip: '自定义按钮',tipPosition: 's',icon: '<svg viewBox="0 0 1024 1024"><path d="M512 85.333333C276.266667 85.333333 85.333333 276.266667 85.333333 512s190.933333 426.666667 426.666667 426.666667 426.666667-190.933333 426.666667-426.666667S747.733333 85.333333 512 85.333333z m0 768c-188.544 0-341.333333-152.789333-341.333333-341.333333S323.456 170.666667 512 170.666667 853.333333 323.456 853.333333 512 700.544 853.333333 512 853.333333z m136.533333-443.733333l-170.666666 102.4-102.4 170.666667-68.266667-68.266667 102.4-170.666667 170.666667-102.4 68.266666 68.266667z"></path></svg>',click: () => {alert('自定义按钮点击事件');},},
]
4.3.2 插入内容
Vditor 提供了 insertValue 方法，用于在当前光标位置插入内容：
vditor.insertValue('插入的内容');
4.3.3 获取和设置内容
可以通过 getValue 和 setValue 方法获取和设置编辑器的内容：
const content = vditor.getValue();
vditor.setValue('新的内容');
4.3.4 事件监听
Vditor 支持多种事件监听，例如 input 事件：
vditor.on('input', () => {console.log('编辑器内容发生变化');
});
通过以上步骤和示例，开发者可以在 Vue 项目中轻松集成和使用 Vditor 编辑器，实现丰富的 Markdown 编辑功能。 ## 5. 开发与使用文档
5.1 安装依赖
在使用Vditor编辑器之前，首先需要在项目中安装相关的依赖。Vditor支持多种前端框架，如原生JavaScript、Vue、React和Angular。以下是安装Vditor的基本步骤：
使用npm安装
npm install vditor --save
使用yarn安装
yarn add vditor
安装完成后，你可以在项目中引入Vditor：
import Vditor from 'vditor';
import 'vditor/dist/index.css';
5.2 初始化对象
初始化Vditor对象是使用编辑器的第一步。以下是初始化Vditor的基本方法：
const vditor = new Vditor('vditor', {height: 360,toolbar: ['emoji','headings','bold','italic','strike','link','|','list','ordered-list','check','outdent','indent','|','quote','line','code','inline-code','insert-before','insert-after','|','upload','record','table','|','undo','redo','|','fullscreen','edit-mode',{name: 'more',toolbar: ['both','code-theme','content-theme','export','outline','preview','devtools','info','help']}]
});
在上述代码中，'vditor'是HTML中容器的ID，height设置了编辑器的高度，toolbar定义了工具栏的按钮。
5.3 HTML 中插入 CSS 和 JavaScript
为了在HTML中使用Vditor，你需要引入相关的CSS和JavaScript文件。以下是一个基本的HTML示例：
<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Vditor Example</title><link rel="stylesheet" href="https://unpkg.com/vditor/dist/index.css">
</head>
<body><div id="vditor"></div><script src="https://unpkg.com/vditor/dist/index.min.js"></script><script>const vditor = new Vditor('vditor', {height: 360,toolbar: ['emoji','headings','bold','italic','strike','link','|','list','ordered-list','check','outdent','indent','|','quote','line','code','inline-code','insert-before','insert-after','|','upload','record','table','|','undo','redo','|','fullscreen','edit-mode',{name: 'more',toolbar: ['both','code-theme','content-theme','export','outline','preview','devtools','info','help']}]});</script>
</body>
</html>
5.4 API 方法说明
Vditor提供了丰富的API方法，方便开发者对编辑器进行操作和控制。以下是一些常用的API方法：
获取编辑器内容
const content = vditor.getValue();
console.log(content);
设置编辑器内容
vditor.setValue('新的编辑器内容');
清空编辑器内容
vditor.clear();
禁用编辑器
vditor.disabled();
启用编辑器
vditor.enabled();
插入内容
vditor.insertValue('插入的内容');
上传文件
vditor.uploadFile();
这些API方法可以帮助你在不同的应用场景中更好地控制Vditor编辑器的行为。详细的API文档可以在Vditor的官方文档中找到。
通过以上步骤，你可以在项目中成功安装和使用Vditor编辑器，并利用其丰富的功能和灵活的API方法来满足不同的开发需求。 ## 6. 高级功能与配置
6.1 图片上传与处理
Vditor 提供了强大的图片上传功能，支持拖拽、剪切板粘贴上传，并显示实时上传进度。以下是关于图片上传与处理的详细配置和使用方法。
6.1.1 基本配置
首先，需要在 Vditor 的初始化选项中配置 upload 参数。以下是一个基本的配置示例：
const vditor = new Vditor('vditor', {upload: {url: 'https://your-upload-endpoint.com/upload',max: 10 * 1024 * 1024, // 最大上传文件大小为 10MBlinkToImgUrl: 'https://your-upload-endpoint.com/linkToImg',filename: (name) => name.replace(/\W/g, ''), // 文件名安全处理accept: 'image/*', // 限制上传文件类型为图片multiple: true, // 允许多文件上传fieldName: 'file[]' // 上传字段名称}
});
6.1.2 自定义上传处理
你可以通过 handler 参数来自定义上传逻辑。例如，如果你希望在上传前对文件进行一些处理，可以这样做：
const vditor = new Vditor('vditor', {upload: {url: 'https://your-upload-endpoint.com/upload',handler: (files) => {// 自定义上传逻辑const formData = new FormData();files.forEach(file => {formData.append('file[]', file);});return fetch('https://your-upload-endpoint.com/upload', {method: 'POST',body: formData}).then(response => response.json());}}
});
6.1.3 图片上传回调
上传成功或失败后，可以通过 success 和 error 回调函数来处理相应的事件：
const vditor = new Vditor('vditor', {upload: {url: 'https://your-upload-endpoint.com/upload',success: (editor, msg) => {console.log('Upload success:', msg);},error: (msg) => {console.error('Upload error:', msg);}}
});
6.2 自定义工具栏
Vditor 允许用户自定义工具栏，以满足不同的编辑需求。以下是如何配置和自定义工具栏的详细步骤。
6.2.1 基本配置
在 Vditor 的初始化选项中，可以通过 toolbar 参数来配置工具栏。以下是一个基本的配置示例：
const vditor = new Vditor('vditor', {toolbar: ['emoji','headings','bold','italic','|','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']
});
6.2.2 自定义按钮
你可以添加自定义按钮到工具栏中。以下是一个自定义按钮的示例：
const vditor = new Vditor('vditor', {toolbar: [{name: 'customButton',icon: '<svg>...</svg>', // 自定义图标tip: '自定义按钮',tipPosition: 's',click: () => {alert('自定义按钮点击事件');}}]
});
6.3 预览模式配置
Vditor 支持多种预览模式，包括所见即所得（WYSIWYG）、即时渲染（IR）和分屏预览（SV）。以下是如何配置预览模式的详细步骤。
6.3.1 基本配置
在 Vditor 的初始化选项中，可以通过 mode 参数来配置预览模式。以下是一个基本的配置示例：
const vditor = new Vditor('vditor', {mode: 'ir' // 设置为即时渲染模式
});
6.3.2 预览主题配置
你可以通过 preview.theme 参数来配置预览主题。以下是一个配置预览主题的示例：
const vditor = new Vditor('vditor', {preview: {theme: {current: 'light',list: {'ant-design': 'Ant Design','dark': 'Dark','light': 'Light','wechat': 'WeChat'},path: 'https://unpkg.com/vditor@${VDITOR_VERSION}/dist/css/content-theme'}}
});
通过以上配置，你可以灵活地使用 Vditor 的高级功能，满足不同的编辑需求。 ## 7. 社区与资源
7.1 官方文档与教程
Vditor作为一款功能强大的Markdown编辑器，其官方提供了详尽的文档和教程，帮助开发者快速上手并深入了解其功能和特性。官方文档涵盖了从基础安装到高级配置的各个方面，是学习和使用Vditor的重要资源。
- 官方文档地址：Vditor官方文档
- 安装指南：详细介绍了如何在不同前端框架中安装和配置Vditor。
- 使用教程：包括基本使用、编辑模式切换、工具栏配置、API调用等。
- 高级功能：介绍了如何进行自定义工具栏、图片上传处理、预览模式配置等高级功能。
7.2 社区支持与交流
Vditor拥有一个活跃的社区，开发者可以在社区中寻求帮助、分享经验、讨论问题。社区支持是Vditor生态系统的重要组成部分，为用户和开发者提供了交流和学习的平台。
- GitHub仓库：Vditor GitHub
- 在GitHub仓库中，开发者可以提交问题（Issues）、参与讨论（Discussions）、贡献代码（Pull Requests）。
- 论坛：Vditor论坛
- 论坛是用户交流的主要场所，可以在这里找到许多关于Vditor的使用经验和解决方案。
- 社交媒体：Vditor在Twitter、Facebook等社交媒体上也有官方账号，定期发布更新和活动信息。
7.3 相关资源与插件
为了进一步扩展Vditor的功能，社区和开发者开发了许多相关的资源和插件。这些资源和插件可以帮助用户更好地使用Vditor，提升开发效率和用户体验。
- 主题和样式：社区提供了多种主题和样式，用户可以根据自己的喜好进行选择和定制。
- 插件：开发者可以开发和使用各种插件来扩展Vditor的功能，例如代码高亮、数学公式支持、图表绘制等。
- 示例项目：GitHub上有很多使用Vditor的示例项目，这些项目展示了Vditor在实际应用中的使用方法和效果。
通过这些社区资源，用户和开发者可以更好地理解和使用Vditor，同时也能够参与到Vditor的生态建设中，共同推动Vditor的发展和完善。 ## 8. 授权与鸣谢
8.1 开源协议
Vditor 编辑器遵循 MIT 开源协议，这是一种非常宽松的软件许可协议，允许用户自由使用、复制、修改、合并、出版发行、散布、再授权及销售软件及其副本。MIT 协议的主要条款包括：
- 版权声明和许可声明：必须在软件和软件的所有副本中包含版权声明和许可声明。
- 免责声明：软件是“按原样”提供的，没有任何形式的明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权的保证。
使用 Vditor 的用户和开发者应遵守 MIT 协议的规定，确保在分发软件时包含原始的版权和许可声明。
9.1 编辑器发展历程
Vditor 编辑器自发布以来，经历了多个版本的迭代和改进，逐渐成为一款功能强大、用户友好的 Markdown 编辑器。以下是 Vditor 编辑器的发展历程概述：
- 初始版本发布：Vditor 的第一个版本发布于 2019 年，当时主要支持基本的 Markdown 编辑功能，包括所见即所得（WYSIWYG）模式和即时渲染（IR）模式。
- 功能扩展：随着用户需求的增加，Vditor 开始逐步增加新的功能，如数学公式、脑图、图表、流程图等高级功能，以及对多种前端框架的支持。
- 性能优化：为了提升用户体验，Vditor 在后续版本中不断进行性能优化，包括减少加载时间、优化渲染速度等。
- 多平台支持：Vditor 不仅支持浏览器端，还推出了桌面版和移动端版本，使得用户可以在不同平台上无缝使用。
9.2 版本记录
以下是 Vditor 编辑器的一些重要版本记录，展示了其功能和性能的逐步提升：
- v1.0.0：初始版本发布，支持所见即所得（WYSIWYG）和即时渲染（IR）模式。
- v1.5.0：增加了对数学公式、脑图、图表等高级功能的支持。
- v2.0.0：引入了分屏预览（SV）模式，优化了编辑器的性能和稳定性。
- v2.5.0：增加了对 Vue、React 和 Angular 等前端框架的支持。
- v3.0.0：推出了桌面版和移动端版本，实现了多平台支持。
- v3.5.0：增加了自定义工具栏和预览模式配置功能，提升了用户体验。
- v4.0.0：引入了图片上传与处理功能，增强了编辑器的实用性。
- v4.5.0：优化了编辑器的加载速度和渲染性能，提升了整体性能。
- v5.0.0：增加了对 CommonMark 和 GFM 语法的支持，扩展了编辑器的语法功能。
