Class Filter

الفلتر

استخدِم هذه الفئة لتعديل الفلاتر الحالية على أوراق بيانات Grid، وهي النوع التلقائي من جداول البيانات. أوراق الشبكة هي أوراق بيانات عادية تتضمن بيانات غير مرتبطة بقاعدة بيانات.

في حال عدم توفّر فلتر في الورقة حتى الآن، يمكنك إنشاء فلتر باستخدام Range.createFilter().

لاستخدام هذا الصف، يجب أولاً الوصول إلى فلتر ورقة الشبكة باستخدام Range.getFilter() أو Sheet.getFilter().

طرق الاستخدام الشائعة

إزالة فلتر

يحصل النموذج التالي على الفلتر في الورقة النشطة ويزيله.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Removes the filter from the active sheet.
filter.remove();

الحصول على النطاق الذي ينطبق عليه الفلتر

يحصل النموذج التالي على الفلتر في ورقة البيانات النشطة، ثم يستخدم طريقة getRange() من هذه الفئة لتسجيل النطاق الذي ينطبق عليه الفلتر.
let ss = SpreadsheetApp.getActiveSheet();
// Gets the existing filter on the active sheet.
let filter = ss.getFilter();
// Logs the range that the filter applies to in A1 notation.
console.log(filter.getRange().getA1Notation());

الطُرق

الطريقةنوع الإرجاعوصف قصير
getColumnFilterCriteria(columnPosition)FilterCriteriaتحصل هذه السياسة على معايير الفلتر في العمود المحدّد، أو null إذا لم يتم تطبيق معايير الفلتر عليه.
getRange()Rangeالحصول على النطاق الذي ينطبق عليه هذا الفلتر
remove()voidيزيل هذا الفلتر.
removeColumnFilterCriteria(columnPosition)Filterيزيل معايير الفلتر من العمود المحدد.
setColumnFilterCriteria(columnPosition, filterCriteria)Filterلضبط معايير الفلتر في العمود المحدد.
sort(columnPosition, ascending)Filterيتم ترتيب النطاق الذي تمت فلترته حسب العمود المحدّد، باستثناء الصف الأول (صف العنوان) في النطاق الذي ينطبق عليه هذا الفلتر.

المستندات التفصيلية

getColumnFilterCriteria(columnPosition)

تحصل هذه السياسة على معايير الفلتر في العمود المحدّد، أو null إذا لم يتم تطبيق معايير الفلتر عليه.

للاطّلاع على مزيد من التفاصيل حول معايير الفلاتر، عليك ربط هذه الطريقة بطرق من الصف FilterCriteria.

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
  // Gets the filter criteria applied to column B of the active sheet
  // and logs the hidden values.
let filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
console.log(filterCriteria);

المعلّمات

الاسمالنوعالوصف
columnPositionIntegerالموضع الذي تمت فهرسته في العمود. على سبيل المثال، فهرس العمود B' 2.

تذكرة ذهاب وعودة

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

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRange()

الحصول على النطاق الذي ينطبق عليه هذا الفلتر

// Gets the existing filter on the active sheet.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Logs the range that the filter applies to in A1 notation.
console.log(filter.getRange().getA1Notation());

تذكرة ذهاب وعودة

Range — نطاق الفلتر للحصول على النطاق في تدوين A1، عليك ربط هذه الطريقة بـ Range.getA1Notation().

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

remove()

يزيل هذا الفلتر.

// Removes the filter from the active sheet.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
filter.remove();

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeColumnFilterCriteria(columnPosition)

يزيل معايير الفلتر من العمود المحدد.

// Removes the filter criteria from column B.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
filter.removeColumnFilterCriteria(2);

المعلّمات

الاسمالنوعالوصف
columnPositionIntegerالموضع الذي تمت فهرسته في العمود. على سبيل المثال، فهرس العمود B' 2.

تذكرة ذهاب وعودة

Filter — الفلتر هو للسلاسل.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setColumnFilterCriteria(columnPosition, filterCriteria)

لضبط معايير الفلتر في العمود المحدد. أولاً، أنشئ أداة إنشاء معايير الفلاتر باستخدام SpreadsheetApp.newFilterCriteria(). ويمكنك بعد ذلك إضافة معايير إلى أداة الإنشاء باستخدام الصف FilterCriteriaBuilder. بعد إنشاء المعايير، عليك ضبطها على أنها المعلَمة filterCriteria لهذه الطريقة.

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Builds the filter criteria to use as a parameter for setColumnFilterCriteria.
const criteria = SpreadsheetApp.newFilterCriteria()
                             .setHiddenValues(["Hello", "World"])
                             .build();
// Sets the filter criteria for column C.
filter.setColumnFilterCriteria(3, criteria);

المعلّمات

الاسمالنوعالوصف
columnPositionIntegerالموضع الذي تمت فهرسته في العمود. على سبيل المثال، فهرس العمود B' 2.
filterCriteriaFilterCriteriaمعايير الفلتر التي يجب ضبطها. وفي حال ضبط المعايير على null، ستتم إزالة معايير الفلتر من العمود المحدّد. ويمكنك أيضًا استخدام removeColumnFilterCriteria(columnPosition).

تذكرة ذهاب وعودة

Filter — الفلتر هو للسلاسل.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

sort(columnPosition, ascending)

يتم ترتيب النطاق الذي تمت فلترته حسب العمود المحدّد، باستثناء الصف الأول (صف العنوان) في النطاق الذي ينطبق عليه هذا الفلتر.

// Gets the existing filter and sorts it by column B in ascending order.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
filter.sort(2, true);

المعلّمات

الاسمالنوعالوصف
columnPositionIntegerالموضع الذي تمت فهرسته في العمود. على سبيل المثال، فهرس العمود B' 2.
ascendingBooleanفي حال true، يرتّب النطاق الذي تمت فلترته تصاعديًا. وإذا كانت false، ترتّب النطاق الذي تمت فلترته بالترتيب التنازلي.

تذكرة ذهاب وعودة

Filter — الفلتر هو للسلاسل.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة تفويضًا مع واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets