Введение

Vditor — это редактор Markdown на стороне браузера. Он поддерживает WYSIWYG, мгновенное отображение (аналогично Typora) и режим предварительного просмотра с разделённым экраном. Vditor реализован на TypeScript и поддерживает нативный JavaScript и такие фреймворки, как Vue, React, Angular и Svelte.

Добро пожаловать на официальный сайт Vditor по адресу https://b3log.org/vditor, чтобы узнать больше.

Предыстория

С популяризацией методов набора текста в Markdown всё больше приложений начинают интегрировать редактор Markdown. Текущее состояние основных интегрируемых редакторов Markdown выглядит следующим образом:

• Некоторые поддерживают только предварительный просмотр с разделением экрана, то есть область редактирования и область предварительного просмотра разделены.
• Некоторые одновременно поддерживают WYSIWYG и предварительный просмотр с разделёнными экранами, но они не могут полностью поддерживать набор текста Markdown в режиме WYSIWYG.
• Почти нет мгновенного рендеринга, подобного Typora.

Эти три пункта соответствуют трём сценариям применения:

• Предварительный просмотр с разделением экранов: адаптируется к традиционной сцене использования Markdown, подходит для редактирования и набора текста на большом экране.
• WYSIWYG: удобен для пользователей, которые не знакомы с Markdown, пользователи, знакомые с Markdown, также могут использовать его без проблем.
• Мгновенный рендеринг: теоретически это самый элегантный способ редактирования Markdown, позволяющий пользователям, знакомым с Markdown, больше сосредоточиться на создании контента.

Поэтому необходим редактор Markdown, который может адаптироваться к сценариям использования. Необходимо учитывать:

• Сценарии использования традиционных пользователей Markdown, предоставляя предварительный просмотр с разделенным экраном.
• Сценарии использования пользователей, работающих с форматированным текстом, предоставляя WYSIWYG.
• Сцены использования высококлассных пользователей Markdown, обеспечивая мгновенный рендеринг.

Vditor приложил усилия в этих областях, надеясь внести некоторый вклад в современную общую область редактирования Markdown.

Особенности

• Поддержка трёх режимов редактирования: WYSIWYG (wysiwyg), мгновенный рендеринг (ir) и разделенный вид (sv).

• Поддержка структуры, математических формул, mind-карт. Карты, диаграммы, блок-схемы, графики Ганта, временные шкалы, штатное расписание, мультимедиа, голосовое чтение, якорные заголовки, выделение и копирование кода, рендеринг Graphviz.

• Встроенный механизм фильтрации безопасности, экспорт, отложенная загрузка изображений, список задач, мультиплатформенный предварительный просмотр, переключение между несколькими темами, функция копирования в WeChat/Zhihu.

• Реализация спецификаций CommonMark и GFM, форматирование и просмотр синтаксического дерева Markdown, поддержка более 10 конфигураций.

• Панель инструментов содержит более 36 операций. Помимо поддержки расширения, можно настроить сочетания клавиш, всплывающие подсказки, позиции подсказок, значки, события кликов, имена классов и вспомогательные панели инструментов.

• Расширение автозаполнения для эмодзи/@/# и т. д.

• Можно использовать перетаскивание, вставку и загрузку, отображать прогресс загрузки в реальном времени, поддерживать междоменную загрузку CORS.

• Сохранять контент в режиме реального времени для предотвращения случайной потери данных.

• Поддержка записи, пользователи могут напрямую публиковать голосовые сообщения.

• Если вставка содержит изображения внешних ссылок, разметка HTML автоматически преобразуется в Markdown и может быть загружена на сервер через указанный интерфейс.

• Поддерживается изменение размера главного окна с помощью перетаскивания, подсчёт символов.

• Многотемный режим, встроенные чёрная, белая и зелёная темы.

• Мультиязычная поддержка, встроенная локализация китайского, английского и корейского языков.

• Поддержка основных браузеров, адаптирован для мобильных устройств.

🔮 Режимы редактирования

WYSIWYG — этот режим более удобен для пользователей, которые не знакомы с Markdown, и вы можете использовать его без проблем, если знакомы с Markdown.

Instant Rendering — этот режим должен быть знаком пользователям, знакомым с Typora. Теоретически это самый элегантный способ редактирования Markdown.

Split View — традиционный режим Split View подходит для редактирования Markdown на большом экране.

🍱 Синтаксическая поддержка

Поддерживаются все синтаксические конструкции CommonMark: тематические разрывы, заголовки ATX, заголовки Setext, блоки кода с отступом, блоки кода в фигурных скобках, HTML-блоки, определения ссылок на ссылки, абзацы, блочные цитаты, списки, обратные слэши, сущности и числовые символьные ссылки, кодовые интервалы, акценты и сильные акценты, ссылки, изображения, необработанный HTML, жёсткие и мягкие переносы строк, текстовое содержимое.

Также поддерживаются все конструкции GFM: таблицы, элементы списка задач, зачёркивание, автоссылки, фильтрация XSS.

Кроме того, поддерживается расширенный синтаксис Markdown: сноски, оглавление, пользовательские идентификаторы заголовков.

Синтаксис диаграмм:

• блок-схема, диаграмма последовательности, график Ганта поддерживаются Mermaid;
• Graphviz;
• линейная диаграмма, круговая диаграмма, диаграмма мозга и т.д. поддерживаются ECharts.

Stave: поддерживается abc.js.

Математические формулы: блоки математических формул, математические формулы на уровне строк поддерживаются MathJax и KaTeX.

YAML Front Matter.

Оптимизация китайского контекста:

• вставляется пробел между китайским и западным языками;
• исправляются орфографические ошибки в терминологии;
• китайские знаки препинания, которым предшествует английский язык, заменяются соответствующими китайскими знаками препинания.

Большинство вышеперечисленных функций можно включить или отключить с помощью конфигурации переключателя, разработчики могут выбрать их в соответствии со своими сценариями применения.

🗃 Примеры использования

Sym — современная платформа сообщества (форум/BBS/SNS/блог), реализованная на Java. Solo и Pipe — B3log, распределённый узел блога сообщества, присоединяйтесь к сети сообществ следующего поколения. Arya — онлайн-редактор Markdown, основанный на Vue, Vditor. Больше примеров.

🛠️ User Guide

CommonJS

• Установите зависимости:

npm install vditor --save

• Представьте и инициализируйте объекты в коде, вы можете обратиться к index.js:

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

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

HTML script

• Вставьте CSS и js в HTML, вы можете обратиться к демо:

<!-- ⚠️Please specify the version number in the production environment, such as https://cdn.jsdelivr.net/npm/vditor@x.x.x/dist... -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vditor/dist/index.css" />
<script src="https://cdn.jsdelivr.net/npm/vditor/dist/index.min.js"></script>

Demo code

• Демо
• Редактор CommonJS
• Рендер CommonJS
• Использование в Svelte

Темы

• Поддерживает четыре набора чёрно-белых тем: and-design, classic, dark, wechat
• Используйте разработанный вами less/css для полной настройки стиля после обращения к существующему стилю
• Цвета темы можно настроить, изменив переменные в index.less
• Добавление class="vditor-reset" (классическая тема) или class="vditor-reset vditor-reset--dark" (чёрная тема) в элемент отображения содержимого может сделать отображение содержимого более удобным

API

id

Может быть заполнен элементом id или самим элементом HTMLElement

⚠️: При заполнении элемента HTMLElement, вам нужно установить options.cache.id или установить options.cache.enable в false

options

options.toolbar

• Панель инструментов, вы можете использовать имя для сокращения: toolbar: ['emoji', 'br', 'bold', '|', 'line']. См. по умолчанию src/ts/util/Options.ts
• name можно перечислить как: emoji , headings , bold , italic , strike , | , line , quote , list , ordered-list , check ,outdent ,indent , code , inline-code, insert-after, insert-before, code-theme, content-theme, export, undo , redo , upload , link , table , record , edit-mode , both , preview , fullscreen , outline , devtools , info , help , br
• Когда name не входит в перечисление, вы можете добавить пользовательскую кнопку в следующем формате:

new Vditor('vditor', {
  toolbar: [
    {
      hotkey: '⇧⌘S',
      name: 'sponsor',
      tipPosition: 's',
      tip: '成为赞助者',
      className: ```
{
    "right",
    icon: '<svg t="1589994565028" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2808" width="32" height="32"><path d="M506.6 423.6m-29.8 0a29.8 29.8 0 1 0 59.6 0 29.8 29.8 0 1 0-59.6 0Z" fill="#0F0F0F" p-id="2809"></path><path d="M717.8 114.5c-83.5 0-158.4 65.4-211.2 122-52.7-56.6-127.7-122-211.2-122-159.5 0-273.9 129.3-273.9 288.9C21.5 562.9 429.3 913 506.6 913s485.1-350.1 485.1-509.7c0.1-159.5-114.4-288.8-273.9-288.8z" fill="#FAFCFB" p-id="2810"></path><path d="M506.6 926c-22 0-61-20.1-116-59.6-51.5-37-109.9-86.4-164.6-139-65.4-63-217.5-220.6-217.5-324 0-81.4 28.6-157.1 80.6-213.1 53.2-57.2 126.4-88.8 206.3-88.8 40 0 81.8 14.1 124.2 41.9 28.1 18.4 56.6 42.8 86.9 74.2 30.3-31.5 58.9-55.8 86.9-74.2 42.5-27.8 84.3-41.9 124.2-41.9 79.9 0 153.2 31.5 206.3 88.8 52 56 80.6 131.7 80.6 213.1 0 103.4-152.1 261-217.5 324-54.6 52.6-113.1 102-164.6 139-54.8 39.5-93.8 59.6-115.8 59.6zM295.4 127.5c-72.6 0-139.1 28.6-187.3 80.4-47.5 51.2-73.7 120.6-73.7 195.4 0 64.8 78.3 178.9 209.6 305.3 53.8 51.8 111.2 100.3 161.7 136.6 56.1 40.4 88.9 54.8 100.9 54.8s44.7-14.4 100.9-54.8c50.5-36.3 108-84.9 161.7-136.6 131.2-126.4 209.6-240.5 209.6-305.3 0-74.9-26.2-144.2-73.7-195.4-48.2-51.9-114.7-80.4-187.3-80.4-61.8 0-127.8 38.5-201.7 117.9-2.5 2.6-5.9 4.1-9.5 4.1s-7.1-1.5-9.5-4.1C423.2 166 357.2 127.5 295.4 127.5z" fill="#141414" p-id="2811"></path><path d="M353.9 415.6m-33.8 0a33.8 33.8 0 1 0 67.6 0 33.8 33.8 0 1 0-67.6 0Z" fill="#0F0F0F" p-id="2812"></path><path d="M659.3 415.6m-33.8 0a33.8 33.8 0 1 0 67.6 0 33.8 33.8 0 1 0-67.6 0Z" fill="#0F0F0F" p-id="2813"></path><path d="M411.6 538.5c0 52.3 42.8 95 95 95 52.3 0 95-42.8 95-95v-31.7h-190v31.7z" fill="#5B5143" p-id="2814"></path><path d="M506.6 646.5c-59.6 0-108-48.5-108-108v-31.7c0-7.2 5.8-13 13-13h190.1c7.2 0 13 5.8 13 13v31.7c0 59.5-48.5 108-108.1 108z m-82-126.7v18.7c0 45.2 36.8 82 82 82s82-36.8 82-82v-18.7h-164z" fill="#141414" p-id="2815"></path><path d="M450.4 578.9a54.7 27.5 0 1 0 109.4 0 54.7 27.5 0 1 0-109.4 0Z" fill="#EA64F9" p-id="2816"></path><path d="M256 502.7a32.1 27.5 0 1 0 64.2 0 32.1 27.5 0 1 0-64.2 0Z" fill="#EFAFF9" p-id="2817"></path><path d="M703.3 502.7a32.1 27.5 0 1 0 64.2 0 32.1 27.5 0 1 0-64.2 0Z" fill="#EFAFF9" p-id="2818"></path></svg>',
    click () {alert('捐赠地址：https://ld246.com/sponsor')},
  ]

Это похоже на язык JavaScript.

Текст описывает внешний вид элементов интерфейса, но не содержит кода для их создания или работы с ними. | | Объяснение | По умолчанию | | - | - | - | | delay | Интервал устранения дребезга предварительного просмотра в миллисекундах | 1000 | | maxWidth | Максимальная ширина области предварительного просмотра | 800 | | mode | Режим отображения: оба, редактор | «оба» | | url | Запрос на анализ md | — | | parse | Предварительный просмотр обратного вызова (элемент: HTMLElement) | — | | transform | Обратный вызов перед рендерингом (html: строка): строка | — |

options.preview.theme

options.preview.hljs

options.preview.markdown

options.preview.math

options.preview.actions

По умолчанию: [«desktop», «tablet», «mobile», «mp-wechat», «zhihu»]

options.hint

interface IHintData {
  html: string;
  value: string;
}

interface IHintExtend {
  key: string;

  hint?(value: string): IHintData[] | Promise<IHintData[]>;
}

options.upload

• Структура данных загрузки файлов следующая. Если структура данных, возвращаемая бэкэндом, несовместима, вы можете использовать format для преобразования.

// POST data
xhr.send(formData);  // formData = FormData.append("file[]", File)
// return data
{
 "msg": "",
 "code": 0,
 "data": {
 "errFiles": ['filename', 'filename2'],
 "succMap": {
   "filename3": "filepath3",
   "filename3": "filepath3"
   }
 }
}

• Чтобы предотвратить недействительность внешних изображений, linkToImgUrl может передавать адреса внешних изображений в буфере обмена на сервер для сохранения и обработки. Структура данных следующая:

// POST data
xhr.send(JSON.stringify({url: src})); // src — это адрес изображения за пределами станции
// return data
{
 msg: '',
 code: 0,
 data : {
   originalURL: '',
   url: ''
 }
}

options.resize

options.classes

options.fullscreen

options.outline

methods

static methods

• Когда не требуется операция редактирования, просто представьте method.min.js и напрямую вызовите. Vditor.mermaidRender(document)

```js
import VditorPreview from 'vditor/dist/method.min'
VditorPreview.mermaidRender(document)

• Когда вам нужно отобразить Markdown на странице, вы можете напрямую вызвать метод preview со следующими параметрами:

previewElement: HTMLDivElement,   // Используйте этот элемент для рендеринга
markdown: string,  // Исходный Markdown, который будет отображаться
options?: IPreviewOptions {
  mode: "dark" | "light";
  anchor?: number;  // 0: не отображать, 1: отображать слева, 2: отображать справа
  customEmoji?: { [key: string]: string };    // Пользовательские эмодзи, по умолчанию {}
  lang?: (keyof II18nLang);    // Язык, по умолчанию 'zh_CN'
  emojiPath?: string;    // Путь к изображению эмодзи
  hljs?: IHljs; // См. параметры.preview.hljs
  speech?: {  // Чтение выбранного содержимого
    enable?: boolean,
  };
  math?: IMath; // Конфигурация рендеринга математических формул
  transform?(html: string): string; // Обратный вызов перед рендерингом
  after?(); // Обратный вызов после рендеринга
  cdn?: string; // Собственный адрес CDN
  lazyLoadImage?: string; // используйте «https://cdn.jsdelivr.net/npm/vditor/dist/images/img-loading.svg», чтобы лениво загрузить изображение
  markdown?: options.preview.markdown;
  renderers?: ILuteRender; // Пользовательский метод рендеринга https://ld246.com/article/1588412297062
}

• ⚠️method.min.js и index.min.js нельзя вводить одновременно

🏗 Руководство разработчика

Принцип связан

• Обсуждение редактора WYSIWYG Markdown
• Vditor реализует Markdown WYSIWYG
• Lute — это движок Markdown, оптимизированный для китайского контекста, поддерживает Go и JavaScript

Окружение

1. Установите node LTS версии

2. Скачайте последний код и распакуйте его

3. Запустите npm install в корневом каталоге

4. npm run Запуск локального сервера, откройте http://localhost:9000

5. Измените код.

6. Соберите пакет кода в каталог dist с помощью команды npm run build.

Переключение на CDN

Благодаря механизму загрузки по требованию, стандартным CDN является https://cdn.jsdelivr.net/npm/vditor@номер версии.

Если вы изменили код или вам нужно использовать собственный CDN, выполните следующие действия:

• В начальные параметры options и IPreviewOptions необходимо добавить конфигурацию cdn.
• Методы highlightRender, mathRender, abcRender, chartRender, mermaidRender должны иметь параметр cdn.
• Скопируйте каталог dist после успешной сборки или jsDelivr в нужное место.

Обновление

Пожалуйста, внимательно прочитайте CHANGELOG перед обновлением версии.

Ⓜ️ Руководство пользователя Markdown

• Базовый синтаксис.
• Расширенный синтаксис.
• Краткое справочное руководство.

🏘️ Сообщество

• Форум.
• Проблемы.

📄 Лицензия

Vditor использует открытую лицензию MIT.

🙏 Благодарности

• Lute: структурированный движок Markdown, поддерживающий Go и JavaScript.
• highlight.js: подсветка синтаксиса JavaScript.
• mermaid: генерация диаграмм и блок-схем из текста аналогично Markdown.
• incubator-echarts: мощная интерактивная библиотека диаграмм и визуализации для браузера.
• abcjs: библиотека JavaScript для рендеринга стандартной нотной записи в браузере.
• IntelliJ IDEA: семейство мощных и эргономичных сред разработки.

📽️ История

На начальном этапе разработки Sym мы напрямую использовали WYSIWYG редактор форматированного текста. В то время HTML-редакторы были очень популярны, и было очень удобно цитировать их в проекте, что также соответствовало привычкам пользователей того времени.

Позже появление Markdown постепенно изменило типографику всех. Кроме того, некоторые другие наши проекты предназначены для программистов, поэтому переход на md также является общей тенденцией. Мы выбрали CodeMirror, который является отличным редактором, он предоставляет богатый программный интерфейс для разработчиков, а также совместим с различными браузерами. Это хорошо.

Позже, когда бизнес-потребности наших проектов обострились, использование CodeMirror иногда кажется более «громоздким». Например, для реализации автоматического заполнения списка имён пользователей, вставки эмодзи, загрузки файлов и т. д. требуется более глубокая вторичная разработка, и эти бизнес-требования точно распространены и необходимы во многих сценариях проекта.

Наконец, мы решили сами реализовать редактор в Sym. После нескольких версий редактор Sym стал зрелым. В сообществе LianDi, которым мы управляем, люди спрашивали нас, можем ли мы отделить редактор для общего использования. В то же время наш основной программист переднего плана V также чувствовал себя немного перегруженным поддержанием редакторов, разбросанных по различным проектам, плюс хорошее впечатление от TypeScript, поэтому я решил использовать ts для реализации нового редактора на стороне браузера.

Так родился Vditor.