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

اجرای داده را برای منابع داده Looker روشن می کند.

اجرای داده برای منبع داده Looker در صورت روشن نشدن یک استثنا ایجاد می کند.

// Turns data execution on for Looker data sources.
SpreadsheetApp.enableLookerExecution();

// 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 associated Looker
// data.
ss.getDataSourceSheets()[0].refreshData();

همه تغییرات صفحه گسترده معلق را اعمال می کند.

گاهی اوقات عملیات صفحه‌گسترده برای بهبود عملکرد با هم ترکیب می‌شوند، مانند زمانی که چندین تماس با 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 - شی 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 - سازنده جدید

یک سازنده برای مقدار Rich Text ایجاد می کند.

// 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 - سازنده جدید.

صفحه گسترده ای را باز می کند که با شی File داده شده مطابقت دارد.

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