Задача
Плагин выполняет долгую операцию и на это время показывает индикатор, чтобы пользователь видел, что работа идет. В примере «загрузка данных» длится 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 наложатся друг на друга.
Как установить и проверить
- Создайте папку плагина, положите в нее три файла и папку resources с иконками и установите плагин по инструкции Установка и удаление плагина ↗.
- Откройте документ и поставьте курсор на пустую строку. В Таблицах выделите ячейку, в Презентациях откройте нужный слайд.
- На вкладке Плагины нажмите Индикатор операции, затем в панели — С блокировкой или Без блокировки. Через 5 секунд индикатор исчезнет и появится строка отчета.
Если индикатор не исчезает или строка не вставляется, откройте консоль плагина по инструкции Отладка плагина ↗.
Результат
С блокировкой ("Block") поверх документа появляется окно со спиннером и текстом из второго параметра:

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

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



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













