Попадание по координате, выделение и правка документа

Координата → позиция документа

Единицы координат

Команда hit-test-docx принимает --x и --y в тысячных долях пикселя. Значение 100000 в примере ниже — это 100 px, а не сто тысяч.

# $CLI — путь к процессору, см. «Установка и проверка»
"$CLI" hit-test-docx /data/contract.docx \
  --x 100000 --y 100000 --format json

{
  "model_version": "fastdoc-d6-hit-test-snapshot-v2",
  "hit_test_mode": "body-line-boxes-line-edge-caret-only",
  "result_kind": "body-line-hit",
  "page_index": 0,
  "paragraph_index": 0,
  "paragraph_location": "word/document.xml:body.block[0]",
  "line_index": 0,
  "caret_slot_index": 1,
  "line_scene_x_milli_px": 96000,
  "line_scene_y_milli_px": 96000
}

Что этот вызов умеет и чего не умеет

Команда отвечает по строкам основного текста и возвращает позицию курсора в строке — это и означает body-line-boxes-line-edge-caret-only в поле hit_test_mode. Таблицы, врезки и графические объекты она не различает: щелчок по ячейке таблицы даст позицию в строке, а не саму ячейку.

В постоянном сеансе команды попадания нет вовсе — этот вызов отдельный, разовый, и открытого сеанса не требует.

Настольное приложение умеет больше: попадание в текст и в ячейку таблицы. Наружу эти режимы пока не выведены — прежде чем открывать их, нужно определить, какие виды объектов вправе трогать встроившее приложение.

Простая точечная правка и сохранение

Команда mutate адресуется номером абзаца и смещением в нём — отсюда «точечная»: правка кладётся ровно в названное место и дальше него не выходит. Она ничего не проверяет: если между чтением и правкой документ изменился, правка ляжет по старым координатам. Годится для сценариев, где сеанс один и между чтением и записью ничего не происходит.

{"id":"edit-1","cmd":"mutate",
 "operation_kind":"insert-text","paragraph_index":0,
 "offset":7,"text":"A4 "}
{"id":"save-1","cmd":"save","path":"/data/contract-edited.docx"}

Предпочтительная типизированная транзакция

Команда apply-text-transaction несёт идентификаторы запроса, документа, сеанса и вида, а вместе с ними ожидаемые ревизии документа и выделения. Ядро сверяет их до изменения: если документ или выделение ушли вперёд, запрос отклоняется целиком, а не применяется наполовину. Поэтому для интеграции предпочтителен этот путь — см. Типы типизированной правки.

{
  "id": "tx-1", "cmd": "apply-text-transaction",
  "request": {
    "request_id": "req-8", "document_id": "contract-42",
    "session_id": "session-1", "view_id": "canvas-1",
    "expected_revision": 42, "expected_selection_revision": 17,
    "command": {"type":"insert_text",
      "at":{"story_id":"body",
            "node_id":"paragraph:body.block[0]",
            "utf16_offset":7,"affinity":"downstream"},
      "text":"A4 "}
  }
}