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

Пример плагина: индикатор долгой операции

Обновлено: 18.11.26

Инструкция актуальна для версий продукта: 2026.3.1.3296 – 2026.3.1.3906

Задача

Плагин выполняет долгую операцию и на это время показывает индикатор, чтобы пользователь видел, что работа идет. В примере «загрузка данных» длится 5 секунд, после чего плагин вставляет строку «Отчет сформирован» со временем. В реальном плагине на этом месте будет запрос к серверу или расчет.

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

Редакторы: Документы, Таблицы, Презентации.

Методы

МетодЧто делает в примере
StartAction ↗Показывает индикатор. С типом "Block" — окно со спиннером поверх документа, с любым другим типом — текст в строке состояния.
EndAction ↗Убирает индикатор. Тип и текст передаются те же, что в StartAction.
callCommandВставляет результат через Document Builder API: абзац в Документах, значение активной ячейки в Таблицах, надпись на текущем слайде в Презентациях.

Как работает callCommand и зачем нужен Asc.scope, описано в статье Как плагин взаимодействует с редактором ↗.

Важно

Пока действует блокировка "Block", редактор не выполняет код из callCommand: функция обратного вызова сработает, но документ не изменится и ошибки не будет. Поэтому сначала вызовите EndAction, а уже потом вставляйте результат. В режиме без блокировки callCommand работает и при включенном индикаторе, но для единообразия плагин делает так же.

Код плагина

Плагин состоит из трех файлов и папки с иконками. GUID в config.json у каждого плагина свой: для своего плагина сгенерируйте новый.

config.json

{
    "name": "Long operation",
    "nameLocale": { "ru": "Индикатор операции" },
    "guid": "asc.{259A32EB-69BE-470E-B975-5B91362237EC}",
    "version": "1.0.0",
    "variations": [
        {
            "description": "Shows a progress indicator while the plugin is working",
            "descriptionLocale": { "ru": "Показывает индикатор, пока плагин выполняет долгую операцию" },
            "url": "index.html",
            "icons": [ "resources/icon.png", "resources/icon@2x.png" ],
            "isViewer": false,
            "EditorsSupport": [ "word", "cell", "slide" ],
            "isVisual": true,
            "isModal": false,
            "isInsideMode": true,
            "initDataType": "none",
            "initData": "",
            "buttons": []
        }
    ]
}

index.html

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Long operation</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;">
    <p>Плагин 5 секунд «загружает данные», а потом вставляет строку отчета в документ.</p>
    <button id="block" class="btn-text-default" style="width: 100%; margin-bottom: 6px;">С блокировкой</button>
    <button id="info" class="btn-text-default" style="width: 100%; margin-bottom: 12px;">Без блокировки</button>
    <p id="status" style="color: #7d858c;"></p>
</body>
</html>

code.js

// Пример «Индикатор долгой операции». Автор: Александр Поляков
(function (window) {
    var DESCRIPTION = "Загрузка данных отчета...";
    var busy = false;

    function setStatus(text) {
        document.getElementById("status").textContent = text;
    }

    // Имитация долгой работы: запрос к серверу, расчет и т. п.
    function loadData(callback) {
        setTimeout(function () {
            callback("Отчет сформирован: " + new Date().toLocaleTimeString("ru-RU"));
        }, 5000);
    }

    // Вставка результата: у каждого редактора свой способ
    function insertResult(text, done) {
        Asc.scope.text = text;
        Asc.scope.editor = window.Asc.plugin.info.editorType;
        window.Asc.plugin.callCommand(function () {
            if (Asc.scope.editor === "word") {
                var paragraph = Api.CreateParagraph();
                paragraph.AddText(Asc.scope.text);
                Api.GetDocument().InsertContent([paragraph]);
            } else if (Asc.scope.editor === "cell") {
                Api.GetActiveSheet().GetActiveCell().SetValue(Asc.scope.text);
            } else if (Asc.scope.editor === "slide") {
                var shape = Api.CreateShape("rect", 6000000, 800000,
                    Api.CreateNoFill(), Api.CreateStroke(0, Api.CreateNoFill()));
                shape.SetPosition(600000, 600000);
                shape.GetDocContent().GetElement(0).AddText(Asc.scope.text);
                Api.GetPresentation().GetCurrentSlide().AddObject(shape);
            }
        }, false, true, done);
    }

    function run(type) {
        if (busy) {
            return;
        }
        busy = true;
        setStatus("Выполняется...");
        // 1. Показываем индикатор
        window.Asc.plugin.executeMethod("StartAction", [type, DESCRIPTION]);
        loadData(function (text) {
            // 2. Убираем индикатор с теми же параметрами.
            //    Пока действует блокировка, callCommand не выполняется,
            //    поэтому EndAction вызываем до вставки результата.
            window.Asc.plugin.executeMethod("EndAction", [type, DESCRIPTION], function () {
                // 3. Вставляем результат
                insertResult(text, function () {
                    busy = false;
                    setStatus("Готово.");
                });
            });
        });
    }

    window.Asc.plugin.init = function () {
        document.getElementById("block").onclick = function () { run("Block"); };
        document.getElementById("info").onclick = function () { run("Information"); };
    };

    window.Asc.plugin.button = function () {
        this.executeCommand("close", "");
    };
})(window);

Флаг busy не дает запустить вторую операцию, пока не закончилась первая: иначе два вызова StartAction наложатся друг на друга.

Как установить и проверить

  1. Создайте папку плагина, положите в нее три файла и папку resources с иконками и установите плагин по инструкции Установка и удаление плагина ↗.
  2. Откройте документ и поставьте курсор на пустую строку. В Таблицах выделите ячейку, в Презентациях откройте нужный слайд.
  3. На вкладке Плагины нажмите Индикатор операции, затем в панели — С блокировкой или Без блокировки. Через 5 секунд индикатор исчезнет и появится строка отчета.

Если индикатор не исчезает или строка не вставляется, откройте консоль плагина по инструкции Отладка плагина ↗.

Результат

С блокировкой ("Block") поверх документа появляется окно со спиннером и текстом из второго параметра:

Без блокировки ("Information«) тот же текст показывается в строке состояния внизу окна:

После EndAction индикатор исчезает, и плагин вставляет строку отчета. Так это выглядит в Документах, Таблицах и Презентациях:

Как доработать

  • Настоящий запрос. Замените setTimeout в loadData на fetch к своему сервису. Вызывайте EndAction и при ошибке запроса, например в finally: иначе с блокировкой пользователь не сможет работать с документом.
  • Этапы операции. Для длинной операции меняйте текст индикатора по этапам: EndAction со старым текстом, затем StartAction с новым, например «Загрузка…» → «Расчет…».

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

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

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