Блоки

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

Базовое использование

Подключайте и используйте блоки в конфигурации редактора.

import 'texditor/styles/theme.css';
import Texditor from 'texditor';
import { 
  Gallery, 
  Files, 
  H2, 
  List, 
  Paragraph 
} from 'texditor/entities/blocks';

const editor = new Texditor({
  // Идентификатор html-элемента
  handle: 'texditor',
  // Список моделей блоков
  blocks: [
    Paragraph,
    List,

    // Настроим простой блок
    H2.setup({
      // Плейсхолдер (если данные не заполнены)
      placeholder: 'Мой заголовок',
      // Параметры базовой санитизации
      sanitizerConfig: {
        elements: ['a', 'sup', 'sub']
        // ...
      }
      // ... другие параметры из основной и базовой модели
    }),

    /*
      На примере блока галереи, который обладает 
      собственными параметрами конфигурации.
    */
    Gallery.setup({
      mimeTypes: [
        "image/png", 
        "image/jpeg", 
        "video/mp4", 
        "image/webp"
      ],
      multiple: true,
      uploadLabelMessage: "Загружайте свои файлы в форматах .png, .jpg, .mp4 или .gif",
      showOnlyWhenEmpty: true,
      stylesLtr: "left",
      styles: [],
      defaultStyle: 'slider',
      ajaxConfig: {
        url: "https://texditor.priveted.com/api/upload",
        options: {
          data: {
            hello: 33
          }
        }
      }
    }),
    
    /* 
     Несмотря на то, что этот элемент будет функционировать как блок,
     для загрузки файлов потребуется настройка, аналогичная той, 
     что используется в блоке «Галерея». 
    */
    Files,

    // ... любой пользовательский блок, соответствующий модели BlockModel.
  ]
});

Чтобы более детально настроить каждый блок и узнать о его специфике, рекомендуется ознакомиться с API.

Расширение и создание пользовательских блоков

Блоки обладают высокой степенью расширяемости и могут использовать все возможности API редактора. Они построены на базовой модели блоков, которая предоставляет разнообразные методы для управления DOM-деревом.

Расширение блока

Мы взяли за основу блок Paragraph, который не требует больших изменений в конфигурации и имеет структуру, основанную на базовой модели блоков BlockModel. Затем мы адаптировали его под свои нужды.

Javascript

import { BlockElement } from "texditor";
import { Paragraph } from "texditor/entities/blocks";

export class CustomParagraph extends Paragraph {
  // Используя стандартную конфигурацию
  configure() {
    // Обязательно берем за основу родительскою конфигурацию
    const config = super.configure();
    config.placeholder = 'Мой параграф'

    return config;
  }

  // Выполняем после монтирования элемента блока в DOM-дерево
  onMount(el) {
    this.myCustomMethod();
  }

  // Это всего лиши пример работы (не делайте так на реальных проектах)
  myCustomMethod() {
    const { blockManager, events } = this.editor;
    const blockElement = this.getElement();

    // Получить текущий элемент блока
    console.log(blockElement);

    // Тестовый пример удаления блока
    blockManager.removeBlock(2);

    // Подписка на событие
    events.on('keydown', (evt) => {
      console.log(evt);
    });
  }
}

Typescript

import {
  BlockElement,
  type BlockModelConfig,
  type TexditorEvent
} from "texditor";
import { Paragraph } from "texditor/entities/blocks";

export class CustomParagraph extends Paragraph {
  // Используя стандартную конфигурацию
  protected configure(): Partial<BlockModelConfig> {
    // Обязательно берем за основу родительскою конфигурацию
    const config = super.configure();
    config.placeholder = 'Мой параграф'

    return config;
  }

  // Выполняем после монтирования элемента блока в DOM-дерево
  protected onMount(_el: BlockElement): void {
    this.myCustomMethod();
  }

  // Это всего лиши пример работы (не делайте так на реальных проектах)
  private myCustomMethod(): void {
    const { blockManager, events } = this.editor;
    const blockElement = this.getElement();

    // Получить текущий элемент блока
    console.log(blockElement);

    // Тестовый пример удаления блока
    blockManager.removeBlock(2);

    // Подписка на событие
    events.on('keydown', (evt: TexditorEvent) => {
      console.log(evt);
    });
  }
}

Создание блока

Для создания блока необходимо расширить класс BlockModel. Чтобы блок функционировал корректно, нужно реализовать основной метод configure.

Javascript

import { BlockModel } from 'texditor/core/models';

export class CustomListBlock extends BlockModel {
  // Определяем основную конфигурацию блока
   configure() {
    return {
      name: 'ul',
      translation: 'list',
      groupCode: 'list',
      tagName: 'ul',
      itemTagName: 'li',
      itemName: 'li',
      itemClassName: 'tex-list-item',
      itemBodyClassName: 'tex-list-item-body',
      autoParse: true,
      autoMerge: true,
      icon: { raw: '<svg>...</svg>' },
      editable: false,
      editableItems: true,
      visibleTools: true,
      sanitizer: true,
      normalize: true,
      convertible: true,
      className: 'tex-list',
      sortableItems: true,
      sanitizerConfig: {
        elements: ['b', 'a', 'i', 's', 'u', 'sup', 'sub', 'mark', 'code'],
        attributes: {
          a: ['href', 'target'],
        },
        protocols: {
          a: {
            href: ['https', 'ftp', 'http', 'mailto'],
          },
        },
      },
    };
  }

  // Далее используем все возможности модели блоков...
}

Typescript

import { BlockModel } from 'texditor/core/models';
import { type BlockModelConfig } from "texditor";

export class CustomListBlock extends BlockModel {
  // Определяем основную конфигурацию блока
  protected configure(): Partial<BlockModelConfig> {
    return {
      name: 'ul',
      translation: 'list',
      groupCode: 'list',
      tagName: 'ul',
      itemTagName: 'li',
      itemName: 'li',
      itemClassName: 'tex-list-item',
      itemBodyClassName: 'tex-list-item-body',
      autoParse: true,
      autoMerge: true,
      icon: { raw: '<svg>...</svg>' },
      editable: false,
      editableItems: true,
      visibleTools: true,
      sanitizer: true,
      normalize: true,
      convertible: true,
      className: 'tex-list',
      sortableItems: true,
      sanitizerConfig: {
        elements: ['b', 'a', 'i', 's', 'u', 'sup', 'sub', 'mark', 'code'],
        attributes: {
          a: ['href', 'target'],
        },
        protocols: {
          a: {
            href: ['https', 'ftp', 'http', 'mailto'],
          },
        },
      },
    };
  }

  // Далее используем все возможности модели блоков...
}

Добавление пользовательских блоков в редактор

Теперь мы можем добавлять новые блоки в список моделей, и они будут корректно работать

import CustomParagraph from './blocks/CustomParagraph';
import CustomListBlock from './blocks/CustomListBlock';

const texditor = new Texditor({
  handle: 'texditor',
  blocks: [
    CustomParagraph,
    CustomListBlock
  ]
})