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 des 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 ne s'affichent pas lorsque le filtre est activé. Avec les vues filtrées, vous pouvez également enregistrer différents filtres nommés et passer de l'un à l'autre à tout moment.

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

Cas d'utilisation des filtres

Voici quelques exemples d'utilisation des filtres :

  • Trier les données selon une colonne spécifique. Par exemple, trier les enregistrements des utilisateurs par nom de famille.
  • Masquer les données qui répondent à une condition spécifique. Par exemple, masquer tous les enregistrements datant de plus de deux ans.
  • Masquer les données qui correspondent à une certaine valeur. Par exemple, masquer tous les problèmes dont l'état est "fermé".

Filtre de base

L' BasicFilter objet d'une feuille de calcul est le filtre par défaut qui est appliqué chaque fois qu'une personne 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 l'effaçant. Cela supprime le filtre et tous ses paramètres 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 spreadsheets.batchUpdate méthode avec le type de requête approprié :

Pour lister le filtre de base, utilisez la spreadsheets.get méthode et définissez le fields paramètre d'URL 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

A 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 à 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 sur la même plage de données.

Cas d'utilisation des vues filtrées

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

  • Vous disposez de plusieurs filtres différents que vous souhaitez utiliser lorsque vous consultez les données.
  • Vous n'êtes pas autorisé à modifier 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 qui ne sera visible que pour vous.
  • Vous souhaitez que chaque personne avec laquelle vous partagez votre feuille de calcul puisse consulter les données différemment. Vous pouvez spécifier la vue filtrée que vous souhaitez appliquer en fournissant le 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 spreadsheets.batchUpdate méthode avec le type de requête approprié :

Pour lister toutes vos vues filtrées, utilisez la spreadsheets.get méthode 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 FilterView objet. L' BasicFilter objet 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)
    },
    ...
  }
}

Exemple de données de ventes

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

Tableau 1. Exemple de données de ventes
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 01/03/2016
3 Porte D-01X 15,00 $ 2 Sud Amir 15/03/2016
4 Cadre FR-0B1 34,00 $ 8 Est Anna 12/03/2016
5 Panneau P-034 6,00 $ 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' SortSpec.dimensionIndex attribut 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 à l'exemple de données de ventes, cette spécification trie d'abord les données selon la colonne "Quantité", puis, si deux lignes ont la même quantité, selon la "Date d'expédition".

Tableau 2. Données de ventes triées selon 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,00 $ 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 01/03/2016
5 Panneau P-034 6,00 $ 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' FilterCriteria objet détermine les données de la 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 filtrage sous forme de carte 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 booléenne condition, la condition doit être true pour que les valeurs soient affichées. La condition ne remplace pas hiddenValues. Si une valeur est listée sous hiddenValues, toutes les correspondances pour une valeur sont toujours masquées.

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

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

Lorsqu'ils sont appliqués à l'exemple de données de ventes, ces critères n'affichent que les lignes où la valeur de la colonne "Catégorie de l'élément" 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 utilisant des 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 01/03/2016
3 Porte D-01X 15,00 $ 2 Sud Amir 15/03/2016
4 Cadre FR-0B1 34,00 $ 8 Est Anna 12/03/2016

Exemple de code de vue filtrée

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

Java

sheets/snippets/src/main/java/SheetsFilterViews.java
/*
 * 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
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def filter_views(spreadsheet_id):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    my_range = {
        "sheetId": 0,
        "startRowIndex": 0,
        "startColumnIndex": 0,
    }
    addfilterviewrequest = {
        "addFilterView": {
            "filter": {
                "title": "Sample Filter",
                "range": my_range,
                "sortSpecs": [{
                    "dimensionIndex": 3,
                    "sortOrder": "DESCENDING",
                }],
                "criteria": {
                    0: {"hiddenValues": ["Panel"]},
                    6: {
                        "condition": {
                            "type": "DATE_BEFORE",
                            "values": {"userEnteredValue": "4/30/2016"},
                        }
                    },
                },
            }
        }
    }

    body = {"requests": [addfilterviewrequest]}
    addfilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    duplicatefilterviewrequest = {
        "duplicateFilterView": {
            "filterId": addfilterviewresponse["replies"][0]["addFilterView"][
                "filter"
            ]["filterViewId"]
        }
    }

    body = {"requests": [duplicatefilterviewrequest]}
    duplicatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    updatefilterviewrequest = {
        "updateFilterView": {
            "filter": {
                "filterViewId": duplicatefilterviewresponse["replies"][0][
                    "duplicateFilterView"
                ]["filter"]["filterViewId"],
                "title": "Updated Filter",
                "criteria": {
                    0: {},
                    3: {
                        "condition": {
                            "type": "NUMBER_GREATER",
                            "values": {"userEnteredValue": "5"},
                        }
                    },
                },
            },
            "fields": {"paths": ["criteria", "title"]},
        }
    }

    body = {"requests": [updatefilterviewrequest]}
    updatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )
    print(str(updatefilterviewresponse))
  except HttpError as error:
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  # Pass: spreadsheet_id
  filter_views("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k")