Mit Tabellen arbeiten

Mit der Google Docs API können Sie Tabelleninhalte bearbeiten. Sie können folgende Vorgänge ausführen:

  • Zeilen, Spalten oder ganze Tabellen einfügen und löschen
  • Inhalte in Tabellenzellen einfügen
  • Inhalte aus Tabellenzellen lesen
  • Spalteneigenschaften und den Stil von Zeilen ändern.

Tabellen in Google Docs werden im Dokument als StructuralElement (Strukturelement) dargestellt. Jede Tabelle enthält eine Liste von Tabellenzeilen, wobei jede Zeile eine Liste von Tabellenzellen enthält. Wie alle strukturellen Elemente hat auch die Tabelle Start- und Endindexe, die die Position der Tabelle im Dokument angeben. Weitere Informationen zur Indexierung finden Sie in der Struktur. Tabelleneigenschaften umfassen viele Stilelemente wie Spaltenbreiten und Ränder.

Das folgende JSON-Fragment zeigt eine einfache 2 × 2-Tabelle, aus der die meisten Details entfernt wurden:

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

Tabellen einfügen und löschen

Wenn Sie einem Dokument eine neue Tabelle hinzufügen möchten, verwenden Sie die InsertTableRequest. Beim Einfügen einer Tabelle müssen Sie Folgendes angeben:

  • Die Tabellendimensionen in Zeilen und Spalten.
  • Die Stelle, an der die neue Tabelle eingefügt werden soll: Dies kann ein Index innerhalb eines Segments oder das Ende eines Segments sein. Beide müssen die ID des angegebenen Tabs enthalten.

Es gibt keine explizite Methode zum Löschen von Tabellen. Wenn Sie eine Tabelle aus einem Dokument löschen möchten, gehen Sie wie bei anderen Inhalten vor: Verwenden Sie die DeleteContentRangeRequest und geben Sie einen Bereich an, der die gesamte Tabelle abdeckt.

Im folgenden Beispiel wird am Ende eines leeren Dokuments eine Tabelle mit 3 × 3 Zeilen eingefügt:

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(TAB_ID))
                .setRows(3)
                .setColumns(3)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(DOCUMENT_ID, 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': TAB_ID
        }
    },
}
]

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

In diesem Beispiel wird gezeigt, wie die zuvor eingefügte Tabelle gelöscht wird:

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(DOCUMENT_ID).setIncludeTabsContent(true).execute();
String tabId = document.getTabs()[0].getTabProperties().getTabId();
DocumentTab documentTab = document.getTabs()[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(DOCUMENT_ID, 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=DOCUMENT_ID, body={'requests': requests}).execute()

Da Sie eine Tabelle wie normalen Inhalt löschen, indem Sie Start- und Endindex angeben, müssen Sie diese Indexe irgendwoher beziehen. Das Beispiel zeigt eine Möglichkeit, diese Indizes aus dem Dokumentinhalt zu extrahieren.

Zeilen einfügen und löschen

Wenn Ihr Dokument bereits eine Tabelle enthält, können Sie mit der Google Docs API Tabellenzeilen einfügen und löschen. Mit der InsertTableRowRequest-Anfrage können Sie Zeilen über oder unter einer bestimmten Tabellenzelle einfügen. Mit der DeleteTableRowRequest-Anfrage können Sie eine Zeile entfernen, die den angegebenen Zellenbereich umfasst.

Im folgenden Beispiel wird Text in die erste Tabellenzelle einer Tabelle eingefügt und eine Tabellenzeile hinzugefügt.

Java

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

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

Python

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

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

Spalten einfügen und löschen

Verwenden Sie InsertTableColumnRequest, um eine Spalte in eine vorhandene Tabelle einzufügen. Sie müssen Folgendes angeben:

  • Eine Zelle, neben der eine neue Spalte eingefügt werden soll.
  • Auf welcher Seite (links oder rechts) die neue Spalte eingefügt werden soll.

Im folgenden Beispiel wird gezeigt, wie Sie eine Spalte in die zuvor gezeigte 2 × 2-Tabelle einfügen:

Java

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

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

Python

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

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

Verwenden Sie den DeleteTableColumnRequest, um eine Spalte zu löschen. Die Zellenposition in einer Zielspalte geben Sie wie beim Einfügen einer Spalte an.

Inhalte aus Tabellenzellen lesen

Eine Tabellenzelle enthält eine Liste von Strukturelementen. Jedes dieser Strukturelemente kann ein Absatz mit Text oder ein anderer Strukturtyp sein, auch eine andere Tabelle. Wenn Sie den Tabelleninhalt lesen möchten, können Sie jedes Element rekursiv prüfen, wie unter Text extrahieren gezeigt.

Inhalte in Tabellenzellen einfügen

Wenn Sie in eine Tabellenzelle schreiben möchten, verwenden Sie eine InsertTextRequest für einen Index in der Zelle, die Sie aktualisieren möchten. Die Tabellenindexe werden entsprechend angepasst. Dasselbe gilt für das Löschen von Zellentext mit der DeleteContentRangeRequest.

Spalteneigenschaften ändern

Mit der UpdateTableColumnPropertiesRequest können Sie die Eigenschaften einer oder mehrerer Spalten in einer Tabelle ändern.

Sie müssen den Startindex der Tabelle sowie ein TableColumnProperties-Objekt angeben. Wenn Sie nur ausgewählte Spalten ändern möchten, geben Sie in der Anfrage eine Liste der Spaltennummern an. Wenn Sie alle Spalten in der Tabelle ändern möchten, geben Sie eine leere Liste an.

Im folgenden Beispiel werden die Spaltenbreiten einer Tabelle aktualisiert. Dazu wird die Breite aller Spalten auf 100 pt und dann die Breite der ersten Spalte auf 200 pt festgelegt:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(TAB_ID))
                .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(TAB_ID))
                .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(DOCUMENT_ID, body).execute();

Python

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

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

Zeilenstile ändern

Mit der UpdateTableRowsStyleRequest können Sie den Stil einer oder mehrerer Zeilen in einer Tabelle ändern.

Sie müssen den Startindex der Tabelle sowie ein TableRowStyle-Objekt angeben. Wenn Sie nur ausgewählte Zeilen ändern möchten, fügen Sie der Anfrage eine Liste mit Zeilennummern hinzu. Wenn Sie alle Zeilen in der Tabelle ändern möchten, geben Sie eine leere Liste an.

Im folgenden Beispiel wird die Mindesthöhe von Zeile 3 einer Tabelle festgelegt:

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(TAB_ID))
                .setRowIndices(rowIndices)
                .setTableRowStyle(
                    new TableRowStyle()
                        .setMinRowHeight(
                            new Dimension().setMagnitude(18d).setUnit("PT")))
                .setFields("*")));

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

Python

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

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