Trabalhar com listas

A API Google Docs permite criar listas em novos documentos, converter parágrafos simples em listas com marcadores e remover marcadores de parágrafos.

Criar uma lista numerada em um novo documento

A API Docs permite criar uma lista numerada em um novo documento inserindo texto e aplicando um estilo de lista a ele em uma única solicitação em lote.

Para criar uma lista numerada em um novo documento:

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

  2. Use o método documents.batchUpdate 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 da 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(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}")

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 é converter parágrafos em uma lista com marcadores.

Para criar uma lista, use o método documents.batchUpdate 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 com um ponto. Se o intervalo especificado se sobrepuser a uma tabela, os marcadores serão aplicados nas células da tabela. O nível de aninhamento de cada parágrafo é determinado contando as tabulações à esquerda de cada parágrafo.

Não é possível ajustar o nível de aninhamento de um marcador. Em vez disso, exclua o marcador, defina os recuos iniciais na frente do parágrafo e crie o marcador novamente. Para mais informações, consulte Remover marcadores de uma lista.

Você também pode usar CreateParagraphBulletsRequest para mudar o estilo de marcador de uma lista.

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 com os 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(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()

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 método documents.batchUpdate 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, independente do nível de aninhamento. Para preservar visualmente o nível de aninhamento, um recuo é adicionado 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(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()

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.