الفلاتر

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الجدول 3. بيانات المبيعات باستخدام معايير الفلتر
A B C D ج ح G
1 فئة العنصر رقم الطراز التكلفة العدد منطقة مندوب مبيعات تاريخ الشحن
2 العجلة W-24 SAR 20.50 4 الغرب بيث 1/3/2016
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")