Gérer la visibilité des données avec des filtres

Ce document explique comment utiliser des filtres pour trier et filtrer les données affichées dans une feuille de calcul.

Les filtres vous permettent de trier et de filtrer les données que vous voyez lorsque vous consultez une feuille de calcul. Les filtres ne modifient pas les valeurs de données dans votre feuille de calcul. Vous pouvez utiliser des filtres pour masquer ou trier temporairement des informations. Les données qui correspondent aux critères de filtrage spécifiés n'apparaissent pas lorsque le filtre est activé. Les vues filtrées vous permettent également d'enregistrer différents filtres nommés et de passer de l'un à l'autre à tout moment.

Pour filtrer les données renvoyées dans une requête de l'API Google Sheets, utilisez l'objet DataFilter. Pour en savoir plus, consultez Lire, écrire et rechercher des métadonnées.

Filtrer les cas d'utilisation

Voici quelques exemples d'utilisation des filtres :

Trier les données d'une colonne spécifique Par exemple, triez les enregistrements utilisateur par nom de famille.
Masquez les données qui remplissent une condition spécifique. Par exemple, masquez tous les enregistrements datant de plus de deux ans.
Masquez les données qui correspondent à une certaine valeur. Par exemple, masquez tous les problèmes dont l'état est "closed" (clôturé).

Filtre de base

L'objet BasicFilter d'une feuille de calcul est le filtre par défaut qui est appliqué chaque fois qu'un utilisateur consulte la feuille de calcul. Une feuille de calcul ne peut contenir qu'un seul filtre de base par feuille. Vous pouvez désactiver le filtre de base en le décochant. Le filtre et tous ses paramètres sont alors supprimés de la feuille de calcul. Si vous souhaitez réactiver le même filtre, vous devez définir à nouveau les critères.

Gérer le filtre de base

Pour définir ou effacer le filtre de base, utilisez la méthode spreadsheets.batchUpdate avec le type de requête approprié :

Pour définir le filtre de base, utilisez la méthode SetBasicFilterRequest.
Pour effacer le filtre de base, utilisez la méthode ClearBasicFilterRequest.

Pour lister le filtre de base, utilisez la méthode spreadsheets.get et définissez le paramètre d'URL fields sur sheets/basicFilter. L'exemple de code spreadsheets.get suivant montre une URL Google Sheets avec un masque de champ :

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/basicFilter

Vues filtrées

Un FilterView est un filtre nommé que vous pouvez activer et désactiver à tout moment. Une feuille peut contenir plusieurs vues filtrées enregistrées, mais vous ne pouvez en appliquer qu'une seule à la fois. Une feuille peut également contenir à la fois un filtre de base et plusieurs vues filtrées, mais vous ne pouvez pas appliquer les deux simultanément à la même plage de données.

Cas d'utilisation des vues filtrées

Voici quelques exemples d'utilisation des vues filtrées :

Vous souhaitez alterner entre plusieurs filtres lorsque vous consultez les données.
Vous ne disposez pas des droits de modification pour une feuille de calcul, mais vous souhaitez tout de même appliquer un filtre. Dans ce cas, vous pouvez créer une vue filtrée temporaire que vous seul pourrez voir.
Vous souhaitez que chaque personne avec laquelle vous partagez votre feuille de calcul puisse afficher les données différemment. Vous pouvez spécifier la vue de filtre que vous souhaitez appliquer en fournissant spreadsheetId et filterViewId dans l'URL de la feuille de calcul. Pour ce faire, utilisez le filterViewId renvoyé dans la réponse lorsque vous créez la vue filtrée.

L'exemple de code suivant montre une URL Sheets avec une vue filtrée :
```
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID
```

Gérer les vues filtrées

Pour créer, dupliquer, modifier ou supprimer des vues filtrées, utilisez la méthode spreadsheets.batchUpdate avec le type de requête approprié :

Pour créer une vue filtrée, utilisez la méthode AddFilterViewRequest.
Pour copier une vue filtrée, utilisez la méthode DuplicateFilterViewRequest.
Pour modifier les propriétés d'une vue filtrée, utilisez la méthode UpdateFilterViewRequest.
Pour supprimer une vue filtrée, utilisez la méthode DeleteFilterViewRequest.

Pour lister toutes vos vues filtrées, utilisez la méthode spreadsheets.get et définissez le paramètre d'URL fields sur sheets/filterViews. L'exemple de code spreadsheets.get suivant montre une URL Sheets avec un masque de champ :

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/filterViews

Représentation JSON d'un filtre

L'exemple de code suivant montre la représentation JSON d'un objet FilterView. L'objet BasicFilter est identique, sauf qu'il ne comporte pas les champs filterViewId et title, et qu'il ne peut pas utiliser de plage nommée.

{
  "filterViewId": number,
  "title": string,
  "range": {
    object(GridRange)
  },
  "namedRangeId": string,
  "sortSpecs": [
    {
      object(SortSpec)
    }
  ],
  "criteria": {
    string: {
      object(FilterCriteria)
    },
    ...
  }
}

Exemples de données de vente

Le reste de ce document fait référence au tableau d'exemple de données de vente suivant :

**Tableau 1.** Exemple de données de vente
	A	B	C	D	E	F	G
1	Catégorie de l'élément	Numéro de modèle	Coût	Quantité	Région	Commercial	Date d'expédition
2	Roue	W-24	20,50 $	4	Ouest	Beth	1/3/2016
3	Porte	D-01X	15 $	2	Sud	Amir	15/03/2016
4	Cadre	FR-0B1	34,00 $	8	Est	Anna	12/03/2016
5	Panneau	P-034	6 $	4	Nord	Devyn	15/03/2016
6	Panneau	P-052	11,50 $	7	Est	Erik	16/05/2016
7	Roue	W-24	20,50 $	11	Sud	Sheldon	30/04/2016
8	Moteur	ENG-0161	330,00 $	2	Nord	Jessie	02/07/2016

Spécifications de tri

Un filtre peut comporter plusieurs spécifications de tri. Ces spécifications déterminent comment trier les données et sont appliquées dans l'ordre spécifié. L'attribut SortSpec.dimensionIndex spécifie l'index de la colonne à laquelle le tri doit être appliqué.

L'exemple de code suivant montre une spécification de tri :

[
  {
    "dimensionIndex": 3,
    "sortOrder": "ASCENDING"
  },
  {
    "dimensionIndex": 6,
    "sortOrder": "ASCENDING"
  }
]

Lorsqu'elle est appliquée aux exemples de données de vente, cette spécification trie d'abord les données par colonne "Quantité", puis, si deux lignes ont la même quantité, par colonne "Date d'expédition".

**Tableau 2.** Données de vente triées par deux colonnes
	A	B	C	D	E	F	G
1	Catégorie de l'élément	Numéro de modèle	Coût	Quantité	Région	Commercial	Date d'expédition
2	Porte	D-01X	15 $	2	Sud	Amir	15/03/2016
3	Moteur	ENG-0161	330,00 $	2	Nord	Jessie	02/07/2016
4	Roue	W-24	20,50 $	4	Ouest	Beth	1/3/2016
5	Panneau	P-034	6 $	4	Nord	Devyn	15/03/2016
6	Panneau	P-052	11,50 $	7	Est	Erik	16/05/2016
7	Cadre	FR-0B1	34,00 $	8	Est	Anna	12/03/2016
8	Roue	W-24	20,50 $	11	Sud	Sheldon	30/04/2016

Critères de filtrage

L'objet FilterCriteria détermine les données de feuille de calcul qui sont affichées ou masquées dans un filtre de base ou une vue filtrée. Chaque critère dépend des valeurs d'une colonne spécifique. Vous fournissez les critères de filtre sous forme de mappage où les clés sont les index de colonne et les valeurs sont les critères.

Pour les critères spécifiés à l'aide d'une valeur booléenne condition, la condition doit être true pour que les valeurs s'affichent. La condition ne remplace pas hiddenValues. Si une valeur est listée sous hiddenValues, toutes les correspondances pour cette valeur sont toujours masquées.

L'exemple de code suivant montre une carte des critères de filtrage :

{
  0: {
    'hiddenValues': ['Panel']
  },
  6: {
    'condition': {
      'type': 'DATE_BEFORE',
      'values': {
        'userEnteredValue': '4/30/2016'
      }
    }
  }
}

Lorsqu'il est appliqué aux données de vente échantillonnées, ce critère n'affiche que les lignes où la valeur de la colonne "Catégorie d'article" n'est pas "Panneau" et où la valeur de la colonne "Date d'expédition" est antérieure au 30 avril 2016.

**Tableau 3.** Données de ventes à l'aide de critères de filtrage
	A	B	C	D	E	F	G
1	Catégorie de l'élément	Numéro de modèle	Coût	Quantité	Région	Commercial	Date d'expédition
2	Roue	W-24	20,50 $	4	Ouest	Beth	1/3/2016
3	Porte	D-01X	15 $	2	Sud	Amir	15/03/2016
4	Cadre	FR-0B1	34,00 $	8	Est	Anna	12/03/2016

Exemple de code de la vue de filtre

L'exemple de code suivant montre comment créer une vue filtrée, la dupliquer, puis mettre à jour la version dupliquée à l'aide des exemples de données de vente.

Java

sheets/snippets/src/main/java/SheetsFilterViews.java

Afficher sur GitHub

/*
 * Dependencies (Maven):
 * com.google.apis:google-api-services-sheets:v4-rev20220927-2.0.0
 * com.google.auth:google-auth-library-oauth2-http:1.19.0
 */

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.*;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.*;

public class SheetsFilterViews {

    public static void main(String... args) {
        filterViews("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k");
    }

    public static void filterViews(String spreadsheetId) {
        try {
            // Load pre-authorized user credentials from the environment.
            // TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2.
            GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
                    .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));

            Sheets service = new Sheets.Builder(
                    GoogleNetHttpTransport.newTrustedTransport(),
                    GsonFactory.getDefaultInstance(),
                    new HttpCredentialsAdapter(credentials))
                    .setApplicationName("Sheets Filter Views Sample")
                    .build();

            // --- Step 1: Add Filter View ---
            GridRange myRange = new GridRange()
                    .setSheetId(0)
                    .setStartRowIndex(0)
                    .setStartColumnIndex(0);

            // Construct Criteria for Column 0 (Hidden Values)
            FilterCriteria criteria0 = new FilterCriteria()
                    .setHiddenValues(Collections.singletonList("Panel"));

            // Construct Criteria for Column 6 (Date Condition)
            ConditionValue dateValue = new ConditionValue().setUserEnteredValue("4/30/2016");
            BooleanCondition dateCondition = new BooleanCondition()
                    .setType("DATE_BEFORE")
                    .setValues(Collections.singletonList(dateValue));
            FilterCriteria criteria6 = new FilterCriteria().setCondition(dateCondition);

            // Map criteria to column indices (Note: keys are Strings in Java map)
            Map<String, FilterCriteria> criteriaMap = new HashMap<>();
            criteriaMap.put("0", criteria0);
            criteriaMap.put("6", criteria6);

            FilterView filterView = new FilterView()
                    .setTitle("Sample Filter")
                    .setRange(myRange)
                    .setSortSpecs(Collections.singletonList(
                            new SortSpec().setDimensionIndex(3).setSortOrder("DESCENDING")
                    ))
                    .setCriteria(criteriaMap);

            // --- Step 1: Add Filter View ---
            // (Request construction remains the same)
            // ...
            AddFilterViewRequest addFilterViewRequest = new AddFilterViewRequest().setFilter(filterView);

            BatchUpdateSpreadsheetRequest batchRequest1 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setAddFilterView(addFilterViewRequest)));

            BatchUpdateSpreadsheetResponse response1 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest1)
                    .execute();

            if (response1.getReplies() == null || response1.getReplies().isEmpty()) {
                System.err.println("Error: No replies returned from AddFilterView request.");
                return;
            }

            Response reply1 = response1.getReplies().get(0);
            if (reply1.getAddFilterView() == null || reply1.getAddFilterView().getFilter() == null) {
                 System.err.println("Error: Response did not contain AddFilterView data.");
                 return;
            }

            int filterId = reply1.getAddFilterView().getFilter().getFilterViewId();

            // --- Step 2: Duplicate Filter View ---
            DuplicateFilterViewRequest duplicateRequest = new DuplicateFilterViewRequest()
                    .setFilterId(filterId);

            BatchUpdateSpreadsheetRequest batchRequest2 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setDuplicateFilterView(duplicateRequest)));

            BatchUpdateSpreadsheetResponse response2 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest2)
                    .execute();

            if (response2.getReplies() == null || response2.getReplies().isEmpty()) {
                 System.err.println("Error: No replies returned from DuplicateFilterView request.");
                 return;
            }

            Response reply2 = response2.getReplies().get(0);
            if (reply2.getDuplicateFilterView() == null || reply2.getDuplicateFilterView().getFilter() == null) {
                System.err.println("Error: Response did not contain DuplicateFilterView data.");
                return;
            }

            int newFilterId = reply2.getDuplicateFilterView().getFilter().getFilterViewId();

            // --- Step 3: Update Filter View ---
            // Extract the new ID from the duplicate response
            int newFilterId = response2.getReplies().get(0)
                    .getDuplicateFilterView().getFilter().getFilterViewId();

            // Create update criteria
            Map<String, FilterCriteria> updateCriteriaMap = new HashMap<>();
            updateCriteriaMap.put("0", new FilterCriteria()); // Empty criteria

            ConditionValue numValue = new ConditionValue().setUserEnteredValue("5");
            BooleanCondition numCondition = new BooleanCondition()
                    .setType("NUMBER_GREATER")
                    .setValues(Collections.singletonList(numValue));
            updateCriteriaMap.put("3", new FilterCriteria().setCondition(numCondition));

            FilterView updateFilterView = new FilterView()
                    .setFilterViewId(newFilterId)
                    .setTitle("Updated Filter")
                    .setCriteria(updateCriteriaMap);

            UpdateFilterViewRequest updateRequest = new UpdateFilterViewRequest()
                    .setFilter(updateFilterView)
                    .setFields("criteria,title");

            BatchUpdateSpreadsheetRequest batchRequest3 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setUpdateFilterView(updateRequest)));

            BatchUpdateSpreadsheetResponse response3 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest3)
                    .execute();

            System.out.println(response3.toPrettyString());

        } catch (IOException | GeneralSecurityException e) {
            System.err.println("An error occurred: " + e);
        }
    }
}

Python

sheets/snippets/sheets_filter_views.py