إدارة إمكانية ظهور البيانات باستخدام الفلاتر

يتناول هذا المستند استخدام الفلاتر لترتيب البيانات المعروضة في جدول بيانات وتصفيتها.

تتيح لك الفلاتر ترتيب البيانات التي تظهر لك عند عرض جدول بيانات وتصفيتها. لا تغيِّر الفلاتر قيم البيانات في جدول البيانات. يمكنك استخدام الفلاتر لإخفاء المعلومات أو ترتيبها مؤقتًا. لا تظهر البيانات التي تطابق معايير الفلتر المحدّدة أثناء تفعيل الفلتر. باستخدام عروض الفلاتر، يمكنك أيضًا حفظ فلاتر مختلفة تحمل أسماء والتبديل بينها متى شئت.

لفلترة البيانات التي يتم عرضها في طلب بيانات من واجهة برمجة التطبيقات لـ Google Sheets، استخدِم الـ DataFilter عنصر. لمزيد من المعلومات، يُرجى الاطّلاع على قراءة البيانات الوصفية وكتابتها والبحث عنها metadata.

حالات استخدام الفلاتر

في ما يلي بعض الأمثلة على حالات استخدام الفلاتر:

• ترتيب البيانات حسب عمود معيّن على سبيل المثال، ترتيب سجلّات المستخدمين حسب الاسم الأخير
• إخفاء البيانات التي تستوفي شرطًا معيّنًا على سبيل المثال، إخفاء جميع السجلّات التي مضى عليها أكثر من عامَين
• إخفاء البيانات التي تطابق قيمة معيّنة على سبيل المثال، إخفاء جميع المشاكل التي تحمل الحالة "مغلقة"

الفلتر الأساسي

عنصر BasicFilter لجدول بيانات هو الفلتر التلقائي الذي يتم تطبيقه كلما عرض أي مستخدم جدول البيانات. يمكن أن يحتوي جدول البيانات على فلتر أساسي واحد فقط لكل ورقة. يمكنك إيقاف الفلتر الأساسي عن طريق محوه. يؤدي هذا الإجراء إلى إزالة الفلتر وجميع إعداداته من جدول البيانات. إذا أردت إعادة تفعيل الفلتر نفسه، عليك ضبط المعايير مرة أخرى.

إدارة الفلتر الأساسي

لضبط الفلتر الأساسي أو محوه، استخدِم الـ spreadsheets.batchUpdate مع نوع الطلب المناسب:

• لضبط الفلتر الأساسي، استخدِم الـ SetBasicFilterRequest طريقة.
• لمحو الفلتر الأساسي، استخدِم الـ ClearBasicFilterRequest طريقة.

لعرض الفلتر الأساسي، استخدِم الـ spreadsheets.get واضبط مَعلمة fields في عنوان URL على sheets/basicFilter. تعرض عيّنة الرمز البرمجي التالية لطريقة spreadsheets.get عنوان URL لـ "جداول بيانات Google" مع قناع حقول:

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

عروض الفلاتر

A FilterView هو فلتر يحمل اسمًا ويمكنك إيقافه وتفعيله متى شئت. يمكن أن تحتوي ورقة البيانات على عروض فلاتر متعددة محفوظة، ولكن يمكنك تطبيق عرض واحد فقط في كل مرة. يمكن أن تحتوي ورقة البيانات أيضًا على فلتر أساسي وعروض فلاتر متعددة، ولكن لا يمكنك تطبيق كليهما في الوقت نفسه على نطاق البيانات نفسه.

حالات استخدام عروض الفلاتر

في ما يلي بعض الأمثلة على حالات استخدام عروض الفلاتر:

• لديك عدة فلاتر مختلفة تريد التبديل بينها عند عرض البيانات.
• ليس لديك إذن تعديل جدول بيانات ولكنك لا تزال تريد تطبيق فلتر. في هذه الحالة، يمكنك إنشاء عرض فلتر مؤقت لا يظهر إلا لك.

• تريد أن يرى كل مستخدم تشارك معه جدول البيانات البيانات بشكل مختلف. يمكنك تحديد عرض الفلتر الذي تريد تطبيقه من خلال تقديم الـ spreadsheetId و filterViewId في عنوان URL لجدول البيانات. لإجراء ذلك، استخدِم filterViewId الذي تم عرضه في الردّ عند إنشاء عرض الفلتر.

  تعرض عيّنة الرمز البرمجي التالية عنوان URL لـ "جداول بيانات Google" مع عرض فلتر:

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

إدارة عروض الفلاتر

لإنشاء عروض الفلاتر أو تكرارها أو تعديلها أو حذفها، استخدِم طريقة spreadsheets.batchUpdate مع نوع الطلب المناسب:

• لإنشاء عرض فلتر، استخدِم الـ AddFilterViewRequest طريقة.
• لإنشاء نسخة من عرض فلتر، استخدِم الـ DuplicateFilterViewRequest طريقة.
• لتعديل خصائص عرض فلتر، استخدِم الـ UpdateFilterViewRequest طريقة.
• لحذف عرض فلتر، استخدِم الـ DeleteFilterViewRequest طريقة.

لعرض جميع عروض الفلاتر، استخدِم الـ spreadsheets.get واضبط مَعلمة fields في عنوان URL على sheets/filterViews. تعرض عيّنة الرمز البرمجي التالية spreadsheets.get عنوان URL لـ "جداول بيانات Google" مع قناع حقول:

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

تمثيل JSON لفلتر

تعرض عينة تعليمات برمجية التالية تمثيل JSON لعنصر FilterView. عنصر BasicFilter هو نفسه باستثناء أنّه لا يحتوي على الحقلَين filterViewId وtitle، ولا يمكنه استخدام نطاق مُعنوَن.

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

مثال على بيانات المبيعات

تشير بقية هذا المستند إلى جدول بيانات المبيعات النموذجي التالي:

الجدول 1. مثال على بيانات المبيعات

	A	ب	C	D	ج	ح	G
1	فئة العنصر	رقم الطراز	التكلفة	الكمية	المنطقة	مندوب مبيعات	تاريخ الشحن
2	العجلة	W-24	‫$20.50	4	الغرب	Beth	2016/3/1
3	الباب	D-01X	‫$15.00	2	الجنوب	Amir	2016/3/15
4	الإطار	FR-0B1	‫$34.00	8	الشرق	Hannah	2016/3/12
5	اللوحة	P-034	‫6.00 دولار أمريكي	4	الشمال	Devyn	2016/3/15
6	اللوحة	P-052	‫$11.50	7	الشرق	إريك	2016/5/16
7	العجلة	W-24	‫$20.50	11	الجنوب	Sheldon	2016/4/30
8	المحرّك	ENG-0161	‫$330.00	2	الشمال	Jessie	2016/7/2

مواصفات الترتيب

يمكن أن يحتوي الفلتر على مواصفات ترتيب متعددة. تحدّد هذه المواصفات كيفية ترتيب البيانات ويتم تطبيقها بالترتيب المحدّد. تحدّد السمة SortSpec.dimensionIndex فهرس العمود الذي يجب تطبيق الترتيب عليه.

تعرض عيّنة تعليمات برمجية التالية مواصفات ترتيب:

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

عند تطبيق هذه المواصفات على بيانات المبيعات النموذجية، يتم الترتيب حسب عمود "الكمية" أولاً، ثم حسب "تاريخ الشحن" إذا كان لصفَين الكمية نفسها.

الجدول 2. بيانات المبيعات مرتّبة حسب عمودَين

	A	ب	C	D	ج	ح	G
1	فئة العنصر	رقم الطراز	التكلفة	الكمية	المنطقة	مندوب مبيعات	تاريخ الشحن
2	الباب	D-01X	‫$15.00	2	الجنوب	Amir	2016/3/15
3	المحرّك	ENG-0161	‫$330.00	2	الشمال	Jessie	2016/7/2
4	العجلة	W-24	‫$20.50	4	الغرب	Beth	2016/3/1
5	اللوحة	P-034	‫6.00 دولار أمريكي	4	الشمال	Devyn	2016/3/15
6	اللوحة	P-052	‫$11.50	7	الشرق	إريك	2016/5/16
7	الإطار	FR-0B1	‫$34.00	8	الشرق	Hannah	2016/3/12
8	العجلة	W-24	‫$20.50	11	الجنوب	Sheldon	2016/4/30

معايير الفلتر

يحدّد عنصر FilterCriteria بيانات جدول البيانات التي يتم عرضها أو إخفاؤها في فلتر أساسي أو عرض فلتر. يعتمد كل معيار على القيم في عمود معيّن. يمكنك تقديم معايير الفلتر كخريطة تكون فيها المفاتيح هي فهارس الأعمدة والقيم هي المعايير.

بالنسبة إلى المعايير المحدّدة باستخدام منطقي condition، يجب أن تكون الحالة true لعرض القيم. لا تلغي الحالة override hiddenValues. إذا تم إدراج قيمة ضمن hiddenValues، سيظل يتم إخفاء جميع التطابقات لقيمة.

تعرض عينة تعليمات برمجية التالية خريطة لمعايير الفلتر:

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

عند تطبيق هذه المعايير على بيانات المبيعات النموذجية، لا يتم عرض سوى الصفوف التي لا تكون فيها قيمة عمود "فئة العنصر" هي "اللوحة"، والتي تكون فيها قيمة عمود "تاريخ الشحن" قبل "30 أبريل 2016".

الجدول 3. بيانات المبيعات باستخدام معايير الفلتر

	A	ب	C	D	ج	ح	G
1	فئة العنصر	رقم الطراز	التكلفة	الكمية	المنطقة	مندوب مبيعات	تاريخ الشحن
2	العجلة	W-24	‫$20.50	4	الغرب	Beth	2016/3/1
3	الباب	D-01X	‫$15.00	2	الجنوب	Amir	2016/3/15
4	الإطار	FR-0B1	‫$34.00	8	الشرق	Hannah	2016/3/12

عينة تعليمات برمجية لعرض الفلتر

تعرض عيّنة الرمز البرمجي التالية كيفية إنشاء عرض فلتر وتكراره، ثم تعديل النسخة المكرّرة باستخدام بيانات المبيعات النموذجية.

جافا

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

عرض على 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

عرض على GitHub

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

مواضيع ذات صلة

• تطبيق الفلاتر على بيانات "جداول بيانات Google"
• قراءة البيانات الوصفية وكتابتها والبحث عنها