Class SpreadsheetApp

تنشئ جدول بيانات جديدًا بالاسم الذي تم تقديمه.

// The code below creates a new spreadsheet "Finances" and logs the URL for it
var ssNew = SpreadsheetApp.create("Finances");
Logger.log(ssNew.getUrl());

المعلّمات

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

Spreadsheet - جدول بيانات جديد

التفويض

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

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

يتم إنشاء جدول بيانات جديد باستخدام الاسم المحدّد والعدد المحدّد من الصفوف والأعمدة.

// The code below creates a new spreadsheet "Finances" with 50 rows and 5 columns and logs the
// URL for it
var ssNew = SpreadsheetApp.create("Finances", 50, 5);
Logger.log(ssNew.getUrl());

المعلّمات

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

Spreadsheet - جدول بيانات جديد

التفويض

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

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

تتيح هذه السياسة تفعيل تنفيذ البيانات لجميع أنواع مصادر البيانات.

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

التفويض

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

• https://www.googleapis.com/auth/bigquery.readonly

تعمل هذه السياسة على تفعيل تنفيذ البيانات لمصدر بيانات BigQuery.

يؤدي تنفيذ بيانات مصدر BigQuery إلى استثناء إذا لم يتم التفعيل.

التفويض

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

• https://www.googleapis.com/auth/bigquery.readonly

تطبيق جميع تغييرات جداول البيانات المعلّقة.

في بعض الأحيان، يتم تجميع عمليات جداول البيانات معًا لتحسين الأداء، على سبيل المثال عند إجراء استدعاءات متعددة للنطاق Range.getValue(). ومع ذلك، قد تحتاج في بعض الأحيان إلى التأكد من إجراء جميع التغييرات المعلّقة على الفور، مثلاً لعرض بيانات المستخدمين أثناء تنفيذ نص برمجي.

// The code below changes the background color of cells A1 and B1 twenty times. You should be
// able to see the updates live in the spreadsheet. If flush() is not called, the updates may
// be applied live or may all be applied at once when the script completes.
function colors() {
  var sheet = SpreadsheetApp.getActiveSheet();
  for (var i = 0; i < 20; i++) {
    if ((i % 2) == 0) {
      sheet.getRange('A1').setBackground('green');
      sheet.getRange('B1').setBackground('red');
    } else {
      sheet.getRange('A1').setBackground('red');
      sheet.getRange('B1').setBackground('green');
    }
    SpreadsheetApp.flush();
  }
}

عرض جدول البيانات النشط حاليًا، أو null إذا لم يكن هناك جدول بيانات.

يمكن أن تحصل الدوال التي يتم تنفيذها في سياق جدول البيانات على مرجع إلى كائن جدول البيانات المقابل من خلال استدعاء هذه الدالة.

// The code below logs the URL for the active spreadsheet.
Logger.log(SpreadsheetApp.getActive().getUrl());

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

Spreadsheet - عنصر جدول بيانات نشط

التفويض

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

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

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

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

// The code below logs the background color for the active range.
var colorObject = SpreadsheetApp.getActiveRange().getBackgroundObject();
// Assume the color has ColorType.RGB.
Logger.log(colorObject.asRgbColor().asHexString());

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

Range — النطاق النشط.

التفويض

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

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

لعرض قائمة النطاقات النشطة في ورقة البيانات النشطة أو null إذا لم يتم اختيار أي نطاقات. ويتم وضع النطاق النشط الذي يحتوي على الخلية المميّزة الحالية في آخر قائمة.

إذا تم تحديد نطاق واحد، يكون هذا الإجراء عبارة عن مكالمة getActiveRange().

// Returns the list of active ranges.
var rangeList = SpreadsheetApp.getActiveRangeList();

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

RangeList — قائمة النطاقات النشطة

التفويض

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

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

الحصول على الورقة النشطة في جدول بيانات.

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

// The code below logs the name of the active sheet.
Logger.log(SpreadsheetApp.getActiveSheet().getName());

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

Sheet - عنصر جدول بيانات نشط

التفويض

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

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

عرض جدول البيانات النشط حاليًا، أو null إذا لم يكن هناك جدول بيانات.

يمكن أن تحصل الدوال التي يتم تنفيذها في سياق جدول بيانات على مرجع إلى العنصر Spreadsheet المقابل عن طريق استدعاء هذه الدالة.

// The code below logs the URL for the active spreadsheet.
Logger.log(SpreadsheetApp.getActiveSpreadsheet().getUrl());

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

Spreadsheet - عنصر جدول بيانات نشط

التفويض

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

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

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

// Returns the current highlighted cell in the one of the active ranges.
var currentCell = SpreadsheetApp.getCurrentCell();

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

Range — الخلية الحالية

التفويض

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

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

لعرض Selection الحالية في جدول البيانات.

var selection = SpreadsheetApp.getSelection();
var currentCell = selection.getCurrentCell();

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

Selection — الاختيار الحالي

التفويض

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

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

تعرض نسخة من بيئة واجهة المستخدم في جدول البيانات&#39؛ التي تسمح للنص البرمجي بإضافة ميزات مثل القوائم ومربعات الحوار والأشرطة الجانبية. لا يمكن للنص البرمجي التفاعل إلا مع واجهة المستخدم للمثيل الحالي لجدول بيانات مفتوح، وذلك فقط إذا كان النص البرمجي مرتبطًا بجدول البيانات. لمزيد من المعلومات، راجِع الأدلة الخاصة بالقوائم ومربّعات الحوار والأشرطة الجانبية.

// Add a custom menu to the active spreadsheet, including a separator and a sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu')
          .addItem('One sub-menu item', 'mySecondFunction')
          .addItem('Another sub-menu item', 'myThirdFunction'))
      .addToUi();
}

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

Ui: نسخة من بيئة واجهة المستخدم هذه لجدول البيانات هذا.

تنشئ أداة إنشاء CellImage.

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

CellImageBuilder — أداة الإنشاء الجديدة.

تنشئ أداة إنشاء Color.

var rgbColor = SpreadsheetApp.newColor().setRgbColor("#FF0000").build();

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

ColorBuilder — أداة الإنشاء الجديدة.

إنشاء أداة إنشاء لقاعدة تنسيق شرطي.

// Adds a conditional format rule to a sheet that causes all cells in range A1:B3 to turn red
// if they contain a number between 1 and 10.
var sheet = SpreadsheetApp.getActive().getActiveSheet();
var range = sheet.getRange('A1:B3');
var rule = SpreadsheetApp.newConditionalFormatRule()
    .whenNumberBetween(1, 10)
    .setBackground("#FF0000")
    .setRanges([range])
    .build()
var rules = sheet.getConditionalFormatRules();
rules.push(rule);
sheet.setConditionalFormatRules(rules);

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

ConditionalFormatRuleBuilder — أداة الإنشاء الجديدة.

تنشئ أداة إنشاء DataSourceSpec.

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

DataSourceSpecBuilder — أداة الإنشاء الجديدة.

تُنشئ أداة لإنشاء قاعدة التحقّق من البيانات.

var cell = SpreadsheetApp.getActive().getRange('A1');
var rule = SpreadsheetApp.newDataValidation()
    .requireNumberBetween(1, 100)
    .setAllowInvalid(false)
    .setHelpText('Number must be between 1 and 100.')
    .build();
cell.setDataValidation(rule);

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

DataValidationBuilder — أداة الإنشاء الجديدة.

تنشئ أداة إنشاء FilterCriteria.

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

FilterCriteriaBuilder — أداة الإنشاء الجديدة

يُنشئ أداة إنشاء لقيمة نص منسّق.

// Sets cell A1 to have the text "Hello world", with "Hello" bolded.
var cell = SpreadsheetApp.getActive().getRange('A1');
var bold = SpreadsheetApp.newTextStyle().setBold(true).build();
var value = SpreadsheetApp.newRichTextValue()
    .setText("Hello world")
    .setTextStyle(0, 5, bold)
    .build();
cell.setRichTextValue(value);

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

RichTextValueBuilder — أداة الإنشاء الجديدة.

تنشئ أداة إنشاء لنمط النص.

// Sets range A1:B3 to have red, size 22, bolded, underlined text.
var range = SpreadsheetApp.getActive().getRange('A1:B3');
var style = SpreadsheetApp.newTextStyle()
    .setForegroundColor("red")
    .setFontSize(22)
    .setBold(true)
    .setUnderline(true)
    .build();
range.setTextStyle(style);

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

TextStyleBuilder — أداة الإنشاء الجديدة.

يفتح جدول البيانات الذي يتوافق مع عنصر الملف المحدّد.

// Get any starred spreadsheets from Google Drive, then open the spreadsheets and log the name
// of the first sheet within each spreadsheet.
var files = DriveApp.searchFiles(
    'starred = true and mimeType = "' + MimeType.GOOGLE_SHEETS + '"');
while (files.hasNext()) {
  var spreadsheet = SpreadsheetApp.open(files.next());
  var sheet = spreadsheet.getSheets()[0];
  Logger.log(sheet.getName());
}

المعلّمات

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

Spreadsheet — جدول البيانات

التفويض

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

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

يفتح جدول البيانات باستخدام رقم التعريف المحدد. يمكن استخراج معرّف جدول البيانات من عنوان URL الخاص به. على سبيل المثال، رقم تعريف جدول البيانات في عنوان URL https://docs.google.com/spreadsheets/d/abc1234567/edit#gid=0 هو "abc;2134567".

// The code below opens a spreadsheet using its ID and logs the name for it.
// Note that the spreadsheet is NOT physically opened on the client side.
// It is opened on the server only (for modification by the script).
var ss = SpreadsheetApp.openById("abc1234567");
Logger.log(ss.getName());

المعلّمات

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

Spreadsheet - عنصر جدول البيانات الذي يحمل رقم التعريف المحدد

التفويض

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

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

يفتح جدول البيانات باستخدام عنوان URL المحدد. ينطبق استثناء استثناء على النص البرمجي إذا لم يكن عنوان URL متوفّرًا أو لم يكن لدى المستخدم إذن بالوصول إليه.

// The code below opens a spreadsheet using its id and logs the name for it.
// Note that the spreadsheet is NOT physically opened on the client side.
// It is opened on the server only (for modification by the script).
var ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc1234567/edit');
Logger.log(ss.getName());

المعلّمات

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

Spreadsheet - عنصر جدول البيانات الذي يحمل رقم التعريف المحدد

التفويض

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

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

لضبط النطاق المحدّد على أنه active range، مع تحديد الخلية العلوية اليسرى في النطاق على أنها current cell.

تعرض واجهة مستخدم جدول البيانات ورقة تحتوي على النطاق المحدد وتختار الخلايا المحددة في النطاق المحدد.

// The code below sets range C1:D4 in the first sheet as the active range.
var range = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].getRange('C1:D4');
SpreadsheetApp.setActiveRange(range);

var selection = SpreadsheetApp.getSelection();
// Current cell: C1
var currentCell = selection.getCurrentCell();
// Active Range: C1:D4
var activeRange = selection.getActiveRange();

المعلّمات

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

Range — النطاق النشط الجديد

تُحدِّد هذه السياسة قائمة النطاقات المحدّدة بصفتها active ranges. تم ضبط النطاق الأخير في القائمة على أنه active range.

// The code below sets ranges [D4, B2:C4] in the active sheet as the active ranges.
var rangeList = SpreadsheetApp.getActiveSheet().getRanges(['D4', 'B2:C4']);
SpreadsheetApp.setActiveRangeList(rangeList);

var selection = SpreadsheetApp.getSelection();
// Current cell: B2
var currentCell = selection.getCurrentCell();
// Active range: B2:C4
var activeRange = selection.getActiveRange();
// Active range list: [D4, B2:C4]
var activeRangeList = selection.getActiveRangeList();

المعلّمات

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

RangeList — قائمة النطاقات المختارة مؤخرًا

التفويض

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

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

تعمل على ضبط الورقة النشطة في جدول بيانات. تعرض واجهة مستخدم "جداول بيانات Google" ورقة البيانات التي تم اختيارها، ما لم تكن الورقة تنتمي إلى جدول بيانات مختلف.

// The code below makes the 2nd sheet active in the active spreadsheet.
var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
SpreadsheetApp.setActiveSheet(spreadsheet.getSheets()[1]);

المعلّمات

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

Sheet - ورقة البيانات التي تم إنشاؤها باستخدام الورقة النشطة الجديدة

تعمل هذه السياسة على ضبط ورقة البيانات النشطة في جدول بيانات، مع خيار استعادة أحدث الاختيارات المتوفرة بها. تعرض واجهة مستخدم "جداول بيانات Google" ورقة البيانات التي تم اختيارها، ما لم تكن الورقة تنتمي إلى جدول بيانات مختلف.

var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
var firstSheet = spreadsheet.getSheets()[0];
var secondSheet = spreadsheet.getSheets()[1];
// Set the first sheet as the active sheet and select the range D4:F4.
spreadsheet.setActiveSheet(firstSheet).getRange('D4:F4').activate();

// Switch to the second sheet to do some work.
spreadsheet.setActiveSheet(secondSheet);
// Switch back to first sheet, and restore its selection.
spreadsheet.setActiveSheet(firstSheet, true);

// The selection of first sheet is restored, and it logs D4:F4
var range = spreadsheet.getActiveSheet().getSelection().getActiveRange();
Logger.log(range.getA1Notation());

المعلّمات

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

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

التفويض

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

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

لضبط جدول البيانات النشط.

// The code below makes the spreadsheet with key "1234567890" the active spreadsheet
var ss = SpreadsheetApp.openById("1234567890");
SpreadsheetApp.setActiveSpreadsheet(ss);

المعلّمات

لضبط الخلية المحددة على أنها current cell.

إذا كانت الخلية المحددة موجودة في نطاق محدّد من قبل، سيصبح هذا النطاق هو النطاق النشط مع الخلية في الخلية الحالية.

إذا لم تكن الخلية المحددة موجودة في أي نطاق محدد، تتم إزالة الاختيار الحالي وتصبح الخلية الخلية الحالية والنطاق النشط.

ملاحظة: يجب أن تحتوي Range المحدّدة على خلية واحدة، وإلا يمكن أن تستبعد هذه الطريقة استثناءً.

// The code below sets the cell B5 in the first sheet as the current cell.
var cell = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].getRange('B5');
SpreadsheetApp.setCurrentCell(cell);

var selection = SpreadsheetApp.getSelection();
// Current cell: B5
var currentCell = selection.getCurrentCell();

المعلّمات

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

Range — الخلية الحالية التي تم إعدادها مؤخرًا

التفويض

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

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