Что такое OLE-объект плагина
OLE-объект — это картинка в документе, за которой скрыты данные плагина. В объекте хранятся три вещи:
- картинка, которую видит пользователь;
- строка данных, из которой эта картинка нарисована;
- GUID плагина, который создал объект.
Когда пользователь дважды щелкает по объекту, редактор запускает плагин с этим GUID и передает ему сохраненные данные. Плагин показывает их в своем окне, пользователь их меняет, и плагин перерисовывает картинку.
Так делают объекты, которые нужно изменять после вставки: штампы, схемы, графики, QR-коды, формулы. Обычную картинку пришлось бы удалять и вставлять заново.
OLE-объекты плагина работают в Документах, Таблицах и Презентациях.
Как это устроено
Настройки в config.json
| Поле | Значение для OLE |
|---|---|
initDataType | "ole": плагин работает с OLE-объектами. |
isUpdateOleOnResize | true: когда пользователь меняет размер объекта, редактор запускает плагин без окна, чтобы тот перерисовал картинку под новый размер. С false картинка просто растягивается. |
Остальные поля — как у обычного плагина с окном, см. config.json ↗.
Данные объекта в info
Когда плагин открыт двойным щелчком по объекту или запущен после изменения размера, в объекте info ↗ есть поля:
| Поле | Что в нем |
|---|---|
objectId | Идентификатор объекта. Нужен для EditOleObject. Если плагин запущен с вкладки Плагины, поля нет. |
data | Строка данных, сохраненная в объекте. |
width, height | Размер объекта в документе, мм. |
widthPix, heightPix | Размер картинки в пикселях. |
resize | true, если плагин запущен без окна после изменения размера. В 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массив записей и добавляйте новую при каждом изменении статуса. На штампе показывайте последнюю, а в окне плагина — все.













