Filtry

Filtry umożliwiają sortowanie i filtrowanie danych widocznych podczas wyświetlania arkusza kalkulacyjnego. Filtry nie zmieniają wartości danych w arkuszu kalkulacyjnym. Za pomocą filtrów możesz tymczasowo ukrywać lub sortować informacje. Dane, które pasują do określonych kryteriów filtra, nie są wyświetlane, gdy filtr jest włączony. Dzięki widokom filtrów możesz też zapisywać różne nazwy filtrów i przełączać się między nimi w dowolnym momencie.

Oto przykładowe przypadki użycia filtrów:

  • Sortowanie danych według określonej kolumny. Możesz na przykład posortować rekordy użytkowników według nazwiska.
  • Ukryj dane, które spełniają określony warunek. Na przykład ukryj wszystkie rekordy starsze niż 2 lata.
  • Ukrywaj dane, które pasują do określonej wartości. np. ukryj wszystkie problemy ze stanem „zamknięty”.

Filtr podstawowy

BasicFilter w przypadku arkusza kalkulacyjnego to filtr domyślny, który jest stosowany za każdym razem, gdy ktoś wyświetla ten arkusz. Arkusz kalkulacyjny może zawierać jeden filtr podstawowy na arkusz. Możesz wyłączyć filtr podstawowy, czyszcząc go. Spowoduje to usunięcie filtra i wszystkich jego ustawień z arkusza kalkulacyjnego. Jeśli zechcesz ponownie włączyć ten sam filtr, musisz jeszcze raz określić kryteria.

Zarządzanie filtrem podstawowym

Aby ustawić lub wyczyścić filtr podstawowy, użyj metody spreadsheets.batchUpdate z odpowiednim typem żądania:

Aby wyświetlić filtr podstawowy, użyj metody spreadsheets.get i ustaw parametr fields adresu URL na sheets/basicFilter. Poniższy przykładowy kod spreadsheets.get przedstawia adres URL Arkuszy Google z maską pola:

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

Widoki filtrów

FilterView to filtr o nazwie, który możesz w każdej chwili wyłączyć i włączyć. Arkusz kalkulacyjny może zawierać wiele widoków filtrów, ale możesz stosować tylko jeden naraz.

Oto przykładowe przypadki użycia widoków filtrów:

  • Masz kilka filtrów, których chcesz się przełączać przy wyświetlaniu danych.
  • Nie masz uprawnień do edycji arkusza kalkulacyjnego, ale chcesz zastosować filtr. W takiej sytuacji możesz utworzyć tymczasowy widok filtra, który będzie widoczny tylko dla Ciebie.

  • Chcesz, aby każda osoba, której udostępniasz arkusz kalkulacyjny, miała wgląd w dane w inny sposób. Aby określić widok filtra, który chcesz zastosować, podaj spreadsheetId i filterViewId w adresie URL arkusza kalkulacyjnego. Aby to zrobić, użyj filterViewId zwróconego w odpowiedzi podczas tworzenia widoku filtra.

    Poniższy przykładowy kod pokazuje adres URL Arkuszy Google z widokiem filtra:

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

Zarządzaj widokami filtrów

Aby tworzyć, duplikować, modyfikować lub usuwać widoki filtrów, użyj metody spreadsheets.batchUpdate z odpowiednim typem żądania:

Aby wyświetlić wszystkie widoki filtrów, użyj metody spreadsheets.get i ustaw parametr fields adresu URL na sheets/filterViews. Poniższy przykładowy kod spreadsheets.get przedstawia adres URL Arkuszy Google z maską pola:

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

Reprezentacja filtra

Poniżej znajdziesz przykładowy kod, który przedstawia reprezentację obiektu FilterView w formacie JSON. Obiekt BasicFilter jest taki sam, ale nie zawiera pól filterViewId ani title i nie może używać nazwanego zakresu.

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

Przykładowe dane

Pozostała część tego dokumentu odwołuje się do poniższej przykładowej tabeli danych o sprzedaży:

Tabela 1. Przykładowe dane dotyczące sprzedaży
O B C D E F G
1 Kategoria produktu Numer modelu Koszt Liczba Region Sprzedawca Data wysyłki
2 Diabelski młyn W-24 20,50 USD 4 zachód Beata 1.03.2016 r.
3 Drzwi D-01X 15 PLN 2 południe Amir 15.03.2016 r.
4 Ramka FR-0B1 34 PLN 8 wschód Hania 12.03.2016 r.
5 Panel P-034 18 PLN 4 północ Dewyn 15.03.2016 r.
6 Panel P-052 11,50 PLN 7 wschód Eryk 16.05.2016 r.
7 Diabelski młyn W-24 20,50 USD 11 południe Sheldon 30.04.2016 r.
8 Silnik ENG-0161 330 USD 2 północ Jessie 02.07.2016 r.

Specyfikacja sortowania

Filtr może mieć wiele specyfikacji sortowania. Określają one sposób sortowania danych i są stosowane w określonej kolejności. Atrybut SortSpec.dimensionIndex określa indeks kolumny, do którego należy zastosować sortowanie.

Poniższy przykładowy kod przedstawia specyfikację sortowania:

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

Jeśli zastosujesz tę specyfikację do przykładowych danych sprzedaży, będzie ona sortowana najpierw według „Ilość”, a jeśli 2 wiersze zawierają tę samą ilość, według wymiaru „Data wysyłki”.

Tabela 2. Dane sprzedaży posortowane według 2 kolumn
O B C D E F G
1 Kategoria produktu Numer modelu Koszt Liczba Region Sprzedawca Data wysyłki
2 Drzwi D-01X 15 PLN 2 południe Amir 15.03.2016 r.
3 Silnik ENG-0161 330 USD 2 północ Jessie 02.07.2016 r.
4 Diabelski młyn W-24 20,50 USD 4 zachód Beata 1.03.2016 r.
5 Panel P-034 18 PLN 4 północ Dewyn 15.03.2016 r.
6 Panel P-052 11,50 PLN 7 wschód Eryk 16.05.2016 r.
7 Ramka FR-0B1 34 PLN 8 wschód Hania 12.03.2016 r.
8 Diabelski młyn W-24 20,50 USD 11 południe Sheldon 30.04.2016 r.

Kryteria filtrowania

Metoda FilterCriteria określa, które dane z arkusza kalkulacyjnego są wyświetlane, a jakie ukryte w filtrze podstawowym lub widoku filtra. Każde kryterium zależy od wartości w konkretnej kolumnie. Kryteria filtrowania podajesz w formie mapy, gdzie klucze to indeksy kolumn, a wartościami są kryteriami.

W przypadku kryteriów określonych przy użyciu wartości logicznej condition warunek musi wynosić True, aby wartości były wyświetlane. Warunek nie zastępuje zasady hiddenValues. Jeśli wartość znajduje się w sekcji hiddenValues, wszystkie dopasowania do niej są ukryte.

Poniższy przykładowy kod przedstawia mapę kryteriów filtra:

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

Gdy zastosujesz to kryterium do przykładowych danych o sprzedaży, spowoduje ono wyświetlenie tylko wierszy, w których „Kategoria produktów” nie jest wartością panelu „Panel” i które „Data wysyłki” przypada przed 30 kwietnia 2016 r.

Tabela 3. Dane o sprzedaży na podstawie kryteriów filtrowania
O B C D E F G
1 Kategoria produktu Numer modelu Koszt Liczba Region Sprzedawca Data wysyłki
2 Diabelski młyn W-24 20,50 USD 4 zachód Beata 1.03.2016 r.
3 Drzwi D-01X 15 PLN 2 południe Amir 15.03.2016 r.
4 Ramka FR-0B1 34 PLN 8 wschód Hania 12.03.2016 r.

Przykład

Poniższy przykładowy kod pokazuje, jak utworzyć widok filtra, zduplikować go, a następnie zaktualizować zduplikowaną wersję, korzystając z powyższych przykładowych danych o sprzedaży.

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