Чтобы эффективно использовать API Документов Google, вы должны понимать архитектуру документа Документов Google и элементы, из которых состоит документ, а также взаимосвязь между ними. На этой странице представлен подробный обзор этих тем:
- Концептуальная модель элементов документа
- Как API Документов представляет эти элементы
- Свойства стиля элементов
Элементы верхнего уровня
Самый внешний элемент-контейнер в Документах Google — это document . Это устройство, которое можно сохранить на Google Диске, поделиться им с другими пользователями и обновить текстом и изображениями.
Элементы верхнего уровня ресурса documents включают его Tab s, SuggestionsViewMode и другие атрибуты:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Вкладки
Один документ может содержать несколько вкладок с разным текстовым содержимым. Свойство tabs документа представляет собой последовательность объектов Tab . Tab состоит из следующих полей:
-
TabProperties: содержит атрибуты вкладки, такие как идентификатор, заголовок и индекс. -
childTabs: отображает дочерние вкладки вкладки (вкладки, вложенные непосредственно под ней). -
DocumentTab: представляет текстовое содержимое вкладки.
В последующих разделах дается краткий обзор иерархии вкладок документа; Представление Tab 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 , который представляет собой место в тексте, которое динамически заменяется содержимым, которое может меняться с течением времени. В Документах это используется для номеров страниц.
Начальный и конечный индексы
Когда вы обновляете содержимое вкладки документа, каждое обновление происходит в определенном месте или в диапазоне внутри документа. Эти местоположения и диапазоны задаются с помощью индексов , которые представляют собой смещение внутри содержащего его сегмента документа. Сегмент – это тело, заголовок, нижний колонтитул или сноска, содержащие элементы структуры или содержимого. Индексы элементов внутри сегмента относятся к началу этого сегмента.
Большинство элементов в содержимом тела имеют свойства startIndex и endIndex отсчитываемые от нуля. Они указывают смещение начала и конца элемента относительно начала охватывающего его сегмента. Дополнительные сведения о том, как упорядочить пакетные вызовы API Документов, см. в разделе Пакетные обновления .
Индексы измеряются в кодовых единицах 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 . И наоборот, любые функции форматирования, которые вы не установили, продолжают наследовать стиль абзаца.