リストを操作する

Google Docs API では、新しいドキュメントでのリストの作成、既存のプレーンな段落を箇条書きリストに変換、段落からの箇条書きの削除がサポートされています。

新しいドキュメントで番号付きリストを作成する

Docs API は、テキストを挿入してから、単一のバッチ リクエストでテキストにリストスタイルを適用することで、新しいドキュメントに番号付きリストを作成することをサポートしています。

新しいドキュメントで番号付きリストを作成するには:

  1. documents.create メソッドを使用してドキュメントを作成します。

  2. documents.batchUpdate メソッドを使用して InsertTextRequest を指定し、ドキュメントにコンテンツを追加します。リスト項目を区切るには、改行文字（\n）を使用します。

  3. 同じバッチ更新で、CreateParagraphBulletsRequest、テキストの範囲を指定する Range、番号付けのパターンを設定する BulletGlyphPreset を含めます。

次のコードサンプルは、ドキュメントを作成し、3 つの項目を番号付きリストとして挿入する方法を示しています。BulletGlyphPreset は NUMBERED_DECIMAL_ALPHA_ROMAN を使用してリストをフォーマットします。つまり、番号付きリストの最初の 3 つのネストレベルは、10 進数、小文字、小文字のローマ数字で表されます。

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 を使用します。つまり、箇条書きリストの最初の 3 つのネストレベルは、矢印、ひし形、円で表されます。

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 に置き換えます。省略すると、ドキュメントの最初のタブがデフォルトになります。