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

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

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

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

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

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

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

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

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

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

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

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

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

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

عروض الفلاتر

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 وضَع مَعلمة عنوان URL fields على القيمة 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	الجنوب	أمير	2016/3/15
4	إطار	FR-0B1	$34.00	8	الشرق	هانا	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	الجنوب	أمير	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	الشرق	هانا	2016/3/12
8	العجلة	W-24	$20.50	11	الجنوب	Sheldon	2016/4/30

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

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

بالنسبة إلى المعايير المحدّدة باستخدام قيمة منطقية condition، يجب أن تكون الحالة true ليتم عرض القيم. لا يتجاوز الشرط 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	الجنوب	أمير	2016/3/15
4	إطار	FR-0B1	$34.00	8	الشرق	هانا	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"
• قراءة البيانات الوصفية وكتابتها والبحث فيها