Для эффективного использования API Google Docs необходимо понимать архитектуру документа Google Docs, его элементы и взаимосвязи между ними. На этой странице представлен подробный обзор следующих тем:
- Концептуальная модель элементов документа
- Как API Docs представляет эти элементы
- Стилевые свойства элементов
Элементы верхнего уровня
Самый внешний элемент-контейнер в Google Docs — это документ . Это единица, которую можно сохранить на Google Диске, поделиться ею с другими пользователями и обновить текстом и изображениями.
Элементы верхнего уровня ресурса documents включают его Tab , SuggestionsViewMode и другие атрибуты:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Вкладки
Один документ может содержать несколько вкладок с различным текстовым содержимым. Свойство tabs документа представляет собой последовательность объектов Tab . Tab состоит из следующих полей:
-
TabProperties: содержит атрибуты вкладки, такие как идентификатор, заголовок и индекс. -
childTabs: отображает дочерние вкладки вкладки (вкладки, которые вложены непосредственно под ней). -
DocumentTab: представляет текстовое содержимое вкладки.
В последующих разделах представлен краткий обзор иерархии вкладок документа; представление вкладок в формате JSON также содержит более подробную информацию. Подробнее о функции вкладок см. в разделе «Работа с вкладками ».
Для управления глобальными функциями вкладок документов за пределами содержимого Body практически всегда лучше использовать один или несколько шаблонов документов, которые можно использовать в качестве основы для программного создания новых документов. Подробнее см. в разделе Объединение текста в документ .
Содержание тела
Body обычно содержит всё содержимое вкладки документа. Большинство элементов, которые вы можете или, вероятно, захотите использовать программно, находятся внутри содержимого Body :
Структурный элемент
Элемент StructuralElement описывает содержимое, обеспечивающее структуру документа. Содержимое Body представляет собой последовательность объектов StructuralElement . Элемент содержимого персонализирует каждый объект StructuralElement , как показано на следующей диаграмме:
Структурные элементы и их объекты контента содержат все визуальные компоненты документа. Это включает текст, встроенные изображения и форматирование.
Структура абзаца
Paragraph — это StructuralElement представляющий абзац. Он содержит фрагмент содержимого, завершающийся символом новой строки. Он состоит из следующих объектов:
-
ParagraphElement: описывает содержимое абзаца. -
ParagraphStyle: необязательный элемент, который явно задает свойства стиля для абзаца. -
Bullet: если абзац является частью списка, необязательный элемент, задающий спецификацию маркера.
ParagraphElement работает примерно как StructuralElement . Набор типов элементов контента (таких как ColumnBreak и Equation ) персонализирует свой собственный ParagraphElement , как показано на следующей диаграмме:
Пример полной структуры документа представлен в формате JSON. В выводе вы можете увидеть множество ключевых структурных и контентных элементов, а также использование начальных и конечных индексов, как описано в следующем разделе.
Текстовые отрезки
TextRun — это элемент ParagraphElement , представляющий собой непрерывную строку текста с одинаковым стилем. Абзац может содержать несколько текстовых фрагментов, но они никогда не выходят за границы абзаца. Содержимое разделяется после символа новой строки, образуя отдельные текстовые фрагменты. Например, рассмотрим небольшой документ, подобный следующему:
На следующей диаграмме показано, как можно визуализировать последовательность абзацев в предыдущем документе, каждый со своим собственным TextRun и дополнительными настройками Bullet .
Автотекст
AutoText — это элемент ParagraphElement , представляющий собой фрагмент текста, динамически заменяемый содержимым, которое может меняться со временем. В Docs он используется для нумерации страниц.
Начальный и конечный индексы
При обновлении содержимого вкладки документа каждое обновление происходит в определённом месте или диапазоне внутри документа. Эти места и диапазоны указываются с помощью индексов , которые представляют собой смещение внутри содержащего сегмента документа. Сегмент — это тело, верхний колонтитул, нижний колонтитул или сноска, содержащие структурные или контентные элементы. Индексы элементов внутри сегмента отсчитываются относительно начала этого сегмента.
Большинство элементов в теле документа имеют свойства startIndex и endIndex , отсчитываемые от нуля. Они указывают смещение начала и конца элемента относительно начала его объемлющего сегмента. Подробнее о порядке пакетных вызовов API Docs см. в разделе Пакетные обновления .
Индексы измеряются в кодовых единицах UTF-16. Это означает, что суррогатные пары используют два индекса. Например, эмодзи «УХМЕЛКАЮЩЕЕ ЛИЦО» 😄 представлено как \uD83D\uDE00 и использует два индекса.
Для элементов внутри тела документа индексы представляют собой смещения от начала содержимого тела, которое является «корневым» элементом.
Типы персонализации для структурных элементов — SectionBreak , TableOfContents , Table и Paragraph — не имеют таких индексов, поскольку эти поля есть у их вмещающего StructuralElement . Это также справедливо для типов персонализации, содержащихся в ParagraphElement , таких как TextRun , AutoText и PageBreak .
Элементы доступа
Многие элементы можно изменять с помощью метода documents.batchUpdate . Например, с помощью InsertTextRequest можно изменить содержимое любого элемента, содержащего текст. Аналогично, с помощью UpdateTextStyleRequest можно применить форматирование к диапазону текста, содержащемуся в одном или нескольких элементах.
Чтобы прочитать элементы документа, используйте метод documents.get для получения JSON-дампа всего документа. Затем вы можете проанализировать полученный JSON-дамп и найти значения отдельных элементов. Подробнее см. в разделе Вывод содержимого документа в формате JSON .
Анализ содержимого может быть полезен в различных сценариях использования. Рассмотрим, например, приложение для каталогизации документов, перечисляющее найденные документы. Это приложение может извлекать название, идентификатор версии и номер начальной страницы вкладок документа, как показано на следующей схеме:
Поскольку методов явного считывания этих настроек не существует, вашему приложению необходимо получить весь документ, а затем проанализировать JSON для извлечения этих значений.
Наследование имущества
Элемент StructuralElement может наследовать свойства своих родительских объектов. Свойства объекта, включая те, которые он определяет, и те, которые он наследует, определяют его конечный внешний вид.
Форматирование текстовых символов определяет, как текст будет отображаться в документе, например, полужирным, курсивом или подчёркнутым. Применяемое форматирование переопределяет форматирование по умолчанию, унаследованное от TextStyle базового абзаца. И наоборот, любые символы, форматирование которых не задано, продолжают наследовать стили абзаца.
Форматирование абзаца определяет, как блоки текста отображаются в документе, например, выравнивание, границы и отступы. Применяемое форматирование переопределяет форматирование по умолчанию, унаследованное от базового ParagraphStyle . И наоборот, любые неустановленные вами параметры форматирования продолжают наследоваться от стиля абзаца.