存取及建立 Google 試算表檔案。這個類別是試算表服務的父項類別。
屬性
屬性 | 類型 | 說明 |
---|---|---|
AutoFillSeries | AutoFillSeries | 列舉類型,用來計算自動填入的值。 |
BandingTheme | BandingTheme | 可能的帶狀主題列舉。 |
BooleanCriteria | BooleanCriteria | 列舉條件式格式設定布林條件。 |
BorderStyle | BorderStyle | 列舉在 Range 上設定邊框的有效樣式。 |
ColorType | ColorType | 可能的顏色類型的列舉。 |
CopyPasteType | CopyPasteType | 可能的貼上類型列舉。 |
DataExecutionErrorCode | DataExecutionErrorCode | 列舉可能的資料執行錯誤代碼。 |
DataExecutionState | DataExecutionState | 可能的資料執行狀態列舉。 |
DataSourceParameterType | DataSourceParameterType | 可能的資料來源參數類型列舉。 |
DataSourceRefreshScope | DataSourceRefreshScope | 列舉可能的資料來源重新整理範圍。 |
DataSourceType | DataSourceType | 可能的資料來源類型列舉。 |
DataValidationCriteria | DataValidationCriteria | 列舉表示可在特定範圍內設定的資料驗證條件。 |
DateTimeGroupingRuleType | DateTimeGroupingRuleType | 日期時間分組規則的列舉。 |
DeveloperMetadataLocationType | DeveloperMetadataLocationType | 可能的開發人員中繼資料位置類型列舉。 |
DeveloperMetadataVisibility | DeveloperMetadataVisibility | 列舉可能的開發人員中繼資料瀏覽權限。 |
Dimension | Dimension | 試算表的可能維度列舉。 |
Direction | Direction | 可在試算表中使用箭頭移動的可能路線列舉 鍵。 |
FrequencyType | FrequencyType | 可能頻率類型的列舉。 |
GroupControlTogglePosition | GroupControlTogglePosition | 群組控制項切換鈕可能位於的位置列舉。 |
InterpolationType | InterpolationType | 條件式格式漸層內插類型列舉。 |
PivotTableSummarizeFunction | PivotTableSummarizeFunction | 列舉函式,可用於總結資料透視表中的值。 |
PivotValueDisplayType | PivotValueDisplayType | 列舉出顯示資料透視值的方式。 |
ProtectionType | ProtectionType | 列舉項目,代表試算表中可禁止編輯的部分。 |
RecalculationInterval | RecalculationInterval | 列舉可用於重新計算試算表的可能間隔時間。 |
RelativeDate | RelativeDate | 以日期為準的 BooleanCriteria 計算所用值的相對日期選項列舉值。 |
SheetType | SheetType | 列舉幾個可存在於試算表中的工作表類型。 |
SortOrder | SortOrder | 排序順序的列舉。 |
TextDirection | TextDirection | 有效文字路線的列舉。 |
TextToColumnsDelimiter | TextToColumnsDelimiter | 列舉將文字分割成不同欄的預設分隔符號。 |
ThemeColorType | ThemeColorType | 列舉可能的主題顏色類型。 |
ValueType | ValueType | 這個例子列舉了試算表服務的 Range 類別中的 Range.getValue() 和 Range.getValues() 傳回的值類型。列舉值
下列為 Number 、Boolean 、Date 或 String 以外的項目。 |
WrapStrategy | WrapStrategy | 列舉給儲存格使用的策略列舉。 |
方法
內容詳盡的說明文件
create(name)
以指定名稱建立新試算表。
// The code below creates a new spreadsheet "Finances" and logs the URL for it var ssNew = SpreadsheetApp.create("Finances"); Logger.log(ssNew.getUrl());
參數
名稱 | 類型 | 說明 |
---|---|---|
name | String | 試算表名稱。 |
回攻員
Spreadsheet
:新試算表
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets
create(name, rows, columns)
使用名字和指定列數和欄數建立新試算表。
// 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());
參數
名稱 | 類型 | 說明 |
---|---|---|
name | String | 試算表名稱。 |
rows | Integer | 試算表的列數。 |
columns | Integer | 試算表的欄數。 |
回攻員
Spreadsheet
:新試算表
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets
enableAllDataSourcesExecution()
針對所有類型的資料來源開啟資料執行功能。
如果未啟用資料來源類型,資料執行作業會擲回例外狀況。使用這個方法 ,即可為所有資料來源類型啟用資料執行功能。
// 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
enableBigQueryExecution()
針對 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
flush()
套用所有待處理的試算表變更。
為了改善效能,試算表作業有時會合併在一起 多次呼叫 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(); } }
getActive()
傳回目前正在使用的試算表;如果沒有試算表,則傳回 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
getActiveRange()
傳回作用中工作表中的所選範圍;如果沒有有效範圍,則傳回 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
getActiveRangeList()
傳回使用中的工作表中的有效範圍清單;如果沒有範圍,則傳回 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
getActiveSheet()
取得試算表中的工作表。
試算表中正在使用的工作表是指正在在試算表中顯示的工作表 第一種是使用無代碼解決方案 AutoML 透過使用者介面建立機器學習模型
// 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
getActiveSpreadsheet()
傳回目前正在使用的試算表;如果沒有試算表,則傳回 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
getCurrentCell()
傳回所選的目前 (醒目顯示) 儲存格,該儲存格位於
正在使用的工作表。如果目前沒有儲存格,則為 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
getSelection()
getUi()
傳回試算表使用者介面環境的執行個體,該環境可讓指令碼 新增選單、對話方塊和側欄等功能。指令碼只能與以下項目的使用者介面互動: 已開啟的試算表例項,且前提是指令碼已繫結至試算表。若需更多資訊,請參閲 選單和對話方塊和側欄的指南。
// 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
:這份試算表使用者介面環境的執行個體
newCellImage()
建立 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
:新的建構工具。
newColor()
建立 Color
的建構工具。
var rgbColor = SpreadsheetApp.newColor().setRgbColor("#FF0000").build();
回攻員
ColorBuilder
:新的建構工具。
newConditionalFormatRule()
建立條件式格式設定規則的建構工具。
// 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
:新的建構工具。
newDataSourceSpec()
建立 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
:新的建構工具。
newDataValidation()
建立資料驗證規則的建構工具。
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
:新的建構工具。
newFilterCriteria()
建立 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
:新的建構工具
newRichTextValue()
建立 RTF 格式的建構工具。
// 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
:新的建構工具。
newTextStyle()
建立文字樣式的建構工具。
// 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
:新的建構工具。
open(file)
開啟對應指定 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()); }
參數
名稱 | 類型 | 說明 |
---|---|---|
file | File | 要開啟的檔案。 |
回攻員
Spreadsheet
:試算表
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets
openById(id)
開啟含有指定 ID 的試算表。您可以從網址中擷取試算表 ID。適用對象
舉例來說,網址 https://docs.google.com/spreadsheets/d/abc1234567/edit#gid=0
中的試算表 ID 是「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());
參數
名稱 | 類型 | 說明 |
---|---|---|
id | String | 試算表的專屬 ID。 |
回攻員
Spreadsheet
:具有指定 ID 的試算表物件
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets
openByUrl(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());
參數
名稱 | 類型 | 說明 |
---|---|---|
url | String | 試算表的網址。 |
回攻員
Spreadsheet
:含有指定網址的試算表物件。
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets
setActiveRange(range)
將指定範圍設為 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 | Range | 要設為有效範圍的範圍。 |
回攻員
Range
:新的有效範圍
setActiveRangeList(rangeList)
將指定的範圍清單設為 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 | RangeList | 要選取的範圍清單。 |
回攻員
RangeList
:新選取的範圍清單
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
setActiveSheet(sheet)
setActiveSheet(sheet, restoreSelection)
設定試算表中正在使用的工作表,並可選擇還原最近選取的工作表 。除非試算表屬於 以及不同的試算表
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 | Sheet | 新的使用中工作表。 |
restoreSelection | Boolean | 如果是 true ,則代表最近選取的新有效工作表
就會再次選取新的工作表;如果為 false ,則新的工作表
而不會變更目前選取的項目 |
回攻員
Sheet
:新的使用中的工作表
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
setActiveSpreadsheet(newActiveSpreadsheet)
設定使用中的試算表。
// The code below makes the spreadsheet with key "1234567890" the active spreadsheet var ss = SpreadsheetApp.openById("1234567890"); SpreadsheetApp.setActiveSpreadsheet(ss);
參數
名稱 | 類型 | 說明 |
---|---|---|
newActiveSpreadsheet | Spreadsheet | 要設為使用中的試算表。 |
setCurrentCell(cell)
將指定儲存格設為 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();
參數
名稱 | 類型 | 說明 |
---|---|---|
cell | Range | 要設為目前儲存格的儲存格。 |
回攻員
Range
:新建的儲存格
授權
使用這個方法的指令碼需要下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets