Sym - 一个用 Java 实现的现代化社区平台 • 源码 • 注册

Pipe - 小而美的开源博客平台 • 体验 • 皮肤
Solo - 一个用 Java 实现的博客系统,为你或你的团队创建个博客吧! • 源码下载 
Wide - 一个基于 Web 的 Go 语言 IDE • 教程试用

Vditor 使用指南

Start

CommonJS

  • 安装依赖
npm install vditor --save
  • 在代码中引入并初始化对象,可参考 index.js
import Vditor from 'vditor'
@import "~vditor/src/assets/scss/classic" // 或者使用 dark

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

HTML script

  • 在 HTML 中插入 css 和 js,可参考 static.html
<!-- 可使用 index.dark.css 或 index.classic.css -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vditor/dist/index.classic.css" />
<script src="https://cdn.jsdelivr.net/npm/vditor/dist/index.min.js" defer></script>
const vditor = new Vditor(id, {options...})
vditor.focus()

API

options

说明 默认值
cache 是否使用 localStorage 进行缓存 true
height 编辑器总高度 'auto'
width 编辑器总宽度,支持 % 'auto'
placeholder 输入区域为空时的提示 ''
lang 多语言:en_US, zh_CN 'zh_CN'
counter 计数器 0
input 输入后触发 (value: string, previewElement?: HTMLElement): void -
focus 聚焦后触发 (value: string): void -
blur 失焦后触发 (value: string): void -
esc esc 按下后触发 (value: string): void -
ctrlEnter ctrl+enter 按下后触发 (value: string): void -
select 编辑器中选中文字后触发 (value: string): void -
editorName 设置编辑器中的 textarea name -
tab tab 键操作字符串,支持 \t 及任意字符串 -

options.toolbar

  • 工具栏,可使用 name 进行简写:toolbar: ['emoji', 'br', 'bold', '|', 'line']。默认值参见 src/ts/util/OptionsClass.ts
  • name 可枚举为:emoji, headings, bold, italic, strike, |, line, quote, list, ordered-list, check, code, inline-code, undo, redo, upload, link, table, record, preview, fullscreen, info, help, br
说明 默认值
name 唯一标示 -
icon svg 图标 -
tip 提示 -
tipPosition 提示位置:ne, nw -
hotkey 快捷键,目前仅支持 ctrl + 任意键 -
suffix 插入编辑器中的后缀 -
prefix 插入编辑器中的前缀 -

options.preview

说明 默认值
delay 预览 debounce 毫秒间隔 1000
show 是否显示预览区域 false
parse 预览回调 (element: HTMLElement): void -
url md 解析请求 -

options.preview.hljs

说明 默认值
enable 是否启用代码高亮 true
style highlight.js 样式文件名 'atom-one-light'

options.hint

说明 默认值
delay 提示 debounce 毫秒间隔 200
emoji 默认表情,可从 src/ts/emoji/allEmoji.ts 中选取 {'+1': '👍', '-1': '👎', 'heart': '❤️', 'cold_sweat': '😰'}
emojiTail 常用表情提示 -
emojiPath 表情图片地址 https://cdn.jsdelivr.net/npm/vditor/src/assets/emoji
at @用户回调,(value: string): Array,需同步返回数组 [{value:'', html:''}] -

options.upload

说明 默认值
url 上传 url,查看规范 ''
max 上传文件最大 Byte 10 * 1024 * 1024
linkToImgUrl 剪切板中包含图片地址时,使用此 url 重新上传 ''
success 上传成功回调 (textarea: HTMLTextAreaElement, msg: string): void -
error 上传失败回调 (msg: string): void -
token CORS 上传验证,头为 X-Upload-Token -
filename 文件名安全处理 (name: string): string name => name.replace(/\W/g,'')
accept 文件上传类型,同 input accept -
validate 校验,成功时返回 true 否则返回错误信息 (files: File[]) => string | boolean -
handler 自定义上传,当发生错误时返回错误信息 (files: File[]) => string | null -

options.resize

说明 默认值
enable 是否支持大小拖拽 false
position 拖拽栏位置:top, bottom 'bottom'
after 拖拽结束的回调 (height: number): void -

options.classes

说明 默认值
preview 预览元素上的 className ''

methods

说明
getValue() 获取编辑器内容
getHTML(includeHljs?: boolean) 获取预览区内容(是否输出代码高亮)。该方法需使用异步编程
insertValue(value: string) 在焦点处插入内容
focus() 聚焦到编辑器
blur() 让编辑器失焦
disabled() 禁用编辑器
enable() 接触编辑器禁用
setSelection(start: number, end: number) 选中从 start 开始到 end 结束的字符串
getSelection():string 返回选中的字符串
setValue(value: string) 设置编辑器内容
renderPreview(value?: string) 设置预览区域内容
getCursorPosition():{top: number, left: number} 获取焦点位置
deleteValue() 删除选中内容
updateValue(value: string) 更新选中内容
isUploading() 上传是否还在进行中
clearCache() 清除缓存
disabledCache() 禁用缓存
enableCache() 启用缓存
html2md(value: string) html 转 md。该方法需使用异步编程

static methods

说明
mathRender(element: HTMLElement) 转换 element 中的文本为数学公式
mermaidRender(element: HTMLElement) 转换 element 中的文本为流程图 / 时序图 / 甘特图
codeRender(element: HTMLElement, lang: (keyof II18nLang)) 为 element 中的代码块添加复制按钮
chartRender(element: (HTMLElement | Document) = document) 图表渲染
md2html(md: string, hljsStyle: style) markdown 文本转换为 html

CSS

在 DOM 元素上添加 class="vditor-reset" 属性可对内容进行更为友好的展示。

Dev

  1. 安装 node LTS 版本
  2. 下载 最新代码并解压
  3. 根目录运行 npm install
  4. npm run start 启动本地服务器,打开 http://localhost:9000
  5. 修改代码
  6. npm run build 打包代码到 dist 目录

注意事项:


欢迎注册黑客派社区,开启你的博客之旅。让学习和分享成为一种习惯!

42 评论
RYAN0UP • 2019-02-11
回复 删除

在焦点处插入内容应该是 insertValue 吧

Vanessa • 2019-02-11
回复 删除
Vanessa • 2019-02-11
回复 删除

谢谢支持

RYAN0UP • 2019-02-11
回复 删除

晚点也在我的项目上试试,现在的 markdown 编辑器不是功能不全就是 bug 多或者不维护

Vanessa • 2019-02-11
回复 删除

本来早就想抽出来的,要不在 b3log 开源的几个项目中维护很头痛。以后只需要维护一个,然后升级以下就好了。

Vanessa • 2019-02-11
回复 删除

本来早就想抽出来的,要不在 b3log 开源的几个项目中维护很头痛。以后只需要维护一个,然后升级以下就好了。

Today • 2019-02-11
回复 删除

终于等到你😄

Today • 2019-02-11
回复 删除

终于等到你😄

KevinBlandy • 2019-02-12
回复 删除

编辑器现在markdownhtml的转换是由后端完成的吗?是否有计划实现让前端渲染,并且提供获取到渲染后 html 的接口。这样后端可以直接保存 html 数据。

很不错的编辑器,用着舒服。

88250 • 2019-02-12
回复 删除

暂时没有前端渲染 md 的计划,主要是前端渲染会有些问题:

  1. 有的业务逻辑是要后端查库的,比如渲染投票
  2. 安全校验需要后端来做,只靠前端会被绕过
  3. 后端渲染才能保证最终效果的一致

但前端可以做一些格式方面的功能,比如 md 格式化、Lint、语法检查。我们正在用 golang 写一个 md 引擎(项目代号 Lute),打算通过 WASM 把这样的功能提供给 JS,在前端做文本格式方面的辅助,让用户可以更好地使用 Vditor。

眼目前,做后端 Markdown 渲染 HTML 可以用 marked(或者用我们包装的 http-marked),这是我们目前测试下来渲染 md 最好的库。

Vanessa • 2019-02-12
回复 删除

过年的时候都没给自己放假 😭

Vanessa • 2019-02-12
回复 删除
An • 2019-02-12
回复 删除

大 V 都开始写编辑器了

Vanessa • 2019-02-12
回复 删除

再开一个新坑。一个萝卜一个坑。

KevinBlandy • 2019-02-12
回复 删除

在文本数据比较大的情况下,每一次的输入事件。都要把整个 markdown 文本提交给后台解析。这样是不是有点儿伤哦?其实我自己的想法非常简单。

  • 前端直接就完成了 markdownhtml 的转换,并且提供 API 获取到 html 数据。
  • 后端保存数据的时候,保存 html 以及 markdown 数据。
  • 查看文章的时候,从 DB 读取和渲染 html
  • 编辑文章的时候,从 DB 读取 markdown 渲染到编辑器。
  • Xss 安全问题,可以用 jsoup 来过滤 html 中的非法 标签属性 等。

我的想法有啥问题,D 哥指教一下。