Utiliser des tables

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é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 sous la forme d'un type StructuralElement dans le document. Chaque table contient une liste de lignes de tableau, où chaque ligne contient une liste de cellules de tableau. Comme tous les éléments structurels, le tableau comporte 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.

L'extrait JSON suivant montre un tableau simple de 2x2 avec la plupart des détails 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 en colonnes.
• Emplacement où insérer le nouveau tableau : il peut s'agir d'un index dans un segment 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 une plage qui couvre l'intégralité du tableau.

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 le tableau précédemment inséré :

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 comme du 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.

L'exemple précédent a inséré le tableau au début du corps. Cet exemple s'attend donc à 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. Ils 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 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 cellule spécifié.

L'exemple suivant insère du texte dans la première cellule d'un tableau et ajoute 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(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 droite) où insérer la nouvelle colonne.

L'exemple suivant montre comment insérer une colonne dans le 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(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 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'un tableau, vous pouvez inspecter chaque élément de manière récursive, comme indiqué dans Extraire du texte.

Insérer du contenu dans des cellules de tableau

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

Modifier les propriétés des colonnes

La 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épart 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 suivant met à 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(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'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 suivant définit 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(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()