Trabaja con tablas

En este documento, se explica cómo trabajar con tablas en la API de Google Docs.

La API de Docs te permite editar el contenido de las tablas. Las operaciones que puedes realizar incluyen las siguientes:

• Insertar y borrar filas, columnas o tablas completas
• Insertar contenido en las celdas de la tabla
• Leer contenido de celdas de tablas
• Modificar las propiedades de las columnas y el estilo de las filas

Las tablas en Documentos de Google se representan como un tipo de StructuralElement en el documento. Cada Table contiene una lista de objetos TableRow, en la que cada fila contiene una lista de objetos TableCell. Al igual que con todos los elementos estructurales, la tabla tiene índices de inicio y finalización, que indican la posición de la tabla en un documento. Las propiedades de la tabla incluyen muchos elementos de estilo, como el ancho de las columnas y el padding.

Tabla de ejemplos

El siguiente fragmento JSON muestra una tabla de 2 x 2 con la mayoría de los detalles quitados:

"table": {
    "columns": 2,
    "rows": 2,
    "tableRows": [
        { "tableCells": [
                {
                    "content": [ { "paragraph": { ...  }, } ],
                },
                {
                    "content": [ { "paragraph": { ... }, } ],
                }
            ],
        },
        {
            "tableCells": [
                {
                    "content": [ { "paragraph": { ... }, } ],
                },
                {
                    "content": [ { "paragraph": { ... }, } ],
                }
            ],
        }
    ]
}

En la siguiente tabla, se muestran los desplazamientos del índice para cada elemento estructural en una tabla de 2 x 2, suponiendo que la tabla comienza en el índice S y que todas las celdas están vacías (cada una contiene solo un carácter de nueva línea \n con una longitud = 1):

Elemento	Ruta	Índice de inicio	Índice de finalización
Tabla	/	S	S + 12
TableRow 0	/rows[0]	S + 1	S + 6
TableCell (0,0)	/rows[0]/cells[0]	S + 2	S + 4
Párrafo	/rows[0]/cells[0]/p[0]	S + 3	S + 4
TableCell (0,1)	/rows[0]/cells[1]	S + 4	S + 6
Párrafo	/rows[0]/cells[1]/p[0]	S + 5	S + 6
Fila 1 de la tabla	/rows[1]	S + 6	S + 11
TableCell (1,0)	/rows[1]/cells[0]	S + 7	S + 9
Párrafo	/rows[1]/cells[0]/p[0]	S + 8	S + 9
TableCell (1,1)	/rows[1]/cells[1]	S + 9	S + 11
Párrafo	/rows[1]/cells[1]/p[0]	S + 10	S + 11

Cómo insertar y borrar tablas

Para agregar una tabla a un documento, usa InsertTableRequest. Debes especificar lo siguiente cuando insertes una tabla:

• Son las dimensiones de la tabla en filas y columnas.
• Ubicación para insertar la tabla: Puede ser un índice dentro de un segmento (como un cuerpo, un encabezado o un pie de página) o el final de un segmento. Cualquiera de los dos debe incluir el ID de la pestaña especificada.

Para insertar una tabla al final del cuerpo, especifica el objeto EndOfSegmentLocation y deja segmentId vacío.

No hay un método explícito para borrar tablas. Para borrar una tabla de un documento, trátala como cualquier otro contenido: usa DeleteContentRangeRequest y especifica un range que abarque toda la tabla.

En la siguiente muestra de código, se muestra cómo insertar una tabla de 3 x 3 al final de un documento vacío:

Java

// Insert a table at the end of the body.
// (An empty or unspecified segmentId field indicates the document's body.)

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setInsertTable(
            new InsertTableRequest()
                .setEndOfSegmentLocation(
                    new EndOfSegmentLocation().setTabId(<var>TAB_ID</var>))
                .setRows(3)
                .setColumns(3)));

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

Python

# Insert a table at the end of the body.
# (An empty or unspecified segmentId field indicates the document's body.)

requests = [{
    'insertTable': {
        'rows': 3,
        'columns': 3,
        'endOfSegmentLocation': {
          'segmentId': '',
          'tabId': <var>TAB_ID</var>
        }
    },
}
]

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

En la siguiente muestra de código, se muestra cómo borrar una tabla especificando sus índices de inicio y finalización. En este ejemplo, se muestra cómo recuperar estos índices del contenido del documento.

Java

// Delete a table that was inserted at the start of the body of the first tab.
// (The table is the second element in the body:
//  documentTab.getBody().getContent().get(2).)

Document document = docsService.documents().get(<var>DOCUMENT_ID</var>).setIncludeTabsContent(true).execute();
String tabId = document.getTabs().get(0).getTabProperties().getTabId();
DocumentTab documentTab = document.getTabs().get(0).getDocumentTab();
StructuralElement table = documentTab.getBody().getContent().get(2);

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setDeleteContentRange(
            new DeleteContentRangeRequest()
                .setRange(
                    new Range()
                        .setStartIndex(table.getStartIndex())
                        .setEndIndex(table.getEndIndex())
                        .setTabId(tabId))));

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

Python

# Delete a table that was inserted at the start of the body of the first tab.
# (The table is the second element in the body: ['body']['content'][2].)

document = service.documents().get(documentId=DOCUMENT_ID, includeTabsContent=True).execute()
tab_id = document['tabs'][0]['tabProperties']['tabId']
document_tab = document['tabs'][0]['documentTab']
table = document_tab['body']['content'][2]

requests = [{
    'deleteContentRange': {
      'range': {
        'segmentId': '',
        'startIndex': table['startIndex'],
        'endIndex':   table['endIndex'],
        'tabId': tab_id
      }
    },
}
]

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

Nota: Dado que el ejemplo de inserción inserta la tabla al principio del segmento del cuerpo, el ejemplo de eliminación espera que sea el tercer elemento (indexado en cero). Los primeros dos elementos son el primer salto de sección y el primer párrafo, que siempre están presentes y no se pueden quitar.

Cómo insertar y borrar filas

Si tu documento ya contiene una tabla, la API de Docs te permite insertar y borrar filas de la tabla. Usa InsertTableRowRequest para insertar filas antes o después de una celda de tabla especificada, y DeleteTableRowRequest para quitar una fila que abarque la ubicación de celda especificada.

En el siguiente ejemplo de muestra de código, se muestra cómo insertar texto en la primera celda de una tabla existente y agregar una fila a la tabla:

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Hello")
        .setLocation(new Location().setIndex(5).setTabId(<var>TAB_ID</var>))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
        .setTableCellLocation(new TableCellLocation()
                .setTableStartLocation(new Location()
                        .setIndex(2).setTabId(<var>TAB_ID</var>))
                .setRowIndex(1)
                .setColumnIndex(1))
        .setInsertBelow(true)));

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

Python

requests = [{
      'insertText': {
        'location': {
          'index': 5,
          'tabId': <var>TAB_ID</var>
        },
        'text': 'Hello'
    }
  },
  {
    'insertTableRow': {
        'tableCellLocation': {
            'tableStartLocation': {
                'index': 2,
                'tabId': <var>TAB_ID</var>
            },
            'rowIndex': 1,
            'columnIndex': 1
        },
        'insertBelow': 'true'
    }
  }
]

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

Cómo insertar y borrar columnas

Para insertar una columna en una tabla existente, usa InsertTableColumnRequest. Debes especificar lo siguiente:

• Una celda junto a la que deseas insertar una columna nueva.
• Lado (izquierdo o derecho) en el que se insertará la columna nueva.

En la siguiente muestra de código, se muestra cómo insertar una columna en la tabla de ejemplo de 2x2 que se mostró anteriormente:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setInsertTableColumn(
            new InsertTableColumnRequest()
                .setTableCellLocation(
                    new TableCellLocation()
                        .setTableStartLocation(
                            new Location().setIndex(2).setTabId(<var>TAB_ID</var>))
                        .setRowIndex(0)
                        .setColumnIndex(0))
                .setInsertRight(true)));

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

Python

requests = [{
    'insertTableColumn': {
      'tableCellLocation': {
        'tableStartLocation': {
          'segmentId': '',
          'index': 2,
          'tabId': <var>TAB_ID</var>
        },
        'rowIndex': 0,
        'columnIndex': 0
      },
      'insertRight': True
    },
}
]

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

Para borrar una columna, usa DeleteTableColumnRequest. Debes especificar la ubicación de la celda dentro de una columna objetivo, como se mostró anteriormente para insertar una columna.

Leer contenido de celdas de tablas

Una celda de la tabla contiene una lista de objetos StructuralElement. Cada uno de estos elementos estructurales puede ser un párrafo con texto o algún otro tipo de estructura, incluso otra tabla. Para leer el contenido de la tabla, puedes inspeccionar cada elemento de forma recursiva, como se muestra en el ejemplo de código Cómo extraer el texto de un documento con la API de Docs.

Cómo insertar contenido en celdas de tablas

Para escribir en una celda de la tabla, usa un InsertTextRequest establecido en el location de la celda que deseas actualizar. Los índices de la tabla se ajustan para tener en cuenta el texto actualizado. Lo mismo se aplica a la eliminación de texto de celdas con DeleteContentRangeRequest.

Nota: No puedes insertar una tabla y escribir en sus celdas en una sola solicitud de batchUpdate. Debido a que la traducción de índices desplaza automáticamente los índices de inserción posteriores más allá de la tabla nueva, primero debes insertar la tabla, recuperar su startIndex y, luego, enviar una solicitud batchUpdate independiente con los índices de coordenadas de celda calculados correctos.

En la siguiente muestra de código, se muestra cómo escribir en una celda de la tabla:

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Hello")
        .setLocation(new Location().setIndex(5).setTabId(<var>TAB_ID</var>))));

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

Python

requests = [{
    'insertText': {
      'location': {
        'index': 5,
        'tabId': <var>TAB_ID</var>
      },
      'text': 'Hello'
    }
}]

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

Cómo modificar las propiedades de las columnas

El objeto UpdateTableColumnPropertiesRequest te permite modificar las propiedades de una o más columnas de una tabla.

Debes proporcionar el índice inicial de la tabla junto con un objeto TableColumnProperties. Para modificar solo las columnas seleccionadas, incluye una lista de números de columna en la solicitud. Para modificar todas las columnas de la tabla, proporciona una lista vacía.

En el siguiente ejemplo de código, se muestra cómo actualizar los anchos de las columnas de una tabla, establecer todas las columnas en 100 pts de ancho y, luego, el ancho de la primera columna en 200 pts:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .setColumnIndices(null)
                .setTableColumnProperties(
                    new TableColumnProperties()
                        .setWidthType("FIXED_WIDTH")
                        .setWidth(
                            new Dimension().setMagnitude(100d).setUnit("PT")))
                .setFields("*")));

List<Integer> columnIndices = new ArrayList<>();
columnIndices.add(0);
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .setColumnIndices(columnIndices)
                .setTableColumnProperties(
                    new TableColumnProperties()
                        .setWidthType("FIXED_WIDTH")
                        .setWidth(
                            new Dimension().setMagnitude(200d).setUnit("PT")))
                .setFields("*")));

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

Python

requests = [
  {
    'updateTableColumnProperties': {
      'tableStartLocation': {'index': 2, 'tabId': <var>TAB_ID</var>},
      'columnIndices': [],
      'tableColumnProperties': {
        'widthType': 'FIXED_WIDTH',
        'width': {
          'magnitude': 100,
          'unit': 'PT'
        }
      },
      'fields': '*'
    }
  },
  {
    'updateTableColumnProperties': {
      'tableStartLocation': {'index': 2, 'tabId': <var>TAB_ID</var>},
      'columnIndices': [0],
      'tableColumnProperties': {
        'widthType': 'FIXED_WIDTH',
        'width': {
          'magnitude': 200,
          'unit': 'PT'
        }
      },
      'fields': '*'
    }
  }
]

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

Cómo modificar los estilos de las filas

El objeto UpdateTableRowStyleRequest te permite modificar el estilo de una o más filas de una tabla.

Debes proporcionar el índice inicial de la tabla junto con un objeto TableRowStyle. Para modificar solo las filas seleccionadas, incluye una lista de números de fila en la solicitud. Para modificar todas las filas de la tabla, proporciona una lista vacía.

En el siguiente ejemplo de código, se muestra cómo establecer la altura mínima de la tercera fila de una tabla:

Java

List<Integer> rowIndices = new ArrayList<>();
rowIndices.add(3);

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableRowStyle(
            new UpdateTableRowStyleRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .setRowIndices(rowIndices)
                .setTableRowStyle(
                    new TableRowStyle()
                        .setMinRowHeight(
                            new Dimension().setMagnitude(18d).setUnit("PT")))
                .setFields("*")));

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

Python

requests = [{
    'updateTableRowStyle': {
        'tableStartLocation': {'index': 2, 'tabId': <var>TAB_ID</var>},
        'rowIndices': [3],
        'tableRowStyle': {
            'minRowHeight': {
              'magnitude': 18,
              'unit': 'PT'
            }
        },
        'fields': '*'
    },
}
]

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

Temas relacionados

• Solicitudes en lotes
• Solicitudes y respuestas