使用清單

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，或省略這個 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，或省略這個 ID，預設為文件中的第一個分頁。