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

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

يتم تجميع عمليات جدول البيانات معًا في بعض الأحيان لتحسين الأداء، كما هو الحال عند إجراء استدعاءات متعددة للنطاق Domain.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: كائن "جداول بيانات Google" النشط

التفويض

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

• 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

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

// 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.

// Opens the spreadsheet file by its URL. If you created your script from within a
// Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Sets the range to A1:D20.
const range = sheet.getRange('A1:D20');

// Creates a filter and applies it to the specified range.
range.createFilter();

// Gets the current filter for the range and creates filter criteria that only shows cells
// that aren't empty.
const filter = range.getFilter();
const criteria = SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build();

// Sets the criteria to  column C.
filter.setColumnFilterCriteria(3, criteria);

رحلة العودة

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 هو "abc1234567".

// 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