مدیریت قابلیت مشاهده داده‌ها با فیلترها

این سند در مورد استفاده از فیلترها برای مرتب‌سازی و فیلتر کردن داده‌های نمایش داده شده در یک صفحه گسترده است.

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

برای فیلتر کردن داده‌های برگردانده شده در یک درخواست API گوگل شیت، از شیء DataFilter استفاده کنید. برای اطلاعات بیشتر، به بخش خواندن، نوشتن و جستجوی فراداده مراجعه کنید.

موارد استفاده از فیلتر

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

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

فیلتر پایه

شیء 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 از Sheets را با نمای فیلتر نشان می‌دهد:

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

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

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

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

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

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

نمایش JSON یک فیلتر

نمونه کد زیر نمایش 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'
      }
    }
  }
}

وقتی این معیار روی داده‌های فروش نمونه اعمال شود، فقط ردیف‌هایی را نشان می‌دهد که مقدار ستون «رده کالا» برابر با «پانل» نباشد و مقدار ستون «تاریخ ارسال» قبل از «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")