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

Работа с OLE-объектами

Обновлено: 18.11.26

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

Что такое OLE-объект плагина

OLE-объект — это картинка в документе, за которой скрыты данные плагина. В объекте хранятся три вещи:

  • картинка, которую видит пользователь;
  • строка данных, из которой эта картинка нарисована;
  • GUID плагина, который создал объект.

Когда пользователь дважды щелкает по объекту, редактор запускает плагин с этим GUID и передает ему сохраненные данные. Плагин показывает их в своем окне, пользователь их меняет, и плагин перерисовывает картинку.

Так делают объекты, которые нужно изменять после вставки: штампы, схемы, графики, QR-коды, формулы. Обычную картинку пришлось бы удалять и вставлять заново.

OLE-объекты плагина работают в Документах, Таблицах и Презентациях.

Как это устроено

Настройки в config.json

ПолеЗначение для OLE
initDataType"ole": плагин работает с OLE-объектами.
isUpdateOleOnResizetrue: когда пользователь меняет размер объекта, редактор запускает плагин без окна, чтобы тот перерисовал картинку под новый размер. С false картинка просто растягивается.

Остальные поля — как у обычного плагина с окном, см. config.json ↗.

Данные объекта в info

Когда плагин открыт двойным щелчком по объекту или запущен после изменения размера, в объекте info ↗ есть поля:

ПолеЧто в нем
objectIdИдентификатор объекта. Нужен для EditOleObject. Если плагин запущен с вкладки Плагины, поля нет.
dataСтрока данных, сохраненная в объекте.
width, heightРазмер объекта в документе, мм.
widthPix, heightPixРазмер картинки в пикселях.
resizetrue, если плагин запущен без окна после изменения размера. В width и height при этом уже новый размер.

Методы

В примере используются два метода. Они есть во всех трех редакторах.

МетодЧто делает
AddOleObject ↗Вставляет новый объект. Принимает { guid, data, imgSrc, width, height, widthPix, heightPix }.
EditOleObject ↗Заменяет данные и картинку существующего объекта. Принимает те же поля, только вместо guid — objectId.

Поля параметра:

  • guid — GUID плагина из info.guid. По нему редактор находит плагин при двойном щелчке;
  • data — строка данных. Чтобы сохранить объект, упакуйте его в JSON.stringify;
  • imgSrc — картинка, например data URL из canvas.toDataURL();
  • width, height — размер в документе, мм;
  • widthPix, heightPix — размер картинки в пикселях.

Если data — не строка, width или height — не число или imgSrc пустой, метод ничего не вставляет. Функция обратного вызова при этом срабатывает как обычно, поэтому по ней нельзя понять, удалась ли вставка.

В Документах есть еще методы для работы со всеми OLE-объектами документа: GetAllOleObjects, SelectOleObject, ChangeOleObject, ChangeOleObjects, RemoveOleObject, RemoveOleObjects, InsertOleObject. В Таблицах и Презентациях их нет. Краткое описание — в статье executeMethod: методы по задачам ↗.

Пример: штамп согласования

Плагин вставляет штамп со статусом, фамилией и датой. Штамп рисуется на canvas, а его поля хранятся в объекте строкой JSON. По двойному щелчку плагин открывается с данными штампа, а при изменении размера перерисовывает его. Плагин состоит из трех файлов и папки с иконками. GUID в config.json у каждого плагина свой: для своего плагина сгенерируйте новый.

config.json

{
    "name": "Approval stamp",
    "nameLocale": { "ru": "Штамп согласования" },
    "guid": "asc.{B7E2D3C5-6A4F-4E81-9B2C-2D3E4F5A6B72}",
    "version": "1.0.0",
    "variations": [
        {
            "description": "Inserts an editable approval stamp",
            "descriptionLocale": { "ru": "Вставляет штамп согласования, который можно изменить" },
            "url": "index.html",
            "icons": [ "resources/icon.png", "resources/icon@2x.png" ],
            "isViewer": false,
            "EditorsSupport": [ "word", "cell", "slide" ],
            "isVisual": true,
            "isModal": true,
            "isInsideMode": false,
            "initDataType": "ole",
            "initData": "",
            "isUpdateOleOnResize": true,
            "size": [ 360, 260 ],
            "buttons": [
                { "text": "OK", "primary": true, "textLocale": { "ru": "Вставить" } },
                { "text": "Cancel", "primary": false, "textLocale": { "ru": "Отмена" } }
            ]
        }
    ]
}

index.html

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Approval stamp</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="status">Статус</label>
    <select id="status" class="form-control" style="width: 100%; margin: 4px 0 8px;">
        <option>СОГЛАСОВАНО</option>
        <option>НА ДОРАБОТКУ</option>
        <option>ОТКЛОНЕНО</option>
    </select>
    <label for="person">Кто согласовал</label>
    <input id="person" class="form-control" style="width: 100%; margin: 4px 0 8px;" value="Иванов И. И.">
    <label for="date">Дата</label>
    <input id="date" class="form-control" style="width: 100%; margin: 4px 0 8px;">
</body>
</html>

code.js

// Пример «Работа с OLE-объектами». Автор: Александр Поляков
(function (window) {
    var WIDTH_MM = 60, HEIGHT_MM = 25;   // размер штампа в документе по умолчанию
    var PX_PER_MM = 8;                   // плотность картинки: 8 пикселей на миллиметр
    var COLORS = { "СОГЛАСОВАНО": "#1e7b34", "НА ДОРАБОТКУ": "#b26a00", "ОТКЛОНЕНО": "#b3261e" };

    function readForm() {
        return {
            status: document.getElementById("status").value,
            person: document.getElementById("person").value,
            date: document.getElementById("date").value
        };
    }

    function fillForm(stamp) {
        document.getElementById("status").value = stamp.status;
        document.getElementById("person").value = stamp.person;
        document.getElementById("date").value = stamp.date;
    }

    // Рисуем штамп на canvas и возвращаем картинку в формате data URL
    function drawStamp(stamp, widthPx, heightPx) {
        var canvas = document.createElement("canvas");
        canvas.width = widthPx;
        canvas.height = heightPx;
        var ctx = canvas.getContext("2d");
        var color = COLORS[stamp.status] || "#1e7b34";
        var pad = Math.round(heightPx * 0.06);
        ctx.fillStyle = "#ffffff";
        ctx.fillRect(0, 0, widthPx, heightPx);
        ctx.strokeStyle = color;
        ctx.lineWidth = Math.max(2, Math.round(heightPx * 0.04));
        ctx.strokeRect(pad, pad, widthPx - 2 * pad, heightPx - 2 * pad);
        ctx.fillStyle = color;
        ctx.textAlign = "center";
        ctx.font = "bold " + Math.round(heightPx * 0.28) + "px Arial";
        ctx.fillText(stamp.status, widthPx / 2, heightPx * 0.42, widthPx - 4 * pad);
        ctx.font = Math.round(heightPx * 0.16) + "px Arial";
        ctx.fillText(stamp.person + "   " + stamp.date, widthPx / 2, heightPx * 0.75, widthPx - 4 * pad);
        return canvas.toDataURL("image/png");
    }

    // Параметры OLE-объекта: данные, картинка и размеры
    function buildOle(stamp, widthMm, heightMm) {
        var widthPx = Math.round(widthMm * PX_PER_MM);
        var heightPx = Math.round(heightMm * PX_PER_MM);
        return {
            data: JSON.stringify(stamp),             // данные штампа хранятся в объекте
            imgSrc: drawStamp(stamp, widthPx, heightPx),
            width: widthMm, height: heightMm,         // размер в документе, мм
            widthPix: widthPx, heightPix: heightPx    // размер картинки, пиксели
        };
    }

    window.Asc.plugin.init = function () {
        var info = this.info;
        var stamp = null;
        // У существующего объекта редактор передает его данные в info.data
        if (info.objectId && info.data) {
            try { stamp = JSON.parse(info.data); } catch (e) { stamp = null; }
        }

        // Пользователь изменил размер объекта: перерисовываем без окна
        if (info.resize === true && stamp) {
            var ole = buildOle(stamp, info.width, info.height);
            ole.objectId = info.objectId;
            this.executeMethod("EditOleObject", [ole], function () {
                window.Asc.plugin.executeCommand("close", "");
            });
            return;
        }

        if (stamp) {
            fillForm(stamp);                        // открыли двойным щелчком: показываем данные
        } else {
            document.getElementById("date").value = new Date().toLocaleDateString("ru-RU");
        }
    };

    window.Asc.plugin.button = function (id) {
        if (id !== 0) {                             // «Отмена» или крестик
            this.executeCommand("close", "");
            return;
        }
        var info = this.info;
        var close = function () { window.Asc.plugin.executeCommand("close", ""); };
        if (info.objectId) {
            // Изменяем существующий штамп, размер оставляем прежним
            var ole = buildOle(readForm(), info.width, info.height);
            ole.objectId = info.objectId;
            this.executeMethod("EditOleObject", [ole], close);
        } else {
            // Вставляем новый штамп. guid связывает объект с плагином
            var newOle = buildOle(readForm(), WIDTH_MM, HEIGHT_MM);
            newOle.guid = info.guid;
            this.executeMethod("AddOleObject", [newOle], close);
        }
    };
})(window);

Плагин открывается модальным окном с двумя кнопками из buttons. В button редактор передает номер кнопки: 0 — «Вставить», 1 — «Отмена», -1 — крестик в заголовке.

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

1. Создайте папку плагина, положите в нее три файла и папку resources с иконками и установите плагин по инструкции Установка и удаление плагина ↗.

2. Откройте документ, поставьте курсор на пустую строку и на вкладке Плагины нажмите Штамп согласования. В окне плагина нажмите Вставить.

3. Дважды щелкните по штампу, смените статус и фамилию и нажмите Вставить.

4. Снова дважды щелкните по штампу: в окне должны быть новые данные. Закройте окно кнопкой Отмена.

5. Выделите штамп и потяните за маркер на правой стороне. После отпускания кнопки мыши штамп перерисуется: рамка станет шире, а текст не растянется.

В Таблицах штамп вставляется от активной ячейки, в Презентациях — в центр слайда. Если штамп не появляется, откройте консоль по инструкции Отладка плагина ↗ и проверьте типы полей в параметре AddOleObject.

Результат

Окно плагина при первом запуске: дата подставлена сегодняшняя.

Окно плагина «Штамп согласования» при первом запуске с полями статуса, имени и даты.

Штамп вставлен в документ размером 60 × 25 мм:

Штамп со статусом «СОГЛАСОВАНО», вставленный в документ.

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

Штамп со статусом «НА ДОРАБОТКУ» после изменения данных.

Повторный двойной щелчок: плагин прочитал данные из объекта:

Окно плагина «Штамп согласования» с данными существующего штампа.

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

Штамп со статусом «НА ДОРАБОТКУ» после увеличения ширины объекта.

Таблицы: штамп вставлен от ячейки C3 и изменен двойным щелчком:

Штамп со статусом «ОТКЛОНЕНО» на листе редактора таблиц.

Презентации: штамп в центре слайда:

Штамп со статусом «СОГЛАСОВАНО» в центре слайда редактора презентаций.

Особенности

  • GUID плагина нельзя менять. При двойном щелчке редактор запускает плагин по GUID, записанному в объекте. Если поменять GUID в новой версии плагина, уже вставленные объекты его не откроют.
  • Размер — в миллиметрах. width и height задают размер объекта в документе, а widthPix и heightPix — размер картинки. Чтобы штамп не расплывался, рисуйте картинку с запасом: в примере — 8 пикселей на миллиметр.
  • Функция обратного вызова не ждет вставки. На проверке callback AddOleObject пришел через 11 мс, когда объекта в документе еще не было: GetAllOleObjects вернул 0 объектов, а через 3 секунды — 1. Закрывать плагин в callback можно: штамп вставляется и после закрытия. Но искать новый объект сразу в callback бесполезно.
  • Режим изменения размера идет без окна. Когда info.resize равно true, пользователь окна плагина не видит. Плагин должен сам перерисовать картинку, вызвать EditOleObject и закрыться.
  • Неверные параметры не дают ошибки. На проверке AddOleObject с объектом в data, со строкой в width и с пустым imgSrc ничего не вставил, а callback пришел как обычно. Если объект не появился, сначала проверьте типы полей.

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

  • QR-код со ссылкой. Подключите библиотеку генерации QR-кодов, рисуйте код на canvas и храните ссылку в data: по двойному щелчку ссылку можно будет изменить.
  • История согласования. Храните в data массив записей и добавляйте новую при каждом изменении статуса. На штампе показывайте последнюю, а в окне плагина — все.

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

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

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