Trabalhar com listas

A API Google Docs oferece suporte à criação de listas em novos documentos, à conversão de parágrafos simples em listas com marcadores e à remoção de marcadores de parágrafos.

Criar uma lista numerada em um novo documento

A API Docs oferece suporte à criação de uma lista numerada em um novo documento inserindo texto e aplicando um estilo de lista ao texto em uma única solicitação em lote.

Para criar uma lista numerada em um novo documento:

  1. Use o documents.create método para criar um documento.

  2. Use o documents.batchUpdate método e forneça um InsertTextRequest para adicionar conteúdo ao documento. Use caracteres de nova linha (\n) para separar os itens da lista.

  3. Na mesma atualização em lote, inclua um CreateParagraphBulletsRequest, um Range para especificar o intervalo de texto e um BulletGlyphPreset para definir o padrão de numeração.

O exemplo de código a seguir mostra como criar um documento e inserir três itens como uma lista numerada. O BulletGlyphPreset usa NUMBERED_DECIMAL_ALPHA_ROMAN para formatar a lista. Isso significa que os três primeiros níveis de aninhamento da lista numerada são representados por um número decimal, uma letra minúscula e um numeral romano minúsculo.

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(<var>TAB_ID</var>))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(22)
                        .setTabId(<var>TAB_ID</var>))
                .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': <var>TAB_ID</var>
            },
            'text': 'Item 1\nItem 2\nItem 3\n'
        }
    },
    {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex': 22,
                'tabId': <var>TAB_ID</var>
            },
            'bulletPreset': 'NUMBERED_DECIMAL_ALPHA_ROMAN'
        }
    }
]

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

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

Substitua TAB_ID pelo ID da guia que contém o conteúdo da lista.

Converter um parágrafo em uma lista

Uma operação comum de formatação de parágrafos é a conversão de parágrafos em uma lista com marcadores.

Para criar uma lista, use o documents.batchUpdate método e forneça um CreateParagraphBulletsRequest. Inclua um Range para especificar o texto afetado e um BulletGlyphPreset para definir o padrão do marcador.

Todos os parágrafos que se sobrepõem ao intervalo especificado são marcados. Se o intervalo especificado se sobrepõe a uma tabela, os marcadores são aplicados nas células da tabela. O nível de aninhamento de cada parágrafo é determinado pela contagem de tabulações à esquerda de cada parágrafo.

Não é possível ajustar o nível de aninhamento de um marcador existente. Em vez disso, exclua o marcador, defina as tabulações à esquerda do parágrafo e crie o marcador novamente. Para mais informações, consulte Remover marcadores de uma lista.

Também é possível usar CreateParagraphBulletsRequest para mudar o estilo de marcador de uma lista existente.

O exemplo de código a seguir mostra uma solicitação em lote que primeiro insere texto no início do documento e, em seguida, cria uma lista dos parágrafos que abrangem os primeiros 50 caracteres. O BulletGlyphPreset usa BULLET_ARROW_DIAMOND_DISC, o que significa que os três primeiros níveis de aninhamento da lista com marcadores são representados por uma seta, um losango e um disco.

Java

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

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

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

Python

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

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

Substitua TAB_ID pelo ID da guia que contém o conteúdo da lista ou omita para usar a primeira guia do documento como padrão.

Converter um parágrafo em uma lista.
Figura 1. Converter um parágrafo em uma lista.

Remover marcadores de uma lista

Para remover marcadores de uma lista de parágrafos, use o documents.batchUpdate método e forneça um DeleteParagraphBulletsRequest. Inclua um Range para especificar o texto afetado.

O método exclui todos os marcadores que se sobrepõem ao intervalo especificado, independentemente do nível de aninhamento. Para preservar visualmente o nível de aninhamento, a indentação é adicionada ao início de cada parágrafo correspondente.

O exemplo de código a seguir mostra uma solicitação em lote que exclui marcadores de uma lista de parágrafos.

Java

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

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

Python

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

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

Substitua TAB_ID pelo ID da guia que contém o conteúdo da lista ou omita para usar a primeira guia do documento como padrão.