使用清單

Google Docs API 支援將純文字段落轉換成項目符號清單，以及移除段落中的項目符號。

將段落轉換為清單

常見的段落格式設定作業是將段落轉換成項目符號清單。

如要建立清單，請使用 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))));

      requests.add(new Request().setCreateParagraphBullets(
              new CreateParagraphBulletsRequest()
                      .setRange(new Range()
                              .setStartIndex(1)
                              .setEndIndex(50))
                      .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
                },
                'text': 'Item One\n',
            }}, {
            'createParagraphBullets': {
                'range': {
                    'startIndex': 1,
                    'endIndex':  50
                },
                'bulletPreset': 'BULLET_ARROW_DIAMOND_DISC',
            }
        }
    ]

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

圖 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))));

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

Python

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

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