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