Utiliser des tables

Ce document explique comment utiliser les tableaux dans l'API Google Docs.

L'API Docs vous permet de modifier le contenu des tableaux. Voici les opérations que vous pouvez effectuer :

• Insérer et supprimer des lignes, des colonnes ou des tableaux entiers
• Insérez du contenu dans les cellules du tableau.
• Lire le contenu des cellules d'un 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 StructuralElement dans le document. Chaque Table contient une liste d'objets TableRow, où chaque ligne contient une liste d'objets TableCell. Comme tous les éléments structurels, le tableau comporte des index de début et de fin, qui indiquent sa position dans un document. Les propriétés du tableau incluent de nombreux éléments de style tels que la largeur des colonnes et la marge intérieure.

Exemple de table

Le fragment JSON suivant montre un tableau 2x2 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": { ... }, } ],
                }
            ],
        }
    ]
}

Le tableau suivant indique les décalages d'index pour chaque élément structurel d'un tableau 2x2, en supposant que le tableau commence à l'index S et que toutes les cellules sont vides (chacune ne contenant qu'un seul caractère de nouvelle ligne \n de longueur = 1) :

Élément	Chemin	Index de début.	Index de fin.
Table	/	S	S + 12
TableRow 0	/rows[0]	S + 1	S + 6
TableCell (0,0)	/rows[0]/cells[0]	S + 2	S + 4
Paragraphe	/rows[0]/cells[0]/p[0]	S + 3	S + 4
TableCell (0,1)	/rows[0]/cells[1]	S + 4	S + 6
Paragraphe	/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
Paragraphe	/rows[1]/cells[0]/p[0]	S + 8	S + 9
TableCell (1,1)	/rows[1]/cells[1]	S + 9	S + 11
Paragraphe	/rows[1]/cells[1]/p[0]	S + 10	S + 11

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 en colonnes.
• Emplacement où insérer le tableau : il peut s'agir d'un index dans un segment (tel qu'un corps, un en-tête ou un pied de page) ou de la fin d'un segment. L'un ou l'autre doit inclure l'ID de l'onglet spécifié.

Pour insérer un tableau à la fin du corps, spécifiez l'objet EndOfSegmentLocation et laissez segmentId vide.

Il n'existe pas de méthode explicite pour supprimer des tables. Pour supprimer un tableau d'un document, traitez-le comme n'importe quel autre contenu : utilisez DeleteContentRangeRequest en spécifiant un range qui couvre l'intégralité du tableau.

L'exemple de code suivant montre comment insérer 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(<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()

L'exemple de code suivant montre comment supprimer une table en spécifiant ses index de début et de fin. Cet exemple montre comment récupérer ces index à partir du contenu du document.

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

Remarque : Étant donné que l'exemple d'insertion insère le tableau au début du segment de corps, l'exemple de suppression s'attend à ce qu'il s'agisse du troisième élément (indexé à zéro). Les deux premiers éléments sont le premier saut de section et le premier paragraphe, qui sont toujours présents et ne peuvent pas être supprimés.

Insérer et supprimer des lignes

Si votre document contient déjà un tableau, l'API Docs vous permet d'insérer et de supprimer des lignes de tableau. Utilisez InsertTableRowRequest pour insérer des lignes avant ou après une cellule de tableau spécifiée, et DeleteTableRowRequest pour supprimer une ligne qui s'étend sur l'emplacement de cellule spécifié.

L'exemple de code suivant montre comment insérer du texte dans la première cellule d'un tableau existant et ajouter une ligne au tableau :

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

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 :

• Une cellule à côté de laquelle vous souhaitez insérer une colonne.
• Côté (gauche ou droit) où insérer la nouvelle colonne.

L'exemple de code suivant montre comment insérer une colonne dans l'exemple de tableau 2x2 présenté 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(<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()

Pour supprimer une colonne, utilisez DeleteTableColumnRequest. Vous devez spécifier l'emplacement de la cellule dans une colonne cible, comme indiqué précédemment pour l'insertion d'une colonne.

Lire le contenu des cellules d'un tableau

Une cellule de tableau contient une liste d'objets StructuralElement. Chacun de ces éléments structurels peut être un paragraphe de texte ou un autre type de structure, voire un autre tableau. Pour lire le contenu d'un tableau, vous pouvez inspecter chaque élément de manière récursive, comme indiqué dans l'exemple de code Extraire le texte d'un document avec l'API Docs.

Insérer du contenu dans des cellules de tableau

Pour écrire dans une cellule de tableau, utilisez un InsertTextRequest défini sur le location de la cellule que vous souhaitez mettre à jour. Les index du tableau s'ajustent pour tenir compte du texte modifié. Il en va de même pour la suppression du texte d'une cellule avec la touche DeleteContentRangeRequest.

Remarque : Vous ne pouvez pas insérer un tableau et écrire dans ses cellules dans une même requête batchUpdate. Étant donné que la traduction d'index décale automatiquement les index d'insertion suivants au-delà de la nouvelle table, vous devez d'abord insérer la table, récupérer son startIndex, puis envoyer une requête batchUpdate distincte en utilisant les index de coordonnées de cellule calculés correctement.

L'exemple de code suivant montre comment écrire dans une cellule de tableau :

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

Modifier les propriétés des colonnes

UpdateTableColumnPropertiesRequest vous permet de modifier les propriétés d'une ou de plusieurs colonnes d'un tableau.

Vous devez fournir l'index de début du tableau, ainsi qu'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 du tableau, fournissez une liste vide.

L'exemple de code suivant montre comment mettre à jour la largeur des colonnes d'un tableau, en définissant la largeur de toutes les colonnes sur 100 points, puis celle 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(<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()

Modifier les styles de ligne

UpdateTableRowStyleRequest vous permet de modifier le style d'une ou de plusieurs lignes d'un tableau.

Vous devez fournir l'index de début du tableau, 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 de code suivant montre comment définir la hauteur minimale de la troisième ligne 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(<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()

Articles associés

• Requêtes par lot
• Requêtes et réponses