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

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

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

// Turns data execution on for all types of data sources.
SpreadsheetApp.enableAllDataSourcesExecution();

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets the first data source sheet in the spreadsheet and refreshes the data.
ss.getDataSourceSheets()[0].refreshData();

التفويض

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

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

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

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

// Turns data execution on for BigQuery data sources.
SpreadsheetApp.enableBigQueryExecution();

// Opens the spreadsheet file by its ID. If you created your script from a Google Sheets file,
// use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets the first data source sheet in the spreadsheet and refreshes the BigQuery data.
ss.getDataSourceSheets()[0].refreshData();

التفويض

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

• 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

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

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

// 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');

// Gets cell A1 on Sheet1.
const range = sheet.getRange('A1');

// Builds an image using a source URL.
const cellImage = SpreadsheetApp.newCellImage()
  .setSourceUrl('https://www.gstatic.com/images/branding/productlogos/apps_script/v10/web-64dp/logo_apps_script_color_1x_web_64dp.png')
  .build();

// Sets the image in cell A1.
range.setValue(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.

// 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');

// Enables BigQuery.
SpreadsheetApp.enableBigQueryExecution();

// Builds a data source specification.
// TODO (developer): Update the project ID to your own Google Cloud project ID.
const dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
  .asBigQuery()
  .setProjectId('project-id-1')
  .setTableProjectId('bigquery-public-data')
  .setDatasetId('ncaa_basketball')
  .setTableId('mbb_historical_teams_games')
  .build();

// Adds the data source and its data to the spreadsheet.
ss.insertDataSourceSheet(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 غير موجود أو لم يكن لدى المستخدم إذن بالوصول إليه.

// Opens a spreadsheet by its URL and logs its name.
// Note that the spreadsheet doesn't physically open on the client side.
// It opens on the server only (for modification by the script).
var ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc1234567/edit');
console.log(ss.getName());

المَعلمات

استرجاع الكرة

Spreadsheet - كائن جدول البيانات بعنوان URL المحدّد

التفويض

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

• 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