Class Selection

الاختيار

الوصول إلى التحديد النشط الحالي في ورقة البيانات النشطة التحديد هو مجموعة الخلايا التي ميّزها المستخدم في ورقة البيانات، ويمكن أن تكون نطاقات غير متجاورة. تُعد إحدى الخلايا في التحديد هي الخلية الحالية، حيث يركّز المستخدم حاليًا، ويتم تمييزها بحدود داكنة في واجهة مستخدم "جداول بيانات Google".

const activeSheet = SpreadsheetApp.getActiveSheet();
const rangeList = activeSheet.getRangeList(['A1:B4', 'D1:E4']);
rangeList.activate();

const selection = activeSheet.getSelection();
// Current Cell: D1
console.log(`Current Cell: ${selection.getCurrentCell().getA1Notation()}`);
// Active Range: D1:E4
console.log(`Active Range: ${selection.getActiveRange().getA1Notation()}`);
// Active Ranges: A1:B4, D1:E4
const ranges = selection.getActiveRangeList().getRanges();
for (let i = 0; i < ranges.length; i++) {
  console.log(`Active Ranges: ${ranges[i].getA1Notation()}`);
}
console.log(`Active Sheet: ${selection.getActiveSheet().getName()}`);

الطُرق

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
getActiveRange()	Range|null	تعرض هذه الدالة النطاق المحدّد في الورقة النشطة، أو null إذا لم يكن هناك نطاق نشط.
getActiveRangeList()	RangeList|null	تعرض هذه الدالة قائمة بالنطاقات النشطة في ورقة البيانات النشطة أو null إذا لم تكن هناك نطاقات نشطة.
getActiveSheet()	Sheet	تعرض هذه الدالة الورقة النشطة في جدول البيانات.
getCurrentCell()	Range|null	تعرض هذه الدالة الخلية الحالية (المميّزة) المحدّدة في أحد النطاقات النشطة أو null إذا لم تكن هناك خلية حالية.
getNextDataRange(direction)	Range|null	بدءًا من current cell وactive range والتحرّك في الاتجاه المحدّد، تعرض هذه الدالة نطاقًا معدَّلاً تم فيه نقل الحافة المناسبة للنطاق لتغطية next data cell مع الحفاظ على تغطية الخلية الحالية.

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

getActiveRange()

تعرض هذه الدالة النطاق المحدّد في الورقة النشطة، أو null إذا لم يكن هناك نطاق نشط. إذا تم تحديد نطاقات متعددة، لن تعرض هذه الطريقة سوى النطاق الأخير الذي تم تحديده.

const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
const activeRange = selection.getActiveRange();

الإرجاع

‫Range|null: النطاق النشط

التفويض

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

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

---

getActiveRangeList()

تعرض هذه الدالة قائمة بالنطاقات النشطة في ورقة البيانات النشطة أو null إذا لم تكن هناك نطاقات نشطة.

إذا تم اختيار نطاق واحد، سيتصرف هذا النطاق كطلب getActiveRange().

const sheet = SpreadsheetApp.getActiveSheet();
// Returns the list of active ranges.
const activeRangeList = sheet.getActiveRangeList();

الإرجاع

RangeList|null: قائمة النطاقات النشطة

التفويض

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

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

---

getActiveSheet()

تعرض هذه الدالة الورقة النشطة في جدول البيانات.

const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
const activeSheet = selection.getActiveSheet();

الإرجاع

Sheet: الورقة النشطة في جدول البيانات

التفويض

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

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

---

getCurrentCell()

تعرض هذه الدالة الخلية الحالية (المميّزة) المحدّدة في أحد النطاقات النشطة أو null إذا لم تكن هناك خلية حالية.

const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
// Returns the current highlighted cell in the one of the active ranges.
const currentCell = selection.getCurrentCell();

الإرجاع

Range|null: الخلية الحالية

التفويض

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

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

---

getNextDataRange(direction)

بدءًا من current cell وactive range والتحرّك في الاتجاه المحدّد، تعرض هذه الدالة نطاقًا معدَّلاً تم فيه نقل الحافة المناسبة للنطاق لتغطية next data cell مع الحفاظ على تغطية الخلية الحالية. إذا كان النطاق النشط غير محدود على طول dimension من الاتجاه، يتم عرض النطاق النشط الأصلي. إذا لم تكن هناك خلية حالية أو نطاق نشط، سيتم عرض null. وهذا الإجراء مكافئ لاختيار نطاق في المحرّر والضغط على Ctrl+Shift+[arrow key].

// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Makes C3 the current cell and C3:E5 the active range.
sheet.getRange('C3:E5').activate();
// Logs 'C1:E3'
console.log(
    SpreadsheetApp.getSelection()
        .getNextDataRange(SpreadsheetApp.Direction.UP)
        .getA1Notation(),
);

المَعلمات

الاسم	النوع	الوصف
direction	Direction	الاتجاه الذي سيتم فيه البحث عن خلية حافة منطقة البيانات التالية.

الإرجاع

Range|null — النطاق المعدَّل الذي يتضمّن خلية البيانات، أو null إذا لم يكن هناك أي تحديد.

التفويض

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

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