В этом руководстве описывается внутренняя структура документа Google Docs: элементы, составляющие документ, и связи между ними.
Элементы верхнего уровня
Элементы документа верхнего уровня включают тело и несколько других атрибутов документа в целом:
document: { body: ... , documentStyle: ... , lists: ... , documentId: ... , namedStyles: ... , revisionId: ... , title: ... }
Чтобы манипулировать глобальными функциями документа за пределами основного содержимого, почти всегда лучше использовать один или несколько шаблонов документов, которые можно использовать в качестве основы для программного создания новых документов.
Содержимое тела
Большинство элементов, которые вы можете или, вероятно, захотите использовать программно, являются элементами содержимого тела:
Конструктивные элементы
Содержимое тела представляет собой просто последовательность объектов StructuralElement
. Элемент содержимого персонализирует каждый объект StructuralElement
, как показано на следующей схеме:
Структурные элементы и их объекты содержимого содержат весь текст документа, встроенные изображения и т. д.
Абзацы содержат особый тип элемента, называемый ParagraphElement
, который работает как StructuralElement
. Набор типов элементов контента персонализирует свой собственный ParagraphElement
, как показано на следующей схеме:
Пример полной структуры документа см. в образце дампа документа в формате JSON. В выводе вы можете увидеть множество ключевых структурных и содержательных элементов, а также использование начальных и конечных индексов, как описано в следующем разделе.
Начальный и конечный индекс
Большинство элементов в теле содержимого имеют свойства startIndex
и endIndex
. Они указывают смещение начала и конца элемента относительно начала охватывающего его сегмента.
Индексы измеряются в кодовых единицах UTF-16. Это означает, что суррогатные пары используют 2 индекса. Например, смайлик «УХАЛЯЮЩЕЕ ЛИЦО», 😄, будет представлен как «\uD83D\uDE00» и будет занимать 2 индекса.
Для элементов внутри тела документа индексы представляют собой смещения от начала содержимого тела, которое является «корневым» элементом.
«Персонализирующие» типы структурных элементов — SectionBreak
, TableOfContents
, Table
и Paragraph
— не имеют этих индексов, поскольку их включающий StructuralElement
имеет эти поля. Это также верно для типов персонализации, содержащихся в ParagraphElement
.
Структура абзаца
Абзац состоит из следующего:
-
elements
— Последовательность, содержащая один или несколько экземпляровtextRun
. -
paragraphStyle
— Необязательный элемент, который явно задает свойства стиля для абзаца. -
bullet
— Необязательный элемент, предоставляющий спецификацию маркера, если абзац является частью списка.
Текст работает
textRun
представляет собой непрерывную строку текста с одинаковым стилем текста. Абзац может содержать несколько фрагментов текста, но фрагменты текста не могут пересекать границы абзаца. Рассмотрим, например, небольшой документ, подобный следующему:
На следующей диаграмме показано, как можно визуализировать последовательность абзацев в приведенном выше документе, каждый из которых имеет свои собственные текстовые фрагменты и дополнительные настройки маркеров.
Элементы доступа
Многие элементы можно изменить с помощью метода BatchUpdate
. Например, используя тип запроса InsertTextRequest
, вы можете изменить содержимое любого элемента, содержащего текст. Аналогичным образом вы можете использовать UpdateTextStyleRequest
, чтобы применить форматирование к диапазону текста, содержащемуся в одном или нескольких элементах.
Чтобы прочитать элементы документа, используйте метод get
для получения дампа JSON всего документа. (Способ сделать это см. в примере содержимого выходного документа в формате JSON .) Затем вы можете проанализировать полученный JSON, чтобы найти значения отдельных элементов.
Анализ содержимого может быть полезен в различных случаях использования. Рассмотрим, например, приложение для каталогизации документов, в котором перечислены найденные им документы. Этому приложению может потребоваться извлечь заголовок, идентификатор редакции и номер начальной страницы документа, как показано на следующей схеме:
Поскольку методов для явного чтения этих параметров не существует, вашему приложению необходимо получить весь документ, а затем проанализировать JSON, чтобы извлечь эти значения.