存取及建立 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.getValue() 和 Range.getValues() 從試算表服務的 Range 類別傳回的值類型列舉。以下是 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()
在試算表中取得使用中的工作表。
試算表中使用中的工作表就是試算表 UI 中顯示的工作表。
// 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()
傳回試算表使用者介面環境的例項,該環境可讓指令碼新增選單、對話方塊和側欄等功能。指令碼只能在已開啟試算表的目前執行個體中與 UI 互動,且只有在指令碼繫結至試算表時。詳情請參閱選單和對話方塊和側欄指南。
// 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)
開啟與指定檔案物件對應的試算表。
// 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
。
試算表 UI 會顯示含有所選範圍的工作表,並選取所選範圍中定義的儲存格。
// 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)
設定試算表的有效工作表,並可選擇在工作表中還原最近選取的項目。Google 試算表 UI 會顯示所選工作表,除非工作表屬於其他試算表。
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