الفلاتر

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

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

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

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

رمز 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 الغرب هبة 1/3/2016
3 باب D-01X $15.00 2 الجنوب أمير 3/15/2016
4 إطار FR-0B1 34.00 دولار أمريكي 8 الشرق هناء 3/12/2016
5 لوحة P-034 ‫6.00 دولار أمريكي 4 الشمال Devyn 3/15/2016
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 الشمال هبة 2/7/2016

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

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

يعرض نموذج الرمز البرمجي التالي مواصفات الترتيب:

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

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

الجدول 2: بيانات المبيعات مرتبة حسب عمودَين
A ب C D ج ح G
1 فئة العنصر رقم الطراز التكلفة الكمية المنطقة مندوب مبيعات تاريخ الشحن
2 باب D-01X $15.00 2 الجنوب أمير 3/15/2016
3 المحرك ENG-0161 330.00 دولار أمريكي 2 الشمال هبة 2/7/2016
4 العجلة W-24 20.50 دولار أمريكي 4 الغرب هبة 1/3/2016
5 لوحة P-034 ‫6.00 دولار أمريكي 4 الشمال Devyn 3/15/2016
6 لوحة P-052 11.50 دولار أمريكي 7 الشرق إريك 2016/5/16
7 إطار FR-0B1 34.00 دولار أمريكي 8 الشرق هناء 3/12/2016
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 الغرب هبة 1/3/2016
3 باب D-01X $15.00 2 الجنوب أمير 3/15/2016
4 إطار FR-0B1 34.00 دولار أمريكي 8 الشرق هناء 3/12/2016

عيّنة

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

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