Занятие 5:
Работа с объектной моделью документов Р7
На занятии описаны:
    Объектная модель документов
    Объектная модель документов в редакторах Р7 во многом старается следовать объектной модели соответствующего типа для MS Office ранних его версий. При этом есть существенные отличия, которые для ряда задач, обычных для MS Office, делают их решение невозможным в Р7. Это прежде всего внешнее управление (автоматизация) через средства ОС Windows (используя технологии ActiveX и COM+). Такое ограничение делает затруднительным интеграцию через API в системы электронного документооборота (СЭД).

    Причина этих ограничений заключается в том, что изначально Р7 задумывался как мультиплатформенный офисный пакет. В основе его работы с документами лежит фреймворк Qt, однако редактор представляет собой веб-приложение, функционирующее на базе веб-браузера Chromium. Взаимодействие пользователя — это локальная навигация по панелям статичной страницы, и лишь небольшая часть области самого документа в редакторе через связку WebAsm обрабатывается бинарным ядром. Ограничения, накладываемые на браузеры, работающие с JavaScript, влияют на работу с локальной файловой системой компьютера (или смартфона).

    API для работы с документами в Р7 также ограничено по возможностям по сравнению с MS Office. Возможности редактора Р7 в основным соответствуют версии 6.0 MS Office.
    Основные отличия Р7 от MS Office
    Класс App vs. Application: В отличие от MS Office, вершиной API в Р7 является не класс Application (приложение), а класс App. Он вроде бы и должен ему соответствовать, но на деле скорее соответствует классу Document, так как не подразумевает большинство функций управления именно приложением редактора. Однако часть функций схожа и позволяет получить доступ к массиву загруженных документов, управлять записью и чтением документов, их экспортом или импортом и т.п.
    Рассмотрим в общем виде модели API документов для текстового и табличного редакторов (примеры и ссылки взяты с сайта опенсорсного решения OnlyOffice).
    Модель документа для текстового редактора
    Создание документа и элементов документа:
    Api
    Document
    Основные свойства документа, глобальные настройки цвета и заливки/обводки, стили, используемые во всем документе:
    ApiDocumentContent, ApiDocument, ApiStyle, ApiFill, ApiStroke, ApiGradientStop, ApiUniColor, ApiPresetColor, ApiRGBColor, ApiSchemeColor
    Section
    Свойства раздела документа:
    ApiSection
    Paragraph
    Общие свойства абзаца, общие свойства текста, свойства текущего абзаца, нумерация абзацев:
    ApiParaPr, ApiTextPr, ApiParagraph, ApiNumbering, ApiNumberingLevel
    Text run
    Общие свойства текста, текущие свойства прогона текста:
    ApiTextPr, ApiRun
    Image
    Общие свойства объекта, текущие свойства изображения:
    ApiDrawing, ApiImage

    Chart
    Общие свойства объекта, текущие свойства диаграммы:
    ApiDrawing, ApiChart

    Shape
    Общие свойства объекта, текущие свойства формы:
    ApiDrawing, ApiShape.
    Если внутри фигуры предусмотрено место для текста, в нее можно вставить всю структуру абзаца.

    Inline text content control
    Общие свойства текста, текущие свойства элемента управления встроенным текстовым содержимым:
    ApiTextPr, ApiInlineLvlSdt
    Text run
    Встроенный контроль текстового содержимого
    Hyperlink
    Текущие свойства гиперссылки:
    ApiHyperlink
    Table
    Общие стили таблиц, общие свойства таблиц, текущие свойства таблиц:
    ApiTableStylePr, ApiTablePr, ApiTable
    Table row
    Общие свойства строки таблицы, свойства текущей строки таблицы:
    ApiTableRowPr, ApiTableRow
    Table cell
    Общие свойства ячеек таблицы, свойства текущей строки таблицы:
    ApiTableCellPr, ApiTableCell
    Paragraph
    Table
    Block content control

    Table cell
    Общие свойства ячеек таблицы, свойства текущей строки таблицы:
    ApiTableCellPr, ApiTableCell
    Paragraph
    Table
    Block content control
    Общие свойства текста, свойства управления содержимым текущего блока:
    ApiTextPr, ApiBlockLvlSdt
    Paragraph

    Table

    Block content control
    Range
    Общие свойства текста, свойства текущего диапазона:
    ApiTextPr, ApiRange
    Paragraph


    Block content control
    Модель документа для табличного редактора
    Создание таблицы и элементов таблицы:
    Создание таблицы, глобальные настройки цвета и заливки/обводки:
    Api, ApiFill, ApiBullet, ApiStroke, ApiGradientStop, ApiUniColor, ApiPresetColor, ApiRGBColor, ApiSchemeColor, ApiName
    Worksheet
    Имя листа, формат ячейки в виде таблицы, ширина столбца, диаграммы:
    ApiWorksheet
    Range
    Свойства текста ячейки, формат текста ячейки (цвет, семейство шрифтов, размер, выравнивание), текстовое значение ячейки.:
    ApiRange
    Areas
    Свойства текущих областей:
    ApiAreas
    Comment
    Текущие свойства комментариев:
    ApiComment
    Image
    Общие свойства объекта, текущие свойства изображения:
    ApiDrawing, ApiImage

    Chart
    Общие свойства объекта, текущие свойства диаграммы:
    ApiDrawing, ApiChart
    Shape
    Общие свойства объекта, текущие свойства формы:
    ApiDrawing, ApiShape.
    Paragraph
    Общие свойства абзаца, текущие свойства абзаца, нумерация абзацев.:
    ApiParaPr, ApiParagraph
    Text run
    Общие свойства текста, текущие свойства выполнения текста:
    ApiTextPr, ApiRun

    Как работать с объектной моделью документов Р7
    Данные, приведенные выше, необходимы для понимания структуры и иерархии классов API. Например, если нам требуется создать или изменить что-то на уровне параграфа в текстовом документе, то цепочка доступа может быть такой:
    
    // В документе
    
    var oDocument = Api.GetDocument();
    var oFParagraph = oDocument.GetElement(0);
    oFParagraph.AddText("First paragraph");
    
    //Аналогично, для ячейки в таблице:
    
    var oWorksheet = Api.GetActiveSheet();
    var oRange = oWorksheet.GetRange("A1:C3");
    var oCell = oRange.GetCells(2, 1);
    oCell.SetFillColor(Api.CreateColorFromRGB(255, 213, 191));
    
    По ссылкам выше вы можете перейти на страницы с описанием самих классов и их методов. В каждом методе обычно приводится пример, который в режиме онлайн тут же исполняется в специальном окне с онлайн-версией редактора OnlyOffice (аналог Р7):
    Дополнительные материалы
    Для понимания работы АПИ документов рекомендуем ознакомится с разделом примеров написания макросов. Примеры необходимы, чтобы сформировать общее представление о механизмах работы API.
    Самостоятельное написание макросов является отличным способом понять, как устроен документ и как с ним можно взаимодействовать через API документов.