Рецепты интеграции
Реакция на щелчок и двойной щелчок, контекстное меню для ячейки таблицы, выполнение внешней команды и полный сценарий транспортной системы от события до DOCX.
Примеры: щелчок, двойной щелчок и меню
Заголовок раздела «Примеры: щелчок, двойной щелчок и меню»Как отвечать на щелчок и двойной щелчок
Заголовок раздела «Как отвечать на щелчок и двойной щелчок»editor.interactions.on("elementActivated", async (event) => { const { gesture, target } = event;
if (gesture === "click" && target.kind === "comment") { hostSidebar.openComment(target.nodeId); }
if (gesture === "doubleClick" && target.hostData?.type === "shipment") { await hostApp.openShipment(target.hostData.id); }});Контекстное меню для ячейки таблицы
Заголовок раздела «Контекстное меню для ячейки таблицы»editor.contextMenu.registerProvider("transport-suite", async (ctx) => { if (ctx.target.kind !== "tableCell") return [];
return [ { id: "transport.openCargo", label: "Открыть карточку груза", enabled: Boolean(ctx.target.hostData?.id) }, { id: "transport.bindRoute", label: "Привязать к маршруту", enabled: !ctx.readOnly }, { type: "separator" }, { id: "a4.table.insertRowBelow", label: "Вставить строку ниже", command: { type: "insert_table_row", position: "below" } } ];});Выполнение внешней команды
Заголовок раздела «Выполнение внешней команды»editor.commands.register("transport.bindRoute", async (ctx) => { const route = await hostUi.chooseRoute(); if (!route) return;
return ctx.session.execute({ operationId: crypto.randomUUID(), expectedRevision: ctx.revision, target: ctx.target, command: { type: "replace_target_text", text: route.displayName } });});Сценарий транспортной системы от события до DOCX
Заголовок раздела «Сценарий транспортной системы от события до DOCX»Разбор по шагам: щелчок правой кнопкой по строке груза
Заголовок раздела «Разбор по шагам: щелчок правой кнопкой по строке груза»-
Пользователь щёлкает правой кнопкой. Поверхность переводит координаты щелчка в координаты страницы документа и спрашивает ядро, во что попали.
-
Ядро отвечает, что под указателем. Например ячейка таблицы: её устойчивый идентификатор, номера строки и столбца, объемлющие элементы и номер ревизии, в которой всё это верно.
-
Редактор спрашивает ваши поставщики пунктов меню, передавая им этот контекст — и только его, а не ссылку на элемент разметки.
-
Ваш поставщик добавляет свои действия. «Открыть карточку груза» и «Привязать к маршруту» встают рядом с разрешёнными встроенными пунктами.
-
Пользователь выбирает маршрут. Ваш интерфейс возвращает его идентификатор; команда на изменение документа собирается отдельно — выбор в вашей системе и правка в документе остаются разными действиями.
-
Ядро принимает команду или отклоняет её. Ожидаемая ревизия и перечень допустимых действий не дают применить правку к устаревшему документу или к объекту, для которого она не предусмотрена.
-
Поверхность обновляется. События
contentChangedиcommandStateChangedприносят новый номер ревизии, и перерисовываются только затронутые страницы, а не весь документ. -
Сохранение и повторное открытие подтверждают результат. Документ сохраняется отдельным файлом либо публикуется разом, а затем читается заново — так проверяется, что на диск легло именно то, что видел пользователь.
Как выглядит переданный контекст
Заголовок раздела «Как выглядит переданный контекст»{ "schema": "a4.interaction-context.v1", "gesture": "contextMenu", "revision": 42, "readOnly": false, "target": { "kind": "tableCell", "nodeId": "body.block[18].row[2].cell[1]", "ancestors": [{"kind":"table","nodeId":"body.block[18]"}], "capabilities": ["read","editText","insertRow"], "hostData": {"type":"shipment","id":"SHP-009173"} }, "hit": {"pageIndex":3,"xMilliPx":412000,"yMilliPx":286000}}Что приходит при устаревшей ревизии
Заголовок раздела «Что приходит при устаревшей ревизии»{ "ok": false, "error": { "code": "revision_conflict", "expectedRevision": 42, "actualRevision": 43, "retry": "refresh_target_and_command_state" }}