Trabajo con listas

La API de Google Docs admite la creación de listas en documentos nuevos, la conversión de párrafos de texto sin formato existentes en listas con viñetas y la eliminación de viñetas de los párrafos.

Cómo crear una lista numerada en un documento nuevo

La API de Docs admite la creación de una lista numerada en un documento nuevo insertando texto y, luego, aplicando un estilo de lista al texto en una sola solicitud por lotes.

Para crear una lista numerada en un documento nuevo, sigue estos pasos:

  1. Usa el método documents.create para crear un documento.

  2. Usa el método documents.batchUpdate y proporciona un InsertTextRequest para agregar contenido al documento. Usa caracteres de salto de línea (\n) para separar los elementos de la lista.

  3. En la misma actualización por lotes, incluye un CreateParagraphBulletsRequest, un Range para especificar el rango de texto y un BulletGlyphPreset para establecer el patrón de numeración.

En el siguiente ejemplo de código, se muestra cómo crear un documento y, luego, insertar tres elementos como una lista numerada. BulletGlyphPreset usa NUMBERED_DECIMAL_ALPHA_ROMAN para dar formato a la lista. Esto significa que los tres primeros niveles de anidación de la lista numerada se representan con un número decimal, una letra minúscula y un número romano en minúsculas.

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}")

Reemplaza TAB_ID por el ID de la pestaña que contiene el contenido de la lista.

Cómo convertir un párrafo en una lista

Una operación común de formato de párrafos es convertir los párrafos existentes en una lista con viñetas.

Para crear una lista, usa el método documents.batchUpdate y proporciona un CreateParagraphBulletsRequest. Incluye un Range para especificar el texto afectado y un BulletGlyphPreset para establecer el patrón de la viñeta.

Se agregan viñetas a todos los párrafos que se superponen con el rango determinado. Si el rango especificado se superpone con una tabla, las viñetas se aplican dentro de las celdas de la tabla. El nivel de anidación de cada párrafo se determina contando las tabulaciones iniciales delante de cada párrafo.

No puedes ajustar el nivel de anidación de una viñeta existente. En su lugar, debes borrar la viñeta, establecer las tabulaciones iniciales delante del párrafo y, luego, volver a crear la viñeta. Para obtener más información, consulta Cómo quitar viñetas de una lista.

También puedes usar CreateParagraphBulletsRequest para cambiar el estilo de viñeta de una lista existente.

En el siguiente ejemplo de código, se muestra una solicitud por lotes que primero inserta texto al comienzo del documento y, luego, crea una lista a partir de los párrafos que abarcan los primeros 50 caracteres. El BulletGlyphPreset usa BULLET_ARROW_DIAMOND_DISC, lo que significa que los primeros tres niveles de anidación de la lista con viñetas se representan con una flecha, un diamante y un 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()

Reemplaza TAB_ID por el ID de la pestaña que contiene el contenido de la lista, o bien omítelo para usar de forma predeterminada la primera pestaña del documento.

Convierte un párrafo en una lista.
Figura 1. Convierte un párrafo en una lista.

Cómo quitar viñetas de una lista

Para quitar viñetas de una lista de párrafos, usa el método documents.batchUpdate y proporciona un DeleteParagraphBulletsRequest. Incluye un Range para especificar el texto afectado.

El método borra todas las viñetas que se superponen con el rango determinado, independientemente del nivel de anidación. Para conservar visualmente el nivel de anidamiento, se agrega una sangría al comienzo de cada párrafo correspondiente.

En la siguiente muestra de código, se muestra una solicitud por lotes que borra viñetas de una lista de párrafos.

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

Reemplaza TAB_ID por el ID de la pestaña que contiene el contenido de la lista, o bien omítelo para usar de forma predeterminada la primera pestaña del documento.