В этой статье вы соберёте плагин «Привет, мир» для редактора документов. Плагин открывает окно с полем ввода и по кнопке Вставить добавляет введённый текст в документ в позиции курсора. На примере видно все части плагина: настройки, интерфейс, код и связь с документом.
Что понадобится:
- установленные Десктоп редакторы Р7;
- текстовый редактор для кода, например Visual Studio Code или Блокнот;
- архиватор для упаковки в ZIP (в Windows и macOS он встроен).
Итоговая структура плагина:
helloworld/
├── config.json
├── index.html
├── code.js
└── resources/
├── icon.png
└── icon@2x.pngШаг 1. Создайте папку и получите GUID
- Создайте в любом месте папку
helloworld, а в ней — папкуresources. - Получите GUID — уникальный идентификатор плагина. По нему редактор отличает один плагин от другого, поэтому у каждого плагина он свой. В Windows GUID можно получить командой PowerShell:
[guid]::NewGuid().ToString().ToUpper()
В Linux и macOS — командой
uuidgen.
В примерах ниже используется GUID 3F6A8B21-7C4D-4E9A-B5F2-1D8E7C6A9B30. Для своего плагина сгенерируйте новый.
Шаг 2. Опишите плагин в config.json
В папке helloworld создайте файл config.json в кодировке UTF-8. Из него редактор узнаёт название плагина, иконку, размер окна и кнопки:
{
"name": "Hello world",
"nameLocale": { "ru": "Привет, мир" },
"guid": "asc.{3F6A8B21-7C4D-4E9A-B5F2-1D8E7C6A9B30}",
"version": "1.0.0",
"variations": [
{
"description": "Inserts text into the document",
"descriptionLocale": { "ru": "Вставляет текст в документ" },
"url": "index.html",
"icons": ["resources/icon.png", "resources/icon@2x.png"],
"isViewer": false,
"EditorsSupport": ["word"],
"isVisual": true,
"isModal": true,
"isInsideMode": false,
"initDataType": "none",
"initData": "",
"size": [400, 150],
"buttons": [
{ "text": "Insert", "textLocale": { "ru": "Вставить" }, "primary": true },
{ "text": "Cancel", "textLocale": { "ru": "Отмена" }, "primary": false }
]
}
]
}Что здесь важно:
| Параметр | Значение в примере |
|---|---|
guid | GUID из шага 1 с префиксом asc. и в фигурных скобках |
nameLocale, descriptionLocale, textLocale | Переводы названия, описания и кнопок. В русском интерфейсе редактор покажет «Привет, мир», «Вставить» и «Отмена» |
url | Страница плагина, которая откроется в окне |
EditorsSupport | Плагин работает только в редакторе документов (word): код в шаге 4 использует методы документа |
isVisual, isModal | Плагин открывается в отдельном окне |
size | Ширина и высота окна в пикселях |
buttons | Кнопки внизу окна. Их номера по порядку (0, 1) придут в код плагина |
Остальные параметры описаны в статье «config.json» ↗.
Шаг 3. Сделайте интерфейс в index.html
Создайте файл index.html. Это обычная веб-страница, которая откроется в окне плагина:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Hello world</title>
<script type="text/javascript" src="../v1/plugins.js"></script>
<script type="text/javascript" src="../v1/plugins-ui.js"></script>
<link rel="stylesheet" href="../v1/plugins.css">
<script type="text/javascript" src="code.js"></script>
</head>
<body style="padding: 12px;">
<label for="text">Текст для вставки:</label>
<input id="text" class="form-control" type="text" value="Привет, мир!" style="width: 100%;
margin-top: 6px;">
</body>
</html>Три первых подключения обязательны для любого плагина:
plugins.js— библиотека плагинов: создаёт объектwindow.Asc.pluginи связывает плагин с редактором. Без неё плагин не работает.plugins-ui.jsиplugins.css— элементы интерфейса и стили в оформлении редактора, например классform-controlу поля ввода.
Файлы подключаются по относительному пути ../v1/: копировать их в плагин не нужно. Они лежат в папке v1 рядом с папками всех плагинов, и так же их подключают встроенные плагины.
Шаг 4. Напишите код в code.js
Создайте файл code.js:
(function (window) {
window.Asc.plugin.init = function () {
document.getElementById("text").focus();
};
window.Asc.plugin.button = function (id) {
if (id === 0) {
Asc.scope.text = document.getElementById("text").value;
this.callCommand(function () {
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText(Asc.scope.text);
oDocument.InsertContent([oParagraph]);
}, true);
} else {
this.executeCommand("close", "");
}
};
})(window);Как это работает:
initвызывается, когда плагин запущен. Здесь он ставит курсор в поле ввода.buttonвызывается по нажатию кнопки в окне. Номер 0 — первая кнопка изconfig.json(«Вставить»), 1 — «Отмена», -1 — крестик в углу окна.- По кнопке «Вставить» плагин записывает текст из поля в
Asc.scopeи передаёт функцию в редактор черезcallCommand. Функция выполняется внутри редактора: создаёт абзац и вставляет его в позицию курсора. Второй параметрtrueзакрывает окно плагина после вставки. - По любой другой кнопке плагин просто закрывает окно.
Функция внутри callCommand не видит переменные плагина — поэтому текст передаётся через Asc.scope. Подробнее об этом — в статье «Как плагин взаимодействует с редактором».
Шаг 5. Добавьте иконку
Положите в папку resources два файла PNG:
| Файл | Размер | Для чего |
|---|---|---|
icon.png | 28 × 28 пикселей | Обычные экраны |
icon@2x.png | 56 × 56 пикселей | Экраны с высокой плотностью пикселей |
Иконка покажется на кнопке плагина на вкладке Плагины и в списке в окне Настройки. Пути к файлам заданы в параметре icons в config.json. Как сделать отдельные иконки для светлой и тёмной темы, рассказано в статье «Иконки плагинов» ↗.
Шаг 6. Установите и запустите плагин
- Выделите все файлы и папку внутри
helloworld(не саму папкуhelloworld) и упакуйте их в ZIP. - Переименуйте архив в
helloworld.plugin. - Откройте в Десктоп редакторах новый документ и перейдите на вкладку Плагины.
- Нажмите Настройки → Добавить плагин и выберите
helloworld.plugin. Плагин «Привет, мир» появится в списке. Нажмите ОК. - На вкладке Плагины нажмите кнопку Привет, мир. Откроется окно с полем ввода.
- Нажмите Вставить. Окно закроется, а в документе появится текст «Привет, мир!».
Готово: первый плагин работает.
Если что-то пошло не так
| Что происходит | Что проверить |
|---|---|
| Плагин не появился после добавления | config.json лежит в корне архива, а не внутри папки helloworld |
| Окно открывается, но «Вставить» ничего не делает | Путь к plugins.js в index.html и подключение code.js |
| Вместо русских букв нечитаемые символы | Файлы сохранены в UTF-8 |
Если причина не нашлась, см. «Отладка плагина».
Что дальше
Попробуйте доработать плагин:
- добавить в список EditorsSupport таблицы и презентации и вставлять текст через
executeMethod("PasteText")— этот метод работает во всех трёх редакторах [проверить в таблицах и презентациях]; - сделать плагин боковой панелью: isModal: false, isInsideMode: true.
Для этого пригодятся статьи:
- «Как плагин взаимодействует с редактором: callCommand, executeMethod и события»;
- «Отладка плагина»;
- «Установка и удаление плагина»;
- Справочник API плагинов: config.json, методы и события.













