Class Filter

فلتر

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

إذا لم يكن هناك فلتر في جدول البيانات حتى الآن، أنشئ فلترًا باستخدام Range.createFilter().

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

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

إزالة أحد الفلاتر

يحصل العيّنة أدناه على الفلتر في الورقة النشطة ويزيله.

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

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

يحصل العيّنة أدناه على الفلتر في الورقة النشطة، ثم يستخدم الطريقة getRange() من هذه الفئة لتسجيل النطاق الذي ينطبق عليه الفلتر.

const ss = SpreadsheetApp.getActiveSheet();
// Gets the existing filter on the active sheet.
const 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.

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

المعلمات

الاسم	النوع	الوصف
columnPosition	Integer	موضع العمود الذي يستند إلى الفهرس 1. على سبيل المثال، الفهرس الخاص بالعمود "ب" هو 2.

الإرجاع

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

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

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

---

getRange()

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

// Gets the existing filter on the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
const 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.
const ss = SpreadsheetApp.getActiveSheet();
const 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.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.removeColumnFilterCriteria(2);

المعلمات

الاسم	النوع	الوصف
columnPosition	Integer	موضع العمود الذي يستند إلى الفهرس 1. على سبيل المثال، الفهرس الخاص بالعمود "ب" هو 2.

الإرجاع

Filter: الفلتر لتسلسل الطلبات.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

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

---

setColumnFilterCriteria(columnPosition, filterCriteria)

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

const ss = SpreadsheetApp.getActiveSheet();
const 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);

المعلمات

الاسم	النوع	الوصف
columnPosition	Integer	موضع العمود الذي يستند إلى الفهرس 1. على سبيل المثال، الفهرس الخاص بالعمود "ب" هو 2.
filterCriteria	FilterCriteria	معايير الفلتر المطلوب ضبطها في حال ضبط المعايير على 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.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.sort(2, true);

المعلمات

الاسم	النوع	الوصف
columnPosition	Integer	موضع العمود الذي يستند إلى الفهرس 1. على سبيل المثال، الفهرس الخاص بالعمود "ب" هو 2.
ascending	Boolean	إذا كان true، يتم ترتيب النطاق الذي تمّت فلترته تصاعديًا. وإذا كان false، يتم ترتيب النطاق الذي تمّت فلترته تنازليًا.

الإرجاع

Filter: الفلتر لتسلسل الطلبات.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

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