Mit Tabellen arbeiten

In diesem Dokument wird erläutert, wie Sie mit Tabellen in der Google Docs API arbeiten.

Mit der Docs API können Sie Tabelleninhalte bearbeiten. Sie können unter anderem 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-Typ dargestellt. Jedes Table enthält eine Liste von TableRow-Objekten, wobei jede Zeile eine Liste von TableCell-Objekten enthält. Wie alle strukturellen Elemente hat die Tabelle Start- und Endindexe, die die Position der Tabelle in einem Dokument angeben. Zu den Tabelleneigenschaften gehören viele Stilelemente wie Spaltenbreiten und Innenabstand.

Beispieltabelle

Das folgende JSON-Fragment zeigt eine 2x2-Tabelle, in der die meisten Details entfernt wurden:

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

In der folgenden Tabelle sind die Index-Offsets für die einzelnen Strukturelemente in einer 2x2-Tabelle aufgeführt. Dabei wird davon ausgegangen, dass die Tabelle bei Index S beginnt und alle Zellen leer sind (jede enthält nur ein einzelnes Zeilenumbruchzeichen \n mit einer Länge von 1):

Element	Pfad	Startindex	Endindex
Tabelle	/	S	S + 12
TableRow 0	/rows[0]	S + 1	S + 6
TableCell (0,0)	/rows[0]/cells[0]	S + 2	S + 4
Absatz	/rows[0]/cells[0]/p[0]	S + 3	S + 4
TableCell [0,1]	/rows[0]/cells[1]	S + 4	S + 6
Absatz	/rows[0]/cells[1]/p[0]	S + 5	S + 6
TableRow 1	/rows[1]	S + 6	S + 11
TableCell (1,0)	/rows[1]/cells[0]	S + 7	S + 9
Absatz	/rows[1]/cells[0]/p[0]	S + 8	S + 9
TableCell (1,1)	/rows[1]/cells[1]	S + 9	S + 11
Absatz	/rows[1]/cells[1]/p[0]	S + 10	S + 11

Tabellen einfügen und löschen

Verwenden Sie InsertTableRequest, um einem Dokument eine Tabelle hinzuzufügen. Beim Einfügen einer Tabelle müssen Sie Folgendes angeben:

• Die Tabellendimensionen in Zeilen und Spalten.
• Die Position, an der die Tabelle eingefügt werden soll. Dies kann ein Index innerhalb eines Segments (z. B. Body, Header oder Footer) oder das Ende eines Segments sein. Entweder muss die ID des angegebenen Tabs enthalten sein.

Wenn Sie eine Tabelle am Ende des Textkörpers einfügen möchten, geben Sie das Objekt EndOfSegmentLocation an und lassen Sie segmentId leer.

Es gibt keine explizite Methode zum Löschen von Tabellen. Wenn Sie eine Tabelle aus einem Dokument löschen möchten, behandeln Sie sie wie jeden anderen Inhalt: Verwenden Sie DeleteContentRangeRequest und geben Sie einen range an, der die gesamte Tabelle umfasst.

Das folgende Codebeispiel zeigt, wie Sie eine 3x3-Tabelle am Ende eines leeren Dokuments einfügen:

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

Im folgenden Codebeispiel wird gezeigt, wie eine Tabelle gelöscht wird, indem die Start- und Endindexe angegeben werden. In diesem Beispiel wird gezeigt, wie Sie diese Indexe aus dem Dokumentinhalt abrufen.

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

Hinweis :Da im Einfügebeispiel die Tabelle am Anfang des Body-Segments eingefügt wird, wird im Löschbeispiel erwartet, dass sie das dritte Element (nullbasiert) ist. Die ersten beiden Elemente sind der erste Abschnittsumbruch und der erste Absatz, die immer vorhanden sind und nicht entfernt werden können.

Zeilen einfügen und löschen

Wenn Ihr Dokument bereits eine Tabelle enthält, können Sie mit der Docs API Tabellenzeilen einfügen und löschen. Mit InsertTableRowRequest können Sie Zeilen vor oder nach einer angegebenen Tabellenzelle einfügen. Mit DeleteTableRowRequest können Sie eine Zeile entfernen, die sich über die angegebene Zellposition erstreckt.

Das folgende Codebeispiel zeigt, wie Sie Text in die erste Zelle einer vorhandenen Tabelle einfügen und eine Tabellenzeile hinzufügen:

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

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.

Das folgende Codebeispiel zeigt, wie Sie eine Spalte in die Beispieltabelle mit 2 × 2 einfügen, die oben gezeigt wurde:

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

Verwenden Sie DeleteTableColumnRequest, um eine Spalte zu löschen. Sie müssen die Zellenposition in einer Zielspalte angeben, wie zuvor beim Einfügen einer Spalte gezeigt.

Inhalte aus Tabellenzellen lesen

Eine Tabellenzelle enthält eine Liste mit StructuralElement-Objekten. Jedes dieser Strukturelemente kann ein Absatz mit Text oder eine andere Art von Struktur sein, z. B. eine weitere Tabelle. Wenn Sie den Tabelleninhalt lesen möchten, können Sie jedes Element rekursiv untersuchen, wie im Codebeispiel Text aus einem Dokument mit der Docs API extrahieren gezeigt.

Inhalte in Tabellenzellen einfügen

Wenn Sie in eine Tabellenzelle schreiben möchten, verwenden Sie ein InsertTextRequest, das auf die location der Zelle festgelegt ist, die Sie aktualisieren möchten. Die Tabellenindexe werden an den aktualisierten Text angepasst. Dasselbe gilt für das Löschen von Zelltext mit DeleteContentRangeRequest.

Hinweis :Sie können nicht in einer einzigen batchUpdate-Anfrage eine Tabelle einfügen und in ihre Zellen schreiben. Da durch die Indexübersetzung nach dem Einfügen einer neuen Tabelle die nachfolgenden Einfügeindexe automatisch verschoben werden, müssen Sie zuerst die Tabelle einfügen, ihre startIndex abrufen und dann eine separate batchUpdate-Anfrage mit den korrekt berechneten Zellkoordinatenindexen senden.

Das folgende Codebeispiel zeigt, wie in eine Tabellenzelle geschrieben wird:

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

Spalteneigenschaften ändern

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

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

Das folgende Codebeispiel zeigt, wie die Spaltenbreiten einer Tabelle aktualisiert werden. Zuerst werden alle Spalten auf eine Breite von 100 Punkten festgelegt, dann die Breite der ersten Spalte auf 200 Punkte:

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

Zeilenstile ändern

Mit dem UpdateTableRowStyleRequest-Element können Sie den Stil einer oder mehrerer Zeilen in einer Tabelle ändern.

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

Das folgende Codebeispiel zeigt, wie die Mindesthöhe der dritten Zeile in einer Tabelle festgelegt wird:

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

Weitere Informationen

• Batchanfragen
• Anfragen und Antworten