L'API Google Docs vous permet de modifier le contenu des tableaux. Voici les opérations que vous pouvez effectuer:
- Insérez et supprimez des lignes, des colonnes ou des tableaux entiers.
- Insérer du contenu dans les cellules d'un tableau
- Lire le contenu des cellules de tableau
- Modifiez les propriétés des colonnes et le style des lignes.
Les tableaux dans Google Docs sont représentés sous la forme d'un type de StructuralElement dans le document. Chaque table contient une liste de lignes de table, chacune contenant une liste de cellules de table. Comme pour tous les éléments structurels, la table comporte des indices de début et de fin, qui indiquent sa position dans le document. Pour en savoir plus sur l'indexation, consultez la structure. Les propriétés de table incluent de nombreux éléments de style, tels que les largeurs de colonne et la marge intérieure.
L'extrait JSON suivant montre un tableau 2x2 simple dont la plupart des détails ont été supprimés:
"table": {
"columns": 2,
"rows": 2,
"tableRows": [
{ "tableCells": [
{
"content": [ { "paragraph": { ... }, } ],
},
{
"content": [ { "paragraph": { ... }, } ],
}
],
},
{
"tableCells": [
{
"content": [ { "paragraph": { ... }, } ],
},
{
"content": [ { "paragraph": { ... }, } ],
}
],
}
]
}
Insérer et supprimer des tableaux
Pour ajouter un tableau à un document, utilisez InsertTableRequest. Lorsque vous insérez un tableau, vous devez spécifier les éléments suivants:
- Dimensions du tableau en lignes et colonnes.
- Emplacement où insérer la nouvelle table: il peut s'agir d'un indice dans un segment ou de la fin d'un segment. L'un d'eux doit inclure l'ID de l'onglet spécifié.
Il n'existe aucune méthode explicite pour supprimer des tables. Pour supprimer une table d'un document, traitez-la comme n'importe quel autre contenu: utilisez DeleteContentRangeRequest, en spécifiant une plage couvrant l'ensemble de la table.
L'exemple suivant insère un tableau 3x3 à la fin d'un document vide:
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()
L'exemple correspondant montre comment supprimer la table précédemment insérée:
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()
Étant donné que vous supprimez une table en tant que contenu ordinaire (en spécifiant les index de début et de fin), vous devez obtenir ces index quelque part. L'exemple montre une façon d'extraire ces index du contenu du document.
Insérer et supprimer des lignes
Si votre document contient déjà un tableau, l'API Google Docs vous permet d'insérer et de supprimer des lignes de tableau. Utilisez InsertTableRowRequest pour insérer des lignes au-dessus ou en dessous d'une cellule de tableau spécifiée, et DeleteTableRowRequest pour supprimer une ligne qui s'étend sur l'emplacement de la cellule spécifiée.
L'exemple suivant insère du texte dans la première cellule d'une table et ajoute une ligne.
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()
Insérer et supprimer des colonnes
Pour insérer une colonne dans une table existante, utilisez InsertTableColumnRequest. Vous devez spécifier les éléments suivants :
- Cellule à côté de laquelle vous souhaitez insérer une colonne.
- Côté (gauche ou droit) où insérer la nouvelle colonne.
L'exemple suivant montre comment insérer une colonne dans la tableau 2x2 illustré précédemment:
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()
Pour supprimer une colonne, utilisez DeleteTableColumnRequest. Vous spécifiez l'emplacement de la cellule dans une colonne cible comme indiqué précédemment pour insérer une colonne.
Lire le contenu des cellules de tableau
Une cellule de tableau contient une liste d'éléments structurels. Chacun de ces éléments structurels peut être un paragraphe avec du texte ou un autre type de structure, voire un autre tableau. Pour lire le contenu d'un tableau, vous pouvez inspecter récursivement chaque élément, comme illustré dans Extraire du texte.
Insérer du contenu dans les cellules d'un tableau
Pour écrire dans une cellule de tableau, utilisez une InsertTextRequest sur un indice dans la cellule que vous souhaitez mettre à jour. Les index de la table sont ajustés pour tenir compte du texte mis à jour. Il en va de même pour la suppression du texte des cellules avec DeleteContentRangeRequest.
Modifier les propriétés des colonnes
UpdateTableColumnPropertiesRequest vous permet de modifier les propriétés d'une ou de plusieurs colonnes d'une table.
Vous devez fournir l'index de début de la table, ainsi qu'un objet TableColumnProperties. Pour modifier uniquement les colonnes sélectionnées, incluez une liste de numéros de colonne dans la requête. Pour modifier toutes les colonnes du tableau, fournissez une liste vide.
L'exemple suivant met à jour les largeurs de colonne d'un tableau, en définissant toutes les colonnes sur 100 points de largeur, puis la largeur de la première colonne sur 200 points:
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()
Modifier les styles de ligne
UpdateTableRowsStyleRequest vous permet de modifier le style d'une ou de plusieurs lignes d'une table.
Vous devez fournir l'index de début de la table, ainsi qu'un objet TableRowStyle. Pour modifier uniquement les lignes sélectionnées, incluez une liste de numéros de ligne dans la requête. Pour modifier toutes les lignes du tableau, fournissez une liste vide.
L'exemple suivant définit la hauteur minimale de la ligne 3 d'un tableau:
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()