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

Как плагин взаимодействует с редактором: callCommand, executeMethod и события

Обновлено: 16.11.26

Код плагина и редактор работают в разных местах. Плагин загружается в отдельном окне (файл index.html и подключенные в него скрипты) и не видит документ напрямую. Чтобы прочитать или изменить документ, плагин обращается к редактору через объект window.Asc.plugin.

Способов связи три:

  • callCommand — передать в редактор функцию, которая работает с документом через объект Api.
  • executeMethod — вызвать готовый метод редактора по имени, например получить выделенный текст или вставить комментарий.
  • События — редактор сам сообщает плагину, что произошло: плагин запущен, нажата кнопка, изменилось положение курсора.

Из статьи вы узнаете, как работает каждый способ и какой выбрать для своей задачи.

Окно плагина и редактор — три канала связи

Два канала идут от плагина к редактору: плагин просит сделать что-то с документом. Третий идёт обратно: редактор сообщает плагину о том, что произошло.

callCommand: выполнить код внутри редактора

callCommand передаёт в редактор функцию, и редактор выполняет её у себя. Внутри функции доступен объект Api: через него можно создавать абзацы, таблицы и диаграммы, читать и менять содержимое документа.

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

Как передать данные: Asc.scope

Функция выполняется в редакторе, поэтому не видит переменные из кода плагина. Чтобы передать в неё данные, запишите их в объект Asc.scope до вызова callCommand. В Asc.scope можно класть только данные, которые преобразуются в JSON: строки, числа, массивы, простые объекты. Функции и элементы страницы передать нельзя.

Пример

Плагин берёт текст из поля ввода и добавляет его абзацем в конец документа:

Asc.scope.text = document.getElementById("input-text").value;
window.Asc.plugin.callCommand(function () {
    var oDocument = Api.GetDocument();
    var oParagraph = Api.CreateParagraph();
    oParagraph.AddText(Asc.scope.text);
    oDocument.Push(oParagraph);
}, false, true, function () {
    console.log("Абзац добавлен");
});

Параметры callCommand:

ПараметрЧто задаёт
funcФункция, которую выполнит редактор
isClosetrue — закрыть окно плагина после выполнения
isCalctrue — пересчитать документ после изменений. Если функция только читает данные, можно передать false
callbackФункция в плагине, которая получит значение, возвращённое из func

Чтобы получить данные из документа, верните их из функции через return. Результат придёт в callback. Объекты Api вернуть нельзя, только данные: строку, число, массив.

Подробнее: callCommand ↗, Объект Asc.scope ↗.

executeMethod: вызвать готовый метод редактора

executeMethod вызывает метод, который редактор уже умеет выполнять: получить выделенный текст, вставить текст в позицию курсора, добавить комментарий, принять исправления. Плагин передаёт имя метода и параметры, а редактор возвращает результат.

Используйте executeMethod, когда нужное действие есть в списке методов executeMethod. Это проще, чем писать то же самое через callCommand, а некоторые действия, например работа с выделением и курсором, доступны только так.

Результат приходит в callback

executeMethod работает асинхронно: вызов сразу завершается, а результат приходит позже в функцию callback. Код, которому нужен результат, пишите внутри callback. Если callback не передан, результат приходит в обработчик window.Asc.plugin.onMethodReturn.

Вызовы выполняются по одному: если плагин вызвал executeMethod, пока предыдущий ещё не вернул результат, новый вызов встаёт в очередь и выполнится после него.

Пример

Плагин получает выделенный текст, переводит его в верхний регистр и вставляет на место выделения:

window.Asc.plugin.executeMethod("GetSelectedText", [], function (text) {
    if (!text) {
        return;
    }
    window.Asc.plugin.executeMethod("PasteText", [text.toUpperCase()]);
});

Второй вызов стоит внутри callback первого: текст нужен до вставки, а на момент выхода из первого executeMethod его ещё нет.

GetSelectedText возвращает текст вместе с переводом строки в конце абзаца. Если он не нужен, уберите его через text.trim().

Методы executeMethod сгруппированы по задачам в статье «executeMethod»: текст и выделение, комментарии, рецензирование, элементы управления содержимым и другие. У каждого метода указано, в каких редакторах он работает.

События: редактор сообщает плагину

События работают в обратную сторону: редактор вызывает функцию плагина, когда что-то происходит. Плагин задаёт обработчики заранее, свойствами объекта window.Asc.plugin.

Два события есть почти в каждом плагине:

  • init — плагин запущен. С него начинается работа: вызывать callCommand и executeMethod можно только после него. В параметре приходят данные, тип которых задан в config.json (параметр initDataType), например выделенный текст.
  • button — пользователь нажал кнопку в окне плагина. В параметре приходит номер кнопки из списка buttons в config.json. Значение -1 означает, что окно закрыли крестиком. Если обработчик button не задан, по крестику плагин закрывается автоматически.

Кроме них, редактор сообщает о событиях в документе: onClick, onTargetPositionChanged (курсор переместился), onInputHelperInput и onInputHelperClear (помощник ввода), onInsertOleObjects, а в Документах — о событиях элементов управления и комментариев. Такие события приходят, только если они перечислены в параметре events вариации в config.json, например "events": ["onTargetPositionChanged"]. Обработчик задаётся свойством event_ + имя события или через window.Asc.plugin.attachEvent; если заданы оба, вызывается event_. Без подписки приходят только onContextMenuClick (выбран пункт контекстного меню, добавленный плагином) и onKeyDown (нажата клавиша, пока открыт помощник ввода). Полный список с редакторами и передаваемыми данными — в статье «События».

Пример

Плагин показывает выделенный текст при запуске и закрывается по любой кнопке:

(function (window) {
    window.Asc.plugin.init = function (text) {
        document.getElementById("selected").innerText = text || "Ничего не выделено";
    };
    window.Asc.plugin.button = function (id) {
        this.executeCommand("close", "");
    };
    window.Asc.plugin.event_onTargetPositionChanged = function () {
        console.log("Курсор переместился");
    };
})(window);

В примере окно закрывается через executeCommand("close", ""). Другие вызовы executeCommand устарели, но для закрытия окна это текущий способ: так же окно закрывает сама библиотека плагинов. Чтобы событие onTargetPositionChanged срабатывало, добавьте его в events в config.json.

Как выбрать способ

ЗадачаСпособ
Получить или заменить выделенный текстexecuteMethod: GetSelectedText, PasteText
Вставить текст или HTML в позицию курсораexecuteMethod: PasteText, PasteHtml
Работать с комментариями и исправлениямиexecuteMethod: группы «Комментарии» и «Рецензирование»
Собрать таблицу, список или несколько абзацевcallCommand
Пройти по всему документу и что-то найти или изменитьcallCommand
Работать с ячейками таблицы или слайдамиcallCommand
Отреагировать на действие пользователя в документеСобытия

Правило простое: если нужное действие есть в списке методов executeMethod, берите его. Если нужно произвольное изменение документа, пишите его через callCommand. В одном плагине способы можно сочетать.

Частые ошибки

Что происходитПричинаКак исправить
Внутри callCommand переменная плагина равна undefinedФункция выполняется в редакторе и не видит переменные плагинаПередайте данные через Asc.scope
Результат executeMethod равен undefinedРезультат читают сразу после вызова, а он приходит позжеИспользуйте результат внутри callback
Ничего не происходит при запуске плагинаcallCommand или executeMethod вызваны до события initПеренесите вызов в обработчик init
Окно плагина закрывается после первого действияВ callCommand передан isClose = trueПередайте false
Код для документа не срабатывает в таблицах: callback получает undefined, в консоли ошибка «Cannot read properties of undefined»У каждого редактора свои методы Api: Api.GetDocument работает только в документахПроверьте тип редактора в info.editorType и вызывайте подходящие методы
callback после callCommand получает undefinedИз функции вернули объект Api, а не данныеВерните строку, число или массив

Смотрите также

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

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

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