الفلاتر

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

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

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

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

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

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

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

لعرض الفلتر الأساسي، استخدِم طريقة 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 مع نوع الطلب المناسب:

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

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

تمثيل الفلتر

يعرض نموذج الرمز البرمجي التالي تمثيل 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

عيّنة

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

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