使用列表

Google 文档 API 支持在新文档中创建列表、将现有纯文本段落转换为项目符号列表，以及从段落中移除项目符号。

在新文档中创建编号列表

Docs API 支持通过插入文本，然后在单个批处理请求中将列表样式应用于文本，从而在新文档中创建编号列表。

如需在新文档中创建编号列表，请执行以下操作：

  1. 使用 documents.create 方法创建文档。

  2. 使用 documents.batchUpdate 方法并提供 InsertTextRequest 以向文档添加内容。使用换行符 (\n) 分隔列表项。

  3. 在同一批次更新中，添加 CreateParagraphBulletsRequest、用于指定文本范围的 Range 和用于设置编号格式的 BulletGlyphPreset。

以下代码示例展示了如何创建文档，然后插入三个项目作为编号列表。BulletGlyphPreset 使用 NUMBERED_DECIMAL_ALPHA_ROMAN 设置列表格式。这意味着，编号列表的前三个嵌套级别分别用十进制数字、小写字母和小写罗马数字表示。

Java

Document doc = new Document().setTitle("New List Document");
doc = docsService.documents().create(doc).execute();
String documentId = doc.getDocumentId();

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item 1\nItem 2\nItem 3\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(22)
                        .setTabId(TAB_ID))
                .setBulletPreset("NUMBERED_DECIMAL_ALPHA_ROMAN")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
docsService.documents().batchUpdate(documentId, body).execute();

System.out.println("Created document with ID: " + documentId);

Python

title = 'New List Document'
body = {'title': title}
doc = service.documents().create(body=body).execute()
document_id = doc.get('documentId')

requests = [
    {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item 1\nItem 2\nItem 3\n'
        }
    },
    {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex': 22,
                'tabId': TAB_ID
            },
            'bulletPreset': 'NUMBERED_DECIMAL_ALPHA_ROMAN'
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_id, body={'requests': requests}).execute()

print(f"Created document with ID: {document_id}")

将 TAB_ID 替换为包含列表内容的标签页的 ID。

将段落转换为列表

一种常见的段落格式设置操作是将现有段落转换为项目符号列表。

如需创建列表，请使用 documents.batchUpdate 方法并提供 CreateParagraphBulletsRequest。包含 Range 以指定受影响的文本，并包含 BulletGlyphPreset 以设置项目符号的样式。

与指定范围重叠的所有段落都会添加项目符号。如果指定范围与某个表格重叠，则项目符号会应用于表格单元格内。每个段落的嵌套级别是通过统计每个段落前面的前导制表符来确定的。

您无法调整现有项目符号的嵌套级别。您必须删除项目符号，在段落前面设置前导制表符，然后重新创建项目符号。如需了解详情，请参阅从列表中移除项目符号。

您还可以使用 CreateParagraphBulletsRequest 更改现有列表的项目符号样式。

以下代码示例展示了一个批处理请求，该请求首先在文档开头插入文本，然后从前 50 个字符所跨越的段落中创建一个列表。BulletGlyphPreset 使用 BULLET_ARROW_DIAMOND_DISC，这意味着项目符号列表的前三个嵌套级别分别用箭头、菱形和圆盘表示。

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item One\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))
                .setBulletPreset("BULLET_ARROW_DIAMOND_DISC")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item One\n',
        }}, {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
            'bulletPreset': 'BULLET_ARROW_DIAMOND_DISC',
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

将 TAB_ID 替换为包含列表内容的标签页的 ID，或者省略此参数以默认使用文档中的第一个标签页。

将段落转换为列表。
图 1. 将段落转换为列表。

从列表中移除项目符号

如需从段落列表中移除项目符号，请使用 documents.batchUpdate 方法并提供 DeleteParagraphBulletsRequest。添加 Range 以指定受影响的文本。

该方法会删除与指定范围重叠的所有项目符号，无论嵌套级别如何。为了直观地保留嵌套级别，系统会在每个相应段落的开头添加缩进。

以下代码示例展示了一个批量请求，用于从段落列表中删除项目符号。

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setDeleteParagraphBullets(
        new DeleteParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'deleteParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

将 TAB_ID 替换为包含列表内容的标签页的 ID，或者省略此参数以默认使用文档中的第一个标签页。