فیلترها

فیلترها به شما امکان می‌دهند داده‌هایی را که هنگام مشاهده یک صفحه گسترده می‌بینید، مرتب‌سازی و فیلتر کنید. فیلترها مقادیر داده‌ها را در صفحه گسترده شما تغییر نمی‌دهند. می‌توانید از فیلترها برای مخفی کردن یا مرتب‌سازی موقت اطلاعات استفاده کنید. داده‌هایی که با معیارهای فیلتر مشخص شده مطابقت دارند، در حالی که فیلتر فعال است، ظاهر نمی‌شوند. با استفاده از نماهای فیلتر ، می‌توانید فیلترهای با نام‌های مختلف را نیز ذخیره کنید و هر زمان که دوست داشتید بین آنها جابجا شوید.

در ادامه چند نمونه از کاربردهای فیلترها آمده است:

  • مرتب‌سازی داده‌ها بر اساس یک ستون خاص. برای مثال، مرتب‌سازی رکوردهای کاربر بر اساس نام خانوادگی.
  • داده‌هایی را که شرایط خاصی را برآورده می‌کنند، پنهان کنید. برای مثال، تمام رکوردهای قدیمی‌تر از ۲ سال را پنهان کنید.
  • داده‌هایی را که با یک مقدار خاص مطابقت دارند پنهان کنید. برای مثال، تمام مسائلی را که وضعیت آنها "بسته" است، پنهان کنید.

فیلتر پایه

فیلتر BasicFilter برای یک صفحه گسترده، فیلتر پیش‌فرضی است که هر زمان کسی صفحه گسترده را مشاهده می‌کند، اعمال می‌شود. یک صفحه گسترده می‌تواند یک فیلتر پایه در هر برگه داشته باشد. می‌توانید با پاک کردن فیلتر پایه، آن را غیرفعال کنید. این کار فیلتر و تمام تنظیمات آن را از صفحه گسترده حذف می‌کند. اگر می‌خواهید همان فیلتر را دوباره فعال کنید، باید معیارها را دوباره تنظیم کنید.

مدیریت فیلتر پایه

برای تنظیم یا پاک کردن فیلتر پایه، از متد spreadsheets.batchUpdate با نوع درخواست مناسب استفاده کنید:

برای فهرست کردن فیلتر پایه، از متد spreadsheets.get استفاده کنید و پارامتر URL fields را روی sheets/basicFilter تنظیم کنید. نمونه کد spreadsheets.get زیر یک URL گوگل شیت را با یک ماسک فیلد نشان می‌دهد: 

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

فیلتر کردن نماها

یک FilterView یک فیلتر نام‌گذاری شده است که می‌توانید هر زمان که دوست دارید آن را خاموش و روشن کنید. یک صفحه گسترده می‌تواند چندین نمای فیلتر داشته باشد، اما شما فقط می‌توانید یکی را در یک زمان اعمال کنید.

در زیر چند نمونه از موارد استفاده برای نمایش فیلترها آمده است:

  • شما چندین فیلتر مختلف دارید که می‌خواهید هنگام مشاهده داده‌ها بین آنها جابجا شوید.
  • شما دسترسی ویرایش به یک صفحه گسترده را ندارید اما همچنان می‌خواهید فیلتر اعمال کنید. در این حالت، می‌توانید یک نمای فیلتر موقت ایجاد کنید که فقط برای شما قابل مشاهده باشد.

  • شما می‌خواهید هر شخصی که صفحه گسترده خود را با او به اشتراک می‌گذارید، داده‌ها را به طور متفاوتی مشاهده کند. می‌توانید با ارائه spreadsheetId و filterViewId در URL صفحه گسترده، نمای فیلتری را که می‌خواهید اعمال کنید، مشخص کنید. برای انجام این کار، هنگام ایجاد نمای فیلتر، از filterViewId برگردانده شده در پاسخ استفاده کنید.

    نمونه کد زیر یک URL گوگل شیت را با نمای فیلتر نشان می‌دهد:

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

مدیریت نمایش فیلترها

برای ایجاد، کپی کردن، تغییر یا حذف نماهای فیلتر، از متد spreadsheets.batchUpdate با نوع درخواست مناسب استفاده کنید:

  • برای ایجاد یک نمای فیلتر، از متد AddFilterViewRequest استفاده کنید.
  • برای ایجاد یک کپی از یک نمای فیلتر، از متد DuplicateFilterViewRequest استفاده کنید.
  • برای تغییر ویژگی‌های یک نمای فیلتر، از متد UpdateFilterViewRequest استفاده کنید.
  • برای حذف یک فیلتر ویو، از متد DeleteFilterViewRequest استفاده کنید.

برای فهرست کردن تمام فیلترهای view، از متد spreadsheets.get استفاده کنید و پارامتر URL fields را روی sheets/filterViews تنظیم کنید. نمونه کد spreadsheets.get زیر یک URL گوگل شیت را با یک ماسک فیلد نشان می‌دهد: 

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. مثال داده‌های فروش
الف ب سی دی ای ف جی
۱ دسته بندی کالا شماره مدل هزینه مقدار منطقه فروشنده تاریخ ارسال
۲ چرخ W-24 ۲۰.۵۰ دلار ۴ غرب بث ۱/۳/۲۰۱۶
۳ درب D-01X ۱۵٫۰۰ دلار ۲ جنوب امیر ۱۵/۳/۲۰۱۶
۴ قاب FR-0B1 ۳۴٫۰۰ دلار ۸ شرق هانا ۳/۱۲/۲۰۱۶
۵ پنل پ-034 ۶٫۰۰ دلار ۴ شمال دوین ۱۵/۳/۲۰۱۶
۶ پنل پ-۰۵۲ ۱۱.۵۰ دلار ۷ شرق اریک ۱۶/۵/۲۰۱۶
۷ چرخ W-24 ۲۰.۵۰ دلار ۱۱ جنوب شلدون ۳۰/۴/۲۰۱۶
۸ موتور ENG-0161 ۳۳۰٫۰۰ دلار ۲ شمال جسی ۷/۲/۲۰۱۶

مرتب سازی مشخصات

یک فیلتر می‌تواند چندین مشخصه مرتب‌سازی داشته باشد. این مشخصه‌ها نحوه مرتب‌سازی داده‌ها را تعیین می‌کنند و به ترتیب مشخص‌شده اعمال می‌شوند. ویژگی SortSpec.dimensionIndex اندیس ستونی را که مرتب‌سازی باید روی آن اعمال شود، مشخص می‌کند.

نمونه کد زیر مشخصات مرتب‌سازی را نشان می‌دهد:

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

وقتی این مشخصه روی داده‌های فروش مثال اعمال شود، ابتدا بر اساس «مقدار» و سپس، اگر دو ردیف مقدار یکسانی داشته باشند، بر اساس «تاریخ ارسال» مرتب‌سازی می‌شود.

جدول ۲. داده‌های فروش مرتب‌شده بر اساس ۲ ستون
الف ب سی دی ای ف جی
۱ دسته بندی کالا شماره مدل هزینه مقدار منطقه فروشنده تاریخ ارسال
۲ درب D-01X ۱۵٫۰۰ دلار ۲ جنوب امیر ۱۵/۳/۲۰۱۶
۳ موتور ENG-0161 ۳۳۰٫۰۰ دلار ۲ شمال جسی ۷/۲/۲۰۱۶
۴ چرخ W-24 ۲۰.۵۰ دلار ۴ غرب بث ۱/۳/۲۰۱۶
۵ پنل پ-034 ۶٫۰۰ دلار ۴ شمال دوین ۱۵/۳/۲۰۱۶
۶ پنل پ-۰۵۲ ۱۱.۵۰ دلار ۷ شرق اریک ۱۶/۵/۲۰۱۶
۷ قاب FR-0B1 ۳۴٫۰۰ دلار ۸ شرق هانا ۳/۱۲/۲۰۱۶
۸ چرخ W-24 ۲۰.۵۰ دلار ۱۱ جنوب شلدون ۳۰/۴/۲۰۱۶

معیارهای فیلتر

متد FilterCriteria تعیین می‌کند که چه داده‌های صفحه‌گسترده در یک فیلتر یا نمای فیلتر پایه نمایش داده شوند یا پنهان شوند. هر معیار به مقادیر موجود در یک ستون خاص بستگی دارد. شما معیارهای فیلتر را به عنوان یک نقشه ارائه می‌دهید که در آن کلیدها، شاخص‌های ستون و مقادیر، معیارها هستند.

برای معیارهایی که با استفاده از یک condition بولی مشخص می‌شوند، شرط باید True باشد تا مقادیر نمایش داده شوند. این شرط، hiddenValues لغو نمی‌کند. اگر مقداری در زیر hiddenValues ​​فهرست شده باشد، تمام تطابق‌های آن مقدار همچنان پنهان هستند.

نمونه کد زیر یک نقشه معیارهای فیلتر را نشان می‌دهد:

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

وقتی این معیار روی داده‌های فروش مثال اعمال شود، فقط ردیف‌هایی را نشان می‌دهد که در آن‌ها «رده کالا» برابر با «پنل» نباشد و «تاریخ ارسال» قبل از ۳۰ آوریل ۲۰۱۶ باشد.

جدول ۳. داده‌های فروش با استفاده از معیارهای فیلتر
الف ب سی دی ای ف جی
۱ دسته بندی کالا شماره مدل هزینه مقدار منطقه فروشنده تاریخ ارسال
۲ چرخ W-24 ۲۰.۵۰ دلار ۴ غرب بث ۱/۳/۲۰۱۶
۳ درب D-01X ۱۵٫۰۰ دلار ۲ جنوب امیر ۱۵/۳/۲۰۱۶
۴ قاب FR-0B1 ۳۴٫۰۰ دلار ۸ شرق هانا ۳/۱۲/۲۰۱۶

نمونه

نمونه کد زیر نحوه ایجاد یک نمای فیلتر، کپی کردن آن و سپس به‌روزرسانی نسخه کپی‌شده با استفاده از داده‌های فروش مثال بالا را نشان می‌دهد.

پایتون

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