L'API Google Docs vous permet de modifier le contenu d'une table. Vous pouvez effectuer les opérations suivantes:
- 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 du tableau
- Modifiez les propriétés des colonnes et le style des lignes.
Dans Google Docs, les tableaux sont représentés par un type d'élément StructuralElement. Chaque table contient une liste de lignes de table, chaque ligne contenant une liste de cellules de table. Comme pour tous les éléments structurels, la table possède des index 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 tableau incluent de nombreux éléments de style, tels que la largeur des colonnes et la marge intérieure.
Le fragment JSON suivant montre une table 2x2 simple dans laquelle 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 une table à un document, utilisez InsertTableRequest. Lorsque vous insérez une table, vous devez spécifier les éléments suivants:
- Les dimensions du tableau en lignes et en colonnes
- Emplacement d'insertion de la nouvelle table: il peut s'agir d'un indice dans un segment ou de la fin d'un segment.
Il n'existe pas de méthode explicite pour supprimer des tables. Pour supprimer une table d'un document, traitez-la comme tout autre contenu: utilisez la méthode DeleteContentRangeRequest, en spécifiant une plage couvrant l'intégralité 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())
.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': ''
}
},
}
]
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.
// (The table is the second element in the body:
// document.getBody().getContent().get(2).)
Document document = docsService.documents().get(DOCUMENT_ID).execute();
StructuralElement table = document.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()))));
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.
# (The table is the second element in the body: ['body']['content'][2].)
document = service.documents().get(documentId=DOCUMENT_ID).execute()
table = document['body']['content'][2]
requests = [{
'deleteContentRange': {
'range': {
'segmentId': '',
'startIndex': table['startIndex'],
'endIndex': table['endIndex']
}
},
}
]
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 des index de début et de fin, vous devez récupérer ces index quelque part. L'exemple montre un moyen 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 couvre l'emplacement de cellule spécifié.
L'exemple suivant insère du texte dans la première cellule d'un tableau et ajoute une ligne.
Java
List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
.setText("Hello")
.setLocation(new Location().setIndex(5))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
.setTableCellLocation(new TableCellLocation()
.setTableStartLocation(new Location()
.setIndex(2))
.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
},
'text': 'Hello'
}
},
{
'insertTableRow': {
'tableCellLocation': {
'tableStartLocation': {
'index': 2
},
'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 la méthode InsertTableColumnRequest. Vous devez spécifier les éléments suivants :
- Une cellule à côté de laquelle vous souhaitez insérer une nouvelle colonne.
- Le côté (gauche ou droit) où insérer la nouvelle colonne.
L'exemple suivant montre comment insérer une colonne dans la table 2x2 présentée précédemment:
Java
List<Request> requests = new ArrayList<>();
requests.add(
new Request()
.setInsertTableColumn(
new InsertTableColumnRequest()
.setTableCellLocation(
new TableCellLocation()
.setTableStartLocation(
new Location().setIndex(2))
.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
},
'rowIndex': 0,
'columnIndex': 0
},
'insertRight': True
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()
Pour supprimer une colonne, utilisez la méthode DeleteTableColumnRequest. Vous spécifiez l'emplacement des cellules dans une colonne cible comme indiqué précédemment pour insérer une colonne.
Lire le contenu des cellules d'un 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'une table, vous pouvez inspecter de manière récursive chaque élément, comme indiqué dans la section Extraire du texte.
Insertion de contenu dans les cellules d'un tableau
Pour écrire dans une cellule de table, utilisez une requête InsertTextRequest pour un index au sein de la cellule que vous souhaitez mettre à jour. Les index des tables s'ajustent en fonction du texte mis à jour. Il en va de même pour la suppression du texte d'une cellule avec DeleteContentRangeRequest.
Modifier les propriétés des colonnes
La méthode 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épart de la table, avec un objet TableColumnProperties. Pour modifier uniquement les colonnes sélectionnées, incluez une liste de numéros de colonnes dans la requête. Pour modifier toutes les colonnes de la table, fournissez une liste vide.
L'exemple suivant met à jour la largeur des colonnes d'une table, en définissant toutes les colonnes sur une largeur de 100 points, puis la largeur de la première colonne sur 200 pts:
Java
List<Request> requests = new ArrayList<>();
requests.add(
new Request()
.setUpdateTableColumnProperties(
new UpdateTableColumnPropertiesRequest()
.setTableStartLocation(new Location().setIndex(2))
.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))
.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},
'columnIndices': [],
'tableColumnProperties': {
'widthType': 'FIXED_WIDTH',
'width': {
'magnitude': 100,
'unit': 'PT'
}
},
'fields': '*'
},
'updateTableColumnProperties': {
'tableStartLocation': {'index': 2},
'columnIndices': [0],
'tableColumnProperties': {
'widthType': 'FIXED_WIDTH',
'width': {
'magnitude': 200,
'unit': 'PT'
}
},
'fields': '*'
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()
Modifier des styles de ligne
La méthode UpdateTableRowsStyleRequest vous permet de modifier le style d'une ou de plusieurs lignes d'une table.
Vous devez fournir l'index de départ de la table, avec un objet TableRowStyle. Pour modifier uniquement les lignes sélectionnées, incluez une liste des numéros de ligne dans la requête. Pour modifier toutes les lignes de la table, 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))
.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},
'rowIndices': [3],
'tableRowStyle': {
'minRowHeight': {
'magnitude': 18,
'unit': 'PT'
}
},
'fields': '*'
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()