Translated by @Zhang Chi, updated at 2020-02-16

Developers.google.com/docs/api/co…

The structure of Google Docs

This guide explains the internal structure of a Google Docs document: the elements that make up the document and the relationships between those elements.

Top-level element

The top-level elements of a document include the body and many other attributes of the document as a whole:

document: { body: ... // documentStyle:... // Lists:... // List documentId:... // file ID namedStyles:... // revisionId:... // Update version ID ID:... / / title}Copy the code

To use global document features beyond body content, it is almost always best to use one or more document templates as an encoding basis for generating new documents.

Document Body Content

Most of the things you can or may want to use programmatically are elements in the body content:

​

Structural elements

The body content is essentially just a series of structural element objects. Each StructuralElement object is personalized by its content element, as shown below:

​

The structure element and its content object contain all the text of the document, embedded images, and so on.

Content elements of the header, footer, and footer types similarly contain a series of structural elements.

Paragraphs contain a special element type called ParagraphElement, which works similar to StructuralElement: Personalized through its own set of content element types, as shown below:

​

For an example of the complete document structure, see sample document dump(result file or dump). In this dump, you can see a number of key structure and content elements, as well as the use of the start and end indexes described in the next section.

Start and end indexes

Most elements in the body content have startIndex and endIndex attributes. These values represent offsets from the starting and ending points of an element relative to the starting point of the enclosing segment.

A segment is the body, header, footer, or footnote that contains structural or content elements. The index of an element in a segment is relative to the beginning of the segment.

Indexes are measured in UTF-16 code units. This means that Surrogate Pairs consume two indexes. For example, “GRINNING FACE” 😄, the emoji will be represented as “\ uD83D \ uDE00” and consume two indexes.

Surrogate Pair is a quadruple byte (two UTF-16 encodings) encoding used to extend a character in UTF-16.

For elements in the document body, these indexes represent the offset from the beginning of the body content (that is, the “root” element).

Elements not contained in content do not have the following index attributes: they are global in scope and do not have the concept of location.

The “personalization” types of structural elements (Paragraph, Table, TableOfContents, and SectionBreak) do not have these indexes because the StructuralElement surrounding them has these fields. The same goes for the individual types included in ParagraphElement.

Paragraph structure

A paragraph consists of the following elements:

• Elements – a sequence containing one or more textRun instances
• ParagraphStyle – paragraphStyle, an optional element that explicitly sets the style attributes for the paragraph.
• Bullet – If the paragraph is part of the list, an optional element of the bullet specification is provided.

Text runs

A text line represents all contiguous text strings with the same text style. A paragraph can contain multiple lines of text; Lines of text cannot cross paragraph boundaries. For example, consider a small document like this:

​

The following figure shows how to visualize the sequence of paragraphs in the above document, each with its own text run and optional bullet setting.

The basic function of Accessing elements is Accessing elements

Many elements can be modified using the BatchUpdate method. For example, with the InsertTextRequest request type, you can modify the content of any element that contains text. Again, you can use UpdateTextStyleRequest to apply the format to a set of text contained in one or more elements.

To read the elements of a document, use the GET method to get a JSON dump of the full document. (To see a simple way to do this, see Using the output document as a JSON example.) You can then look up the values of individual elements through the parsing JSON results.

Parsing content is useful for a variety of use cases. For example, a document classification application that lists the documents it finds. An application like this might want to extract the title, revision ID, and start page number of the document, as shown below:

​

Because there is no way to explicitly read these Settings, the application needs to get the entire document and then parse the JSON to extract the values.