Gestire la visibilità dei dati con i filtri

Questo documento spiega come utilizzare i filtri per ordinare e filtrare i dati mostrati in un foglio di lavoro.

I filtri ti consentono di ordinare e filtrare i dati che vedi quando visualizzi un foglio di lavoro. I filtri non modificano i valori dei dati nel foglio di lavoro. Puoi utilizzare i filtri per nascondere o ordinare temporaneamente le informazioni. I dati che corrispondono ai criteri di filtro specificati non vengono visualizzati quando il filtro è attivo. Con le visualizzazioni filtrate, puoi anche salvare diversi filtri denominati e passare da uno all'altro quando vuoi.

Per filtrare i dati restituiti in una richiesta dell'API Google Sheets, utilizza l' DataFilter oggetto. Per saperne di più, consulta Leggere, scrivere e cercare metadati.

Casi d'uso dei filtri

Di seguito sono riportati alcuni casi d'uso di esempio per i filtri:

  • Ordinare i dati in base a una colonna specifica. Ad esempio, ordinare i record utente per cognome.
  • Nascondere i dati che soddisfano una condizione specifica. Ad esempio, nascondere tutti i record precedenti a due anni.
  • Nascondere i dati che corrispondono a un determinato valore. Ad esempio, nascondere tutti i problemi con stato "Chiuso".

Filtro di base

L' BasicFilter oggetto per un foglio di lavoro è il filtro predefinito che viene applicato ogni volta che qualcuno visualizza il foglio di lavoro. Un foglio di lavoro può avere un solo filtro di base per foglio. Puoi disattivare il filtro di base cancellandolo. In questo modo, il filtro e tutte le relative impostazioni vengono rimossi dal foglio di lavoro. Se vuoi riattivare lo stesso filtro, devi impostare di nuovo i criteri.

Gestire il filtro di base

Per impostare o cancellare il filtro di base, utilizza il spreadsheets.batchUpdate metodo con il tipo di richiesta appropriato:

Per elencare il filtro di base, utilizza il spreadsheets.get metodo e imposta il fields parametro URL su sheets/basicFilter. Il seguente esempio di codice spreadsheets.get mostra un URL di Fogli Google con una maschera di campo:

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

Visualizzazioni filtrate

A FilterView è un filtro denominato che puoi attivare e disattivare quando vuoi. Un foglio può avere più visualizzazioni filtrate salvate, ma puoi applicarne solo una alla volta. Un foglio può contenere anche un filtro di base e più visualizzazioni filtrate, ma non puoi applicarli contemporaneamente nello stesso intervallo di dati.

Casi d'uso delle visualizzazioni filtrate

Di seguito sono riportati alcuni casi d'uso di esempio per le visualizzazioni filtrate:

  • Hai diversi filtri diversi che vuoi alternare quando visualizzi i dati.
  • Non disponi dell'accesso in modifica a un foglio di lavoro, ma vuoi comunque applicare un filtro. In questo caso, puoi creare una visualizzazione filtrata temporanea visibile solo a te.

  • Vuoi che ogni persona con cui condividi il foglio di lavoro visualizzi i dati in modo diverso. Puoi specificare la visualizzazione filtrata che vuoi applicare fornendo the spreadsheetId and filterViewId nell'URL del foglio di lavoro. Per farlo, utilizza filterViewId restituito nella risposta quando crei la visualizzazione filtrata.

    Il seguente esempio di codice mostra un URL di Fogli con una visualizzazione filtrata:

    https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID

Gestire le visualizzazioni filtrate

Per creare, duplicare, modificare o eliminare le visualizzazioni filtrate, utilizza il spreadsheets.batchUpdate metodo con il tipo di richiesta appropriato:

Per elencare tutte le visualizzazioni filtrate, utilizza il spreadsheets.get metodo e imposta il fields parametro URL su sheets/filterViews. Il seguente spreadsheets.get esempio di codice mostra un URL di Fogli con una maschera di campo:

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

Rappresentazione JSON di un filtro

Il seguente esempio di codice mostra la rappresentazione JSON di un FilterView oggetto. L' BasicFilter oggetto è lo stesso, tranne per il fatto che non ha i campi filterViewId e title e non può utilizzare un intervallo denominato.

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

Dati delle vendite di esempio

Il resto di questo documento fa riferimento alla seguente tabella di dati delle vendite di esempio:

Tabella 1. Dati delle vendite di esempio
A B C D E F G
1 Categoria elemento Numero di modello Costo Quantità Regione Commerciale Data di spedizione
2 Ruota W-24 20,50 $ 4 Occidentale Beth 01/03/2016
3 Porta D-01X 15,00 $ 2 Meridionale Amir 15/03/2016
4 Cornice FR-0B1 34,00 $ 8 Orientale Hannah 12/03/2016
5 Riquadro P-034 6,00 $ 4 Nord Devyn 15/03/2016
6 Riquadro P-052 11,50 $ 7 Orientale Erik 16/05/2016
7 Ruota W-24 20,50 $ 11 Meridionale Sheldon 30/04/2016
8 Motore ENG-0161 330,00 $ 2 Nord Jessie 02/07/2016

Specifiche di ordinamento

Un filtro può avere più specifiche di ordinamento. Queste specifiche determinano la modalità di ordinamento dei dati e vengono applicate nell'ordine specificato. L' SortSpec.dimensionIndex attributo specifica l'indice della colonna a cui deve essere applicato l'ordinamento.

Il seguente esempio di codice mostra una specifica di ordinamento:

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

Se applicata ai dati delle vendite di esempio, questa specifica ordina prima in base alla colonna "Quantità" e poi, se due righe hanno la stessa quantità, in base alla "Data di spedizione".

Tabella 2. Dati delle vendite ordinati in base a due colonne
A B C D E F G
1 Categoria elemento Numero di modello Costo Quantità Regione Commerciale Data di spedizione
2 Porta D-01X 15,00 $ 2 Meridionale Amir 15/03/2016
3 Motore ENG-0161 330,00 $ 2 Nord Jessie 02/07/2016
4 Ruota W-24 20,50 $ 4 Occidentale Beth 01/03/2016
5 Riquadro P-034 6,00 $ 4 Nord Devyn 15/03/2016
6 Riquadro P-052 11,50 $ 7 Orientale Erik 16/05/2016
7 Cornice FR-0B1 34,00 $ 8 Orientale Hannah 12/03/2016
8 Ruota W-24 20,50 $ 11 Meridionale Sheldon 30/04/2016

Criteri del filtro

L' FilterCriteria oggetto determina quali dati del foglio di lavoro vengono mostrati o nascosti in un filtro di base o in una visualizzazione filtrata. Ogni criterio dipende dai valori di una colonna specifica. I criteri di filtro vengono forniti come una mappa in cui le chiavi sono gli indici delle colonne e i valori sono i criteri.

Per i criteri specificati utilizzando una booleana condition, la condizione deve essere true affinché i valori vengano mostrati. La condizione non sostituisce hiddenValues. Se un valore è elencato in hiddenValues, tutte le corrispondenze per un valore rimangono nascoste.

Il seguente esempio di codice mostra una mappa dei criteri di filtro:

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

Se applicati ai dati delle vendite di esempio, questi criteri mostrano solo le righe in cui il valore della colonna "Categoria elemento" non è "Riquadro" e in cui il valore della colonna "Data di spedizione" è precedente al "30 aprile 2016".

Tabella 3. Dati delle vendite che utilizzano i criteri di filtro
A B C D E F G
1 Categoria elemento Numero di modello Costo Quantità Regione Commerciale Data di spedizione
2 Ruota W-24 20,50 $ 4 Occidentale Beth 01/03/2016
3 Porta D-01X 15,00 $ 2 Meridionale Amir 15/03/2016
4 Cornice FR-0B1 34,00 $ 8 Orientale Hannah 12/03/2016

Esempio di codice della visualizzazione filtrata

Il seguente esempio di codice mostra come creare una visualizzazione filtrata, duplicarla e poi aggiornare la versione duplicata utilizzando i dati delle vendite di esempio.

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