Структура документа Google Docs

В этом руководстве описывается внутренняя структура документа 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, чтобы извлечь эти значения.