Контракт взаимодействия для пилота

Устойчивая ссылка на место в документе, минимальный набор методов и события, которые фиксируются до начала интеграции.

Семантическая цель

Чтобы ваше приложение могло сказать «что сделать» вместо «куда щёлкнуть», нужна общая единица адресации: устойчивая ссылка на место в документе. DocumentTarget описывает именно её — вид элемента, его идентификатор и ревизию, в которой этот идентификатор действителен. Ссылок на DOM-узлы и координаты в этом контракте нет намеренно: они меняются при перерисовке.

export interface DocumentTarget {
  kind: "paragraph" | "run" | "table" | "tableCell" |
        "image" | "comment" | "field" | "header" | "footer" |
        "hostObject";
  nodeId: string;          // стабильный ID в пределах revision
  revision: number;
  ancestors: Array<{ kind: string; nodeId: string }>;
  capabilities: string[]; // read, editText, insertRow, openProperties...
  hostData?: { type: string; id: string };
}

Минимальный набор методов сеанса

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

interface A4DocumentSession {
  getDocumentSnapshot(options?: { depth: "semantic" }): Promise<Model>;
  getProjection(request: ProjectionRequest): Promise<Projection>;
  hitTest(point: PagePoint): Promise<HitResult>;
  getSelection(): Promise<SelectionSnapshot>;
  getCommandState(target: DocumentTarget): Promise<CommandState>;
  execute(request: ExecuteRequest): Promise<CommandReceipt>;
  executeBatch(request: AtomicBatchRequest): Promise<BatchReceipt>;
  save(request: SaveRequest): Promise<SaveReceipt>;
}

События

Событие	Когда приходит	Обязательные поля
`selectionChanged`	Изменилось выделение или положение курсора	выделение, ревизия, источник изменения
`elementActivated`	Щелчок, двойной щелчок или активация с клавиатуры	вид жеста, объект, точка попадания, выделение
`contextMenuRequested`	Перед показом контекстного меню	идентификатор запроса, объект, точка, встроенные пункты
`contentChanged`	Команда изменила документ	новая ревизия, подтверждение, какие узлы изменились
`commandStateChanged`	Команда стала доступна или недоступна, изменилась её отметка	объект, новые состояния
dirtyChanged, saved, error	Изменения, сохранение и ошибки	ревизия, путь к файлу или описание ошибки

Дальше

Как поверхность встраивается в ваше окно — Встраивание Surface.
Что приходит в событиях — Host API.