Продукты Р7
Корпоративный сервер 2024
Корпоративный сервер 2024
Сервер документов
Сервер документов
Редакторы документов
Редакторы документов
Корпоративный сервер 2019
Корпоративный сервер 2019
Графика
Графика
ВКС и мессенджер
ВКС и мессенджер
Мобильные редакторы
Мобильные редакторы
Почтовый сервер
Почтовый сервер
Органайзер
Органайзер
Сервер лицензирования
Сервер лицензирования
Файл-Экспресс
Файл-Экспресс
Аналитика
Аналитика
Дополнительно
Часто задаваемые вопросы
Разработчикам
Интеграции
Новые возможности

Создание первого плагина: пошаговый пример

Обновлено: 16.11.26

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

Что понадобится:

  • установленные Десктоп редакторы Р7;
  • текстовый редактор для кода, например Visual Studio Code или Блокнот;
  • архиватор для упаковки в ZIP (в Windows и macOS он встроен).

Итоговая структура плагина:

helloworld/
├── config.json
├── index.html
├── code.js
└── resources/
    ├── icon.png
    └── icon@2x.png

Шаг 1. Создайте папку и получите GUID

  1. Создайте в любом месте папку helloworld, а в ней — папку resources.
  2. Получите 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 }
      ]
    }
  ]
}

Что здесь важно:

ПараметрЗначение в примере
guidGUID из шага 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);

Как это работает:

  1. init вызывается, когда плагин запущен. Здесь он ставит курсор в поле ввода.
  2. button вызывается по нажатию кнопки в окне. Номер 0 — первая кнопка из config.json («Вставить»), 1 — «Отмена», -1 — крестик в углу окна.
  3. По кнопке «Вставить» плагин записывает текст из поля в Asc.scope и передаёт функцию в редактор через callCommand. Функция выполняется внутри редактора: создаёт абзац и вставляет его в позицию курсора. Второй параметр true закрывает окно плагина после вставки.
  4. По любой другой кнопке плагин просто закрывает окно.

Функция внутри callCommand не видит переменные плагина — поэтому текст передаётся через Asc.scope. Подробнее об этом — в статье «Как плагин взаимодействует с редактором».

Шаг 5. Добавьте иконку

Положите в папку resources два файла PNG:

ФайлРазмерДля чего
icon.png28 × 28 пикселейОбычные экраны
icon@2x.png56 × 56 пикселейЭкраны с высокой плотностью пикселей

Иконка покажется на кнопке плагина на вкладке Плагины и в списке в окне Настройки. Пути к файлам заданы в параметре icons в config.json. Как сделать отдельные иконки для светлой и тёмной темы, рассказано в статье «Иконки плагинов» ↗.

Шаг 6. Установите и запустите плагин

  1. Выделите все файлы и папку внутри helloworld (не саму папку helloworld) и упакуйте их в ZIP.
  2. Переименуйте архив в helloworld.plugin.
  3. Откройте в Десктоп редакторах новый документ и перейдите на вкладку Плагины.
  4. Нажмите Настройки → Добавить плагин и выберите helloworld.plugin. Плагин «Привет, мир» появится в списке. Нажмите ОК.
  5. На вкладке Плагины нажмите кнопку Привет, мир. Откроется окно с полем ввода.
  6. Нажмите Вставить. Окно закроется, а в документе появится текст «Привет, мир!».

Готово: первый плагин работает.

Если что-то пошло не так

Что происходитЧто проверить
Плагин не появился после добавленияconfig.json лежит в корне архива, а не внутри папки helloworld
Окно открывается, но «Вставить» ничего не делаетПуть к plugins.js в index.html и подключение code.js
Вместо русских букв нечитаемые символыФайлы сохранены в UTF-8

Если причина не нашлась, см. «Отладка плагина».

Что дальше

Попробуйте доработать плагин:

  • добавить в список EditorsSupport таблицы и презентации и вставлять текст через executeMethod("PasteText") — этот метод работает во всех трёх редакторах [проверить в таблицах и презентациях];
  • сделать плагин боковой панелью: isModal: false, isInsideMode: true.

Для этого пригодятся статьи:

  • «Как плагин взаимодействует с редактором: callCommand, executeMethod и события»;
  • «Отладка плагина»;
  • «Установка и удаление плагина»;
  • Справочник API плагинов: config.json, методы и события.

Была ли эта статья полезной?

Поделитесь пожалуйста своим мнением

      В статье есть ошибкиРекомендации не помоглиТекст трудно понятьСодержание статьи не соответствует заголовкуДругое