Код плагина и редактор работают в разных местах. Плагин загружается в отдельном окне (файл 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 | Функция, которую выполнит редактор |
| isClose | true — закрыть окно плагина после выполнения |
| isCalc | true — пересчитать документ после изменений. Если функция только читает данные, можно передать 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, а не данные | Верните строку, число или массив |













