Filtres

Les filtres vous permettent de trier et de filtrer les données affichées lorsque vous consultez une feuille de calcul. Les filtres ne modifient pas les valeurs des données de 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é. Avec les vues filtrées, vous pouvez également enregistrer différents filtres nommés et basculer entre eux à tout moment.

Voici quelques exemples de cas d'utilisation des filtres:

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

Filtre de base

Le BasicFilter d'une feuille de calcul est le filtre par défaut appliqué chaque fois qu'un utilisateur la consulte. Une feuille de calcul peut comporter un filtre de base par feuille. Vous pouvez désactiver le filtre de base en le vidant. 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 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 de calcul peut comporter plusieurs vues filtrées, mais vous ne pouvez en appliquer qu'une à la fois.

Voici quelques exemples de cas d'utilisation des vues de filtre:

  • Vous souhaitez passer d'un filtre à un autre lorsque vous affichez les données.
  • Vous n'êtes pas autorisé à modifier une feuille de calcul, mais vous souhaitez quand même appliquer un filtre. Dans ce cas, vous pouvez créer une vue filtrée temporaire que vous seul pouvez voir.

  • Vous souhaitez que chaque personne avec laquelle vous partagez votre feuille de calcul affiche 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 l'filterViewId renvoyé dans la réponse lorsque vous créez la vue de filtre.

    L'exemple de code suivant montre une URL Google 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 lister toutes vos vues de filtre, 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 Google Sheets avec un masque de champ:

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

Représentation du filtre

L'exemple de code suivant montre la représentation JSON d'un objet FilterView. L'objet BasicFilter est le même, 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

Le reste de ce document fait référence à l'exemple de tableau de données sur les ventes ci-dessous:

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 3/1/2016
3 Porte D-01X 15 $ 2 Sud Amir 3/15/2016
4 Cadre FR-0B1 34,00 $ 8 Est Anna 3/12/2016
5 Panneau P-034 6 $ 4 Nord Devyn 3/15/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 2/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'indice de colonne auquel 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 vente, cette spécification trie d'abord par "Quantité", puis, si deux lignes ont la même quantité, par "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 $ 2 Sud Amir 3/15/2016
3 Moteur ENG-0161 330,00 $ 2 Nord Jessie 2/07/2016
4 Roue W-24 20,50 $ 4 Ouest Beth 3/1/2016
5 Panneau P-034 6 $ 4 Nord Devyn 3/15/2016
6 Panneau P-052 11,50 $ 7 Est Erik 16/05/2016
7 Cadre FR-0B1 34,00 $ 8 Est Anna 3/12/2016
8 Roue W-24 20,50 $ 11 Sud Sheldon 30/04/2016

Critères de filtrage

La méthode FilterCriteria détermine les données de la feuille de calcul à afficher ou à masquer dans un filtre de base ou une vue de filtre. Chaque critère dépend des valeurs d'une colonne spécifique. Vous fournissez les critères de filtrage sous forme de mappage où les clés sont les indices de colonne et les valeurs sont les critères.

Pour les critères spécifiés à l'aide d'un condition booléen, 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 cette valeur restent 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'il est appliqué à l'exemple de données de ventes, ce critère n'affiche que les lignes où la catégorie d'article n'est pas "Panneau" et où la date d'expédition est antérieure au 30 avril 2016.

Tableau 3. Données sur les 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 3/1/2016
3 Porte D-01X 15 $ 2 Sud Amir 3/15/2016
4 Cadre FR-0B1 34,00 $ 8 Est Anna 3/12/2016

Échantillon

L'exemple de code suivant montre comment créer une vue de filtre, la dupliquer, puis mettre à jour la version dupliqué à l'aide de l'exemple de données de vente ci-dessus.

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