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(),
);

المعلمات

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

الإرجاع

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

التفويض

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

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