Установка

Выполните этот код в командной строке:

$ npm i @emailmaker/[email protected] -save

Добавьте EmailMaker plugin в ваш App config.

Для сборщика Webpack

Импорт пакета:

const emailMakerPlugin = require('@emailmaker/emailmaker/webpack')

Определение пакета в приложении:

module.exports = {
	plugins: [
		new EmailmakerWebpackPlugin(),
	]
}

Для сборщика Vite

Импорт пакета:

import emailMakerPlugin from 'emailmaker/vite'

Определение пакета в приложении:

export default defineConfig({
	plugins: [emailMakerPlugin()],
})

Инициализация

Импортируйте EmailMaker plugin в вашем компоненте:

import * as emailmaker from "@emailmaker/emailmaker"

Параметры инициализации плагина содержат параметр getAuthToken. В него должна быть передана функция, которая запрашивает авторизационный OAuth токен по Client ID и Client Secret.

Получение OAuth токена на бэкенде

curl --location 'https://api.emailmaker.ru/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=*******' \
--data-urlencode 'client_secret=*******' \
--data-urlencode 'grant_type=client_credentials'

Создание сущности EmailMaker plugin

emailmaker.init({
	getAuthToken: getAuthToken,
	element: "#test",
	content: {
		title: "Email subject",
		html: `КОД_ПИСЬМА`,
	},
	config: { }
}).then(instance => {  })

КОД_ПИСЬМА можно взять из нашего образца или вставить HTML-код своего письма.

Конфигурация

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

element

Вы можете передать строку element в конфигурацию плагина. Это селектор DOM-элемента, внутри которого нужно инициализировать плагин. Если элемент не определен, приложение будет запущено в фоновом режиме.

content

Секция content содержит параметры письма, которое нужно отобразить в редакторе. В этот параметр может быть передано:

{string}

HTML верстка письма.

{object} email options

{
	id?: string; // Уникальный ID проекта в вашей системе.
	html?: string; // HTML верстка письма.
	subject?: string; // Тема письма.
	preheader?: string; // Прехедер письма.
}

{object} full description

{
	temlateId?: string; // ID шаблона внутри EmailMaker.
	email?: object; // email options.
	blocks?: []; // Дополнительные блоки.
	comments?: []; // Комментарии в письме.
}

Можно изменить содержимое в любой момент после инициализации с помощью метода instance.show(content).

config

Раздел для настройки внешнего вида и настроек редактора. Вы можете изменить конфигурацию этого раздела после инициализации, используя emailmaker.setConfig или emailmaker.updateConfig.

Список параметров секции config

| Параметр | Описание | Значение по умолчанию | | -------------------------------------- | --------------------------------------------------------------------------- | --------------------- | | theme | Тема плагина: light, dark. | light | | autosaveTimeout | Задержка перед автосохранением, мс. | 10000 | | mergeTags | JSON со списком динамических переменных. | undefined | | styles | Строка со стилями в формате CSS. | '' | | | | | | headerShow | Ппоказ шапки. | true | | headerArrowBackVisible | Показ стрелки "Назад". | true | | headerTitleVisible | Показ поля "Тема". | true | | headerPreheaderVisible | Показ поля "Прехедер". | true | | historyEnabled | Показ кнопки "История версий". | true | | codeEnabled | Показ кнопки "Code-mode". | true | | codeSideEnabled | Показ кнопки "Code-mode" в режиме, когда есть переключатель десктоп/мобайл. | true | | previewIconEnabled | Показ кнопки "Предпросмотр". | true | | previewModeEnabled | Ссылка на Предпросмотр. | true | | livePreviewEnabled | Показ кнопки "Тестировние в почтовиках". | true | | sendTestEnabled | Показ кнопки "Отправить тест". | true | | sharePreviewEnabled | Показ кнопки "Поделиться". | true | | webversionEnabled | Показ ссылки на веб-версию. | true | | commonStylesEnabled | Показ стилей контента. | true | | emailResponsiveControlEnabled | Показ переключателя адаптивности письма. | true | | | | | | emailDropdownMenuEnabled | Показ меню письма. | true | | emailDropdownMenuClone | Показ пункта "Клонировать". | true | | emailDropdownMenuImport | Показ пункта "Импортировать". | true | | emailDropdownMenuImportButton | Показ пункта "Импортировать" кнопкой | true | | emailDropdownMenuLock | Показ пункта "Заблокировать". | true | | emailDropdownMenuRemove | Показ пункта "Удалить". | true | | | | | | emailExportEnabled | Показ кнопки "Экспорт". | true | | exportHtmlEnabled | Экспорт в HTML. | true | | exportZipEnabled | Экспорт в ZIP. | true | | exportClipboardEnabled | Экспорт в буфер. | true | | exportWebHookEnabled | Экспорт в вебхук. | true | | exportOutlookEnabled | Экспорт в Outlook. | true | | exportPdfEnabled | Экспорт в PDF. | true | | exportPngEnabled | Экспорт в PNG. | true | | | | | | nextButtonEnabled | Показ второстепенной кнопки. | false | | nextButtonText | Текст на второстепенной кнопке. | '' | | saveButtonEnabled | Показ основной кнопки. | true | | saveButtonText | Текст основной кнопки. | true | | commandButtonsEnabled | Показ основной и второстепенной кнопки. | true | | | | | | sidePanelFloating | Плавающая боковая панель. | true | | desktopMobileSwitchRule | Полоса переключения режимов. | true | | desktopMobileSwitchPanel | Панель переключения режимов. | false | | onlyCodeModeInMobile | вывод в мобиле только кода. | false | | | | | | pathEnabled | Показ хлебных крошек. | true | | copyPasteEnabled | Показ копирования-вставки блока в iframe. | true | | saveBlockEnabled | Показ кнопки сохранения блока. | true | | editImageControlEnabled | Показ кнопки редактирования изображения. | true | | | | | | menuDirection | Расположение боковой панели. | 'right' | | defaultBuildPanel | Настройка открывающейся вкладки по умолчанию. | ''/'empty'/'project'/'common'/'template' | | commentsEnabled | Показ кнопки "Комментарии". | true | | aiAssistentEnabled | Показ "AI ассистента". | true | | optimizeEnabled | Показ кнопки "Оптимизация". | true | | optimizeLinksEnabled | Показ проверки ссылок. | true | | optimizeImagesEnabled | Показ проверки картинок. | true | | optimizeSpamAssassinEnabled | Показ проверки SpamAssassin. | true | | optimizeCheckCodeEnabled | Показ проверки кода. | true | | settingsEnabled | Показ кнопки "Настройки". | true | | UTMEnabled | Показ таба UTM-метки. | true | | descriptionEnabled | Показ поля "Описание" в настройках. | true | | tagsEnabled | Показ поля Теги в настройках. | true | | switchDesktopMobilePropsEnabled | Показ переключателя мобильных свойств. | true | | stepToOtherElementEnabled | Показ кнопок перехода к другим элементам. | true | | deleteButtonEnabled | Показ кнопки удаления элемента. | true | | toggleSidePanel | Возможность схлопывать боковую панель. | true | | blocksSectionsShow | Показ меню блоков. | true | | blocksEmptyEnabled | Показ пустых блоков. | true | | blocksSavedEnabled | Показ сохранённых блоков. | true | | blocksCommonEnabled | Показ общих блоков. | true | | blocksTemplateEnabled | Показ блоков шаблона. | true | | blocksSearchEnabled | Показ поиска по блокам. | true | | blocksAddPanelEnabled | Показ панели добавления блока в визуальном редакторе. | true | | imagePathDropdownEnabled | Показ выпадашки с путём к изображению. | true | | | | | | formFieldImageTitleEnabled | Показ поля title в форме картинки. | true | | formFieldBorderEnabled | Показ полей изменения рамки. | true | | formFieldBorderRadiusEnabled | Показ полей изменения скругления. | true | | formFieldBoxShadowEnabled | Показ полей изменения тени. | true | | formFieldVisibilityEnabled | Показ кнопок изменения видимости элемента. | true | | formFieldExportAsPictureEnabled | Показ переключателя экспорт в картинку. | true | | | | | | formButtonFieldInsertImageEnabled | Показ кнопки вставки изображения в текст у кнопки. | true | | formButtonFieldVerticalAlignEnabled | Показ кнопок вертикального выравнивания у кнопки. | true | | formButtonFieldTextAlignEnabled | Показ кнопок выравнивания текста у кнопки. | true | | formButtonFieldBackgroundImageEnabled | Показ полей фонового изображения у кнопки. | true | | formButtonFieldPaddingsEnabled | Показ полей внутренних отступов у кнопки. | true | | formButtonFieldReplacerEnabled | Показ реплейсера у кнопки. | true | | | | | | formCellFieldVerticalAlignEnabled | Показ кнопок вертикального выравнивания у ячейки. | true | | formCellFieldBackgroundImageEnabled | Показ полей фонового изображения у ячейки. | true | | formCellFieldPaddingsEnabled | Показ полей внутренних отступов у ячейки. | true | | formCellFieldSizeEnabled | Показ полей ширины и высоты. | true | | | | | | formImageFieldVerticalAlignEnabled | Показ кнопок вертикального выравнивания у картинки. | true | | formImageFieldReplacerEnabled | Показ кнопок вертикального выравнивания у картинки. | true | | formImageFieldHeightEnabled | Показ поля высоты у картинки. | true | | | | | | formTableFieldBackgroundImageEnabled | Показ полей фонового изображения у таблицы. | true | | formDivFieldBackgroundImageEnabled | Показ полей фонового изображения у контейнера. | true | | formEmailFieldBackgroundImageEnabled | Показ полей фонового изображения у письма. | true | | | | | | formTextFieldTypografEnabled | Показ кнопки типографа. | true | | formTextFieldReplacerEnabled | Показ кнопки реплейсера. | true | | | | | | elementImageEnabled | Элемент Картинка. | true | | elementTextEnabled | Элемент Текст. | true | | elementHeaderEnabled | Элемент Заголовок. | true | | elementButtonEnabled | Элемент Кнопка. | true | | elementListULEnabled | Элемент Список UL. | true | | elementListOLEnabled | Элемент Список OL. | true | | elementDividerEnabled | Элемент Разделитель. | true | | elementSpacerEnabled | Элемент Отступ. | true | | elementSocialEnabled | Элемент Соцсети | true | | elementTableEnabled | Элемент Таблица. | true | | elementCountdownEnabled | Элемент Счётчик. | true | | elementVideoEnabled | Элемент Видео. | true | | elementAIimageEnabled | Элемент AI картинка. | true | | elementAItextEnabled | Элемент AI текст. | true | | elementCarouselEnabled | Элемент AMP карусель. | true | | elementAccordionEnabled | Элемент AMP аккордион. | true | | elementFormEnabled | Элемент AMP форма. | true | | | | | | imageCenterStockEnabled | Таб Стока фотографий. | true | | imageCenterGifEnabled | Таб Стока гифок. | true | | imageCenterEditorEnabled | Таб редактора изображений. | true | | compressMaxSize | Макс. вес картинки после оптимизации, Мб. | true | | compressMaxWidthOrHeight | Макс. ширина картинки после оптимизации, px. | true |

Обработка событий

События могут быть переданы в конфигурации или добавлены после при работе с экземпляром плагина. Все подписчики событий могут быть асинхронными функциями.

Пример

emailmaker.init({
	....,
	// Подписка на события в инициализации.
	handleReadEmail: (e) => {},
	handleSaveEmail: async (e) => {}
}).then((instance) => {
	// Подписка на события после инициализации.
	const dispose = instance.handleReadEmail(e => {});
	const dispose = instance.handleSaveEmail(async (e) => {});
});

Передавая асинхронную функцию, вы можете реализовать асинхронную загрузку данных.

Пример

emailmaker.init({
	element: "#test",
	content: {
		id: "1"
	}
	handleReadEmail: async (id) => {
		return await  fetchData(id); // Ваша функция получения данных.
	}
}).then((instance) => { 
	setTimeout(() => instance.show({ id: "2" }), 1000)
});

События

| Обработчик события | Описание | | ------------------------- | -------------------------------------------- | | handleReadEmail | Чтение письма | | handleSaveEmail | Сохранение / обновление письма | | handleReadEmailRevisions | Чтение списка автосохранений | | handleEmailAutosave | Автосохранение | | handleReadBlocks | Чтение списка блоков проекта | | handleSaveBlock | Сохранение / обновление блока проекта | | handleRemoveBlock | Удаление блока проекта | | handleReadComments | Чтение списка комментариев письма | | handleSaveComment | Сохранение / обновление комментария | | handleRemoveComment | Удаление комментария письма | | handleSaveButtonClick | Нажатие кнопки сохранения письма | | handleNextButtonClick | Нажатие кнопки Далее | | handlePreviousButtonClick | Нажатие кнопки Назад | | handleEmailChanged | Изменение любого параметра письма | | handleHtmlChanged | Изменение кода письма | | handleDestroy | Деструкция плагина | | handleLoad | Окончание инициализации экземпляра плагина | | handleLoadImage | Загрузка изображений | | handleNotify | Уведомление | | handleError | Уведомление типа Ошибка | | handleSuccess | Уведомление типа Успех | | handleTestEmailSend | Отправка тестового письма | | handleTestEmailModal | Открытие модального окна тестового письма |

Методы

| Метод | Описание | | ------------------------- | -------------------------------------------- | | init | Инициализация (async) | | show | Изменение содержимого после инициализации | | destroy | Деструкция экземпляра | | reset | Сброс всей конфигурации | | getEmail | Получение текущего письма | | getConfig | Получение конфигурации | | getBlocks | Получение блоков проекта | | getComments | Получение комментариев письма | | getEmailRevisions | Получение списка контроля версий | | setConfig | Установка новых парамеров config | | updateConfig | Добавление к параметрам config | | notify | Показ уведомлений | | getElement | Получение элемента инициализации | | save | Сохраенние письма. | | compileEmail | Получение скопмилированного письма |

📂 Файловый менеджер

Для включения файлового менеджера необходимо в конфигурации инициализации указать параметры:

emailmaker.init({
  storageProvider: ..., // реализация интерфейса StorageProvider
  config: {
    imageCenterFileManagerView: true
  }
});

Секция fileManager управляет возможностями файлового менеджера. Все поля необязательные; если не заданы или false, соответствующая функция отключена.

Basic Operations

• enableTrash — включает функциональность корзины для удаленных файлов. При включении файлы перемещаются в корзину вместо полного удаления. По умолчанию true
• enableRenameFolder — разрешает переименование папок. По умолчанию true
• enableRenameFile — разрешает переименование файлов. По умолчанию true
• enableUpdateFile — разрешает обновление содержимого или метаданных файлов. По умолчанию true
• enableEdit — разрешает редактирование файлов (изменение содержимого или свойств). По умолчанию true
• enableMoveFile — разрешает перемещение файлов между папками. По умолчанию true
• enableMoveFolder — разрешает перемещение папок. По умолчанию true
• enableCopyFile — разрешает копирование файлов. По умолчанию true
• enableCopyFolder — разрешает копирование папок. По умолчанию true
• enableDelete — разрешает удаление файлов и папок. При включенной корзине файлы перемещаются в корзину. По умолчанию true
• multiSelect — разрешает множественный выбор файлов и папок для групповых операций. По умолчанию true
• defaultFolderName — Имя папки по умолчанию

Pagination & Display

• enablePagination — разрешает постраничную навигацию. Если отключено, все элементы загружаются сразу. По умолчанию true

Client-Side Processing

• clientSideSorting — клиентская сортировка файлов.

  • Если true, применяется стандартная сортировка (по имени по возрастанию).
  • Если указана функция, она принимает текущий массив файлов, необязательные sortBy и sortOrder, и возвращает отсортированный массив.

• clientSidePaging — клиентская пагинация файлов.

  • Если true, применяется стандартная нарезка массива по page и limit.
  • Если указана функция, она принимает массив файлов, page и limit, и возвращает массив только для нужной страницы.

• clientSideFilter — клиентская фильтрация файлов.

  • Если true, применяется стандартная фильтрация по тексту search.
  • Если указана функция, она принимает массив файлов и необязательный search, и возвращает отфильтрованный массив.

Cache Strategy

• cacheStrategy — стратегия кэширования для оптимизации производительности.
  • ttl — время жизни кэша в миллисекундах. По умолчанию 300000 (5 минут)
  • errorTtl — время жизни кэша для ошибок в миллисекундах. По умолчанию 60000 (1 минута)
  • allowSortedInsert — разрешает вставку элемента в отсортированный массив без полной инвалидации кэша. По умолчанию false
  • allowSearchInsert — разрешает вставку элемента в массив с фильтрами без полной инвалидации кэша. По умолчанию false
  • invalidateOnPaginationFull — если страница полная, кэш помечается как устаревший при вставке нового элемента. По умолчанию true
  • comparator — функция сравнения двух файлов для сортировки. По умолчанию сравнение по имени
  • filterMatch — функция проверки, проходит ли файл текущий фильтр. По умолчанию поиск по имени

Интерфейс StorageProvider

Свойства

| Свойство | Тип | Описание | По умолчанию | |----------|------|-------------|---------| | pathMode | boolean | Использовать путь как идентификатор для папок | - | | rootId | string | Пользовательский идентификатор корневой папки | '' | | trashPath | string | Путь к корзине/папке для удаленных файлов | - | | tempPath | string | Путь к временной папке для загрузок | - | | useSoftDelete | boolean | Включить программное мягкое удаление | false | | ensureFolderTrailingSlash | boolean | Добавлять к путям папок завершающий слэш | true | | validateDuplicates | boolean | Проверка на существование при операциях с файлами и папками | - |

Методы

Основные методы

| Метод | Параметры | Возвращает | Описание | |--------|------------|---------|-------------| | getItems | options:- folderId?: string- search?: string- sortBy?: string- sortOrder?: 'asc'\|'desc'- page?: number- limit?: number- itemType: 'all'\|'file'\|'folder' | { items: FileSystemItem[], pagination?: Partial<ApiPaginationResponse> } | Получить список файлов и папок с фильтрацией, сортировкой, пагинацией | | createFolder | name: string, parentid?: string | FileSystemItem | Создать новую папку | | uploadFile | file: - name: string- size: number- type: string- folderId?: string- data: Blob \| string- thumbnail?: string- dimensions?: string- aspectRatio?: string- extension?: string | FileSystemItemUpdate | Загрузить файл с метаданными | | uploadFiles | request:- items: массив объектов:    - requestId?: string — необязательный идентификатор для сопоставления результата    - name: string — имя файла    - size: number — размер файла в байтах    - type: string — MIME-тип файла    - folderId?: string \| null — целевая папка    - data: Blob \| string — содержимое файла    - extension?: string — расширение файла- folderId?: string \| null — папка для загрузки по умолчанию | BatchResult<UploadFileResultData> | Загрузить несколько файлов. Порядок элементов важен — при отсутствии requestId результаты сопоставляются по индексу | | uploadFileByUrl | url: string, folderId?: string | FileSystemItem | Загрузить файл по URL (проверять существующие файлы) | | findItemByPath | path: string | FileSystemItem \| undefined | Найти системные файлы/папки по пути | | setController | controller: StorageProviderController | void | Установить контроллер управления кэшем | | getFileData | file: FileSystemItem | Blob | Получить содержимое файла как blob | | getUrl | file: FileSystemItem | string | Получить URL для доступа к файлу | | getThumbnailUrl | file: FileSystemItem | string | Получить URL миниатюры | | renameItem | item: FileSystemItem, newName: string | FileSystemItemUpdate | Переименовать файл/папку | | deleteItem | item: FileSystemItem | void | Удалить один элемент (перемещает в корзину при мягком удалении) | | deleteItems | items: FileSystemItem[] | BatchResult<never> | Удалить несколько элементов | | moveItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Переместить один элемент | | moveItems | items: FileSystemItem[], targetFolderId?: string | BatchResult<FileSystemItemUpdate> | Переместить несколько элементов | | copyItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Копировать один элемент | | copyItems | items: FileSystemItem[], targetFolderId?: string | BatchResult<FileSystemItemUpdate> | Копировать несколько элементов | | updateFile | file: FileSystemItem, updates: объект с метаданными | FileSystemItemUpdate | Обновить метаданные/содержимое файла |

Определения типов

• MayBePromise<T>: T | Promise<T>
• FileSystemItem: Объект файла или папки
• FileSystemItemUpdate: Элемент с измененными полями
• BatchResult<T>: Результат с деталями успеха/ошибки
• ApiPaginationResponse: Метаданные пагинации

Важные примечания

• Мягкое удаление: Когда useSoftDelete=true, операции удаления перемещают элементы в trashPath
• Корневая папка: Используйте rootId или пустую строку для операций с корневой папкой
• Разрешение путей: trashPath и tempPath преобразуются в реальные идентификаторы папок
• Загрузка по URL: Должна проверять, существует ли файл уже на текущем сервере
• Управление кэшем: Используйте setController для запросов инвалидации кэша
• Двойное мягкое удаление: Если бэкенд уже реализует мягкое удаление, оставьте useSoftDelete=false