Занятие 5:
Работа с объектной моделью документов Р7
Работа с объектной моделью документов Р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 задумывался как мультиплатформенный офисный пакет. В основе его работы с документами лежит фреймворк 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
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
Текущие свойства гиперссылки:
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
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 документов.