Установка

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

``cmd
$ npm i @emailmaker/emailmaker@1.0.103 -save
`

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


$3


Импорт пакета:
`javascript
const emailMakerPlugin = require('@emailmaker/emailmaker/webpack')
`
Определение пакета в приложении:
`javascript
module.exports = {
plugins: [
new EmailmakerWebpackPlugin(),
]
}
`

$3

Импорт пакета:
`javascript
import emailMakerPlugin from 'emailmaker/vite'
`
Определение пакета в приложении:
`javascript
export default defineConfig({
plugins: [emailMakerPlugin()],
})
`

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

Импортируйте EmailMaker plugin в вашем компоненте:
`javascript
import * as emailmaker from "@emailmaker/emailmaker"
`
Параметры инициализации плагина содержат параметр getAuthToken. В него должна быть передана функция, которая запрашивает авторизационный OAuth токен по Client ID и Client Secret.

$3

`curl
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'
`

$3

`javascript
emailmaker.init({
getAuthToken: getAuthToken,
element: "#test",
content: {
title: "Email subject",
html: КОД_ПИСЬМА,
},
config: { }
}).then(instance => { })
`
КОД_ПИСЬМА можно взять из нашего образца или вставить HTML-код своего письма.

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

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

$3

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

$3

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

#### {string}

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

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

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

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

$3


Раздел для настройки внешнего вида и настроек редактора. Вы можете изменить конфигурацию этого раздела после инициализации, используя 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 |
| templateNotEmAlertShow | Показ уведомления о том, что шаблон не из EM. | 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 |

$3

События могут быть переданы в конфигурации или добавлены после при работе с экземпляром плагина. Все подписчики событий могут быть асинхронными функциями.
#### Пример
`javascript
emailmaker.init({
....,
// Подписка на события в инициализации.
handleReadEmail: (e) => {},
handleSaveEmail: async (e) => {}
}).then((instance) => {
// Подписка на события после инициализации.
const dispose = instance.handleReadEmail(e => {});
const dispose = instance.handleSaveEmail(async (e) => {});
});
`
Передавая асинхронную функцию, вы можете реализовать асинхронную загрузку данных.
#### Пример
`javascript
emailmaker.init({
element: "#test",
content: {
id: "1"
}
handleReadEmail: async (id) => {
return await fetchData(id); // Ваша функция получения данных.
}
}).then((instance) => {
setTimeout(() => instance.show({ id: "2" }), 1000)
});
`

$3

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

$3

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

$3

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

`ts
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 — функция проверки, проходит ли файл текущий фильтр. По умолчанию поиск по имени




$3

#### Свойства

| Свойство | Тип | Описание | По умолчанию |
|----------|------|-------------|---------|
| 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 } | Получить список файлов и папок с фильтрацией, сортировкой, пагинацией |
| 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 | Загрузить несколько файлов. Порядок элементов важен — при отсутствии 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 | Удалить несколько элементов |
| moveItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Переместить один элемент |
| moveItems | items: FileSystemItem[], targetFolderId?: string | BatchResult | Переместить несколько элементов |
| copyItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Копировать один элемент |
| copyItems | items: FileSystemItem[], targetFolderId?: string | BatchResult | Копировать несколько элементов |
| updateFile | file: FileSystemItem, updates: объект с метаданными | FileSystemItemUpdate | Обновить метаданные/содержимое файла |

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

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

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

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