فیلترها

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

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

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

فیلتر اصلی

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

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

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

برای فهرست کردن فیلتر اصلی، از روش spreadsheets.get استفاده کنید و پارامتر URL fields را روی sheets/basicFilter تنظیم کنید. نمونه کد spreadsheets.get زیر نشانی اینترنتی کاربرگ‌نگار 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 زیر نشانی اینترنتی کاربرگ‌نگار 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. داده های فروش نمونه
الف ب سی D E اف جی
1 دسته بندی آیتم شماره مدل هزینه مقدار منطقه فروشنده تاریخ ارسال
2 چرخ W-24 20.50 دلار 4 غرب بث 3/1/2016
3 درب D-01X 15.00 دلار 2 جنوب امیر 1395/3/15
4 قاب FR-0B1 34.00 دلار 8 شرق هانا 3/12/2016
5 پانل P-034 6.00 دلار 4 شمال دوین 1395/3/15
6 پانل P-052 11.50 دلار 7 شرق اریک 1395/5/16
7 چرخ W-24 20.50 دلار 11 جنوب شلدون 30/4/2016
8 موتور ENG-0161 330.00 دلار 2 شمال جسی 7/2/2016

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

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

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

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

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

جدول 2. داده های فروش بر اساس 2 ستون مرتب شده اند
الف ب سی D E اف جی
1 دسته بندی آیتم شماره مدل هزینه مقدار منطقه فروشنده تاریخ ارسال
2 درب D-01X 15.00 دلار 2 جنوب امیر 1395/3/15
3 موتور ENG-0161 330.00 دلار 2 شمال جسی 7/2/2016
4 چرخ W-24 20.50 دلار 4 غرب بث 3/1/2016
5 پانل P-034 6.00 دلار 4 شمال دوین 1395/3/15
6 پانل P-052 11.50 دلار 7 شرق اریک 1395/5/16
7 قاب FR-0B1 34.00 دلار 8 شرق هانا 3/12/2016
8 چرخ W-24 20.50 دلار 11 جنوب شلدون 30/4/2016

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

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

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

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

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

وقتی این معیار برای نمونه داده‌های فروش اعمال می‌شود، فقط ردیف‌هایی را نشان می‌دهد که «رده کالا» «پانل» نیست و «تاریخ ارسال» قبل از 30 آوریل 2016 است.

جدول 3. داده های فروش با استفاده از معیارهای فیلتر
الف ب سی D E اف جی
1 دسته بندی آیتم شماره مدل هزینه مقدار منطقه فروشنده تاریخ ارسال
2 چرخ W-24 20.50 دلار 4 غرب بث 3/1/2016
3 درب D-01X 15.00 دلار 2 جنوب امیر 1395/3/15
4 قاب FR-0B1 34.00 دلار 8 شرق هانا 3/12/2016

نمونه

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

پایتون

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