存取及修改試算表區間。範圍可以是工作表中的單一儲存格,也可以是工作表中一組相鄰的儲存格。
方法
內容詳盡的說明文件
activate()
將指定的範圍設為 active range
,範圍內的左上方儲存格則為 current cell
。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getRange('A1:D10'); range.activate(); const selection = sheet.getSelection(); // Current cell: A1 const currentCell = selection.getCurrentCell(); // Active Range: A1:D10 const activeRange = selection.getActiveRange();
回攻員
Range
:這個範圍,用於鏈結。
activate As Current Cell()
將指定的儲存格設為 current cell
。
如果指定的儲存格位於現有範圍內,則該範圍會成為有效範圍,而儲存格則會成為目前的儲存格。
如果指定的儲存格不在任何現有範圍內,系統會移除現有選取範圍,並將該儲存格設為目前的儲存格和有效範圍。
注意:指定的 Range
必須包含一個儲存格,否則會擲回例外狀況。
// Gets the first sheet of the spreadsheet. const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; // Gets the cell B5 and sets it as the active cell. const range = sheet.getRange('B5'); const currentCell = range.activateAsCurrentCell(); // Logs the activated cell. console.log(currentCell.getA1Notation());
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
add Developer Metadata(key)
將含有指定鍵的開發人員中繼資料新增至範圍。
// 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 row 2 on the sheet. const range = sheet.getRange('2:2'); // Adds the key 'NAME' to the developer metadata for row 2. range.addDeveloperMetadata('NAME'); // Gets the metadata and logs it to the console. const developerMetaData = range.getDeveloperMetadata()[0]; console.log(developerMetaData.getKey());
參數
名稱 | 類型 | 說明 |
---|---|---|
key | String | 新的開發人員中繼資料鍵。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
add Developer Metadata(key, visibility)
將開發人員中繼資料加入範圍,並指定鍵和瀏覽權限。
// 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 row 2 on Sheet1. const range = sheet.getRange('2:2'); // Adds the key 'NAME' and sets the developer metadata visibility to 'DOCUMENT' // for row 2 on Sheet1. range.addDeveloperMetadata( 'NAME', SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT, ); // Gets the updated metadata info and logs it to the console. const developerMetaData = range.getDeveloperMetadata()[0]; console.log(developerMetaData.getKey()); console.log(developerMetaData.getVisibility().toString());
參數
名稱 | 類型 | 說明 |
---|---|---|
key | String | 新的開發人員中繼資料鍵。 |
visibility | Developer | 新開發人員中繼資料的瀏覽權限。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
add Developer Metadata(key, value)
將開發人員中繼資料新增至指定範圍,並指定鍵和值。
// 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 row 2 of Sheet1. const range = sheet.getRange('2:2'); // Adds the key 'NAME' and sets the value to 'GOOGLE' for the metadata of row 2. range.addDeveloperMetadata('NAME', 'GOOGLE'); // Gets the metadata and logs it to the console. const developerMetaData = range.getDeveloperMetadata()[0]; console.log(developerMetaData.getKey()); console.log(developerMetaData.getValue());
參數
名稱 | 類型 | 說明 |
---|---|---|
key | String | 新的開發人員中繼資料鍵。 |
value | String | 新開發人員中繼資料的值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
add Developer Metadata(key, value, visibility)
為範圍新增開發人員中繼資料,並指定鍵、值和瀏覽權限。
// 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 row 2 on the sheet. const range = sheet.getRange('2:2'); // Adds the key 'NAME', sets the value to 'GOOGLE', and sets the visibility // to PROJECT for row 2 on the sheet. range.addDeveloperMetadata( 'NAME', 'GOOGLE', SpreadsheetApp.DeveloperMetadataVisibility.PROJECT, ); // Gets the updated metadata info and logs it to the console. const developerMetaData = range.getDeveloperMetadata()[0]; console.log(developerMetaData.getKey()); console.log(developerMetaData.getValue()); console.log(developerMetaData.getVisibility().toString());
參數
名稱 | 類型 | 說明 |
---|---|---|
key | String | 新的開發人員中繼資料鍵。 |
value | String | 新開發人員中繼資料的值。 |
visibility | Developer | 新開發人員中繼資料的瀏覽權限。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
apply Column Banding()
將預設的欄帶主題套用至指定範圍。根據預設,分割帶有頁首,但沒有頁尾顏色。
// 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 row 2 on the sheet. const range = sheet.getRange('2:2'); // Applies column banding to row 2. const colBanding = range.applyColumnBanding(); // Gets the first banding on the sheet and logs the color of the header column. console.log( sheet.getBandings()[0] .getHeaderColumnColorObject() .asRgbColor() .asHexString(), ); // Gets the first banding on the sheet and logs the color of the second column. console.log( sheet.getBandings()[0] .getSecondColumnColorObject() .asRgbColor() .asHexString(), );
回攻員
Banding
- 新的頻帶。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
apply Column Banding(bandingTheme)
將指定的資料欄帶狀主題套用至範圍。根據預設,分割帶有頁首,但沒有頁尾顏色。
// 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 row 2 on the sheet. const range = sheet.getRange('2:2'); // Applies the INDIGO color banding theme to the columns in row 2. const colBanding = range.applyColumnBanding(SpreadsheetApp.BandingTheme.INDIGO); // Gets the first banding on the sheet and logs the color of the second column. console.log( sheet.getBandings()[0] .getSecondColumnColorObject() .asRgbColor() .asHexString(), );
參數
名稱 | 類型 | 說明 |
---|---|---|
banding | Banding | 要套用至指定範圍內資料欄的色彩主題。 |
回攻員
Banding
- 新的頻帶。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
apply Column Banding(bandingTheme, showHeader, showFooter)
將指定的資料欄分割主題套用至範圍,並設定指定的頁首和頁尾。
// 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 rows 12-22 on the sheet. const range = sheet.getRange('12:22'); // Applies the BLUE color banding theme to rows 12-22. // Sets the header visibility to false and the footer visibility to true. const colBanding = range.applyColumnBanding( SpreadsheetApp.BandingTheme.BLUE, false, true, ); // Gets the banding color and logs it to the console. console.log( sheet.getBandings()[0] .getSecondColumnColorObject() .asRgbColor() .asHexString(), ); // Gets the header color object and logs it to the console. Returns null because // the header visibility is set to false. console.log(sheet.getBandings()[0].getHeaderColumnColorObject()); // Gets the footer color and logs it to the console. console.log( sheet.getBandings()[0] .getFooterColumnColorObject() .asRgbColor() .asHexString(), );
參數
名稱 | 類型 | 說明 |
---|---|---|
banding | Banding | 要套用至指定範圍內資料欄的色彩主題。 |
show | Boolean | 如果為 true ,則會將分割主題標題顏色套用至第一個資料欄。 |
show | Boolean | 如果為 true ,則會將分割主題頁尾顏色套用至最後一欄。 |
回攻員
Banding
- 新的頻帶。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
apply Row Banding()
將預設的列分割主題套用至指定範圍。根據預設,分割帶有頁首,但沒有頁尾顏色。
// Opens the spreadsheet by its URL. If you created your script from within a // Google Sheets spreadsheet, 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 rows 1-30 on Sheet1. const range = sheet.getRange('1:30'); // Applies row banding to rows 1-30. range.applyRowBanding(); // Gets the hex color of the second banded row. const secondRowColor = range.getBandings()[0].getSecondRowColorObject().asRgbColor().asHexString(); // Logs the hex color to console. console.log(secondRowColor);
回攻員
Banding
:頻帶。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
apply Row Banding(bandingTheme)
將指定的列分割主題套用至指定範圍。根據預設,分割帶有頁首,但沒有頁尾顏色。
// Opens the spreadsheet by its URL. If you created your script from within a // Google Sheets spreadsheet, 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 rows 1-30 on Sheet1. const range = sheet.getRange('1:30'); // Applies the INDIGO row banding theme to rows 1-30. range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO); // Gets the hex color of the second banded row. const secondRowColor = range.getBandings()[0].getSecondRowColorObject().asRgbColor().asHexString(); // Logs the hex color to console. console.log(secondRowColor);
參數
名稱 | 類型 | 說明 |
---|---|---|
banding | Banding | 要套用至指定範圍內資料列的顏色主題。 |
回攻員
Banding
- 新的頻帶。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
apply Row Banding(bandingTheme, showHeader, showFooter)
將指定的列分割主題套用至範圍,並套用指定的頁首和頁尾設定。
// Opens the spreadsheet by its URL. If you created your script from within a // Google Sheets spreadsheet, 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 rows 1-30 on Sheet1. const range = sheet.getRange('1:30'); // Applies the INDIGO row banding to rows 1-30 and // specifies to hide the header and show the footer. range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO, false, true);
參數
名稱 | 類型 | 說明 |
---|---|---|
banding | Banding | 要套用至指定範圍內資料列的顏色主題。 |
show | Boolean | 如果為 true ,則會將分割主題標題顏色套用至第一列。 |
show | Boolean | 如果為 true ,則會將分割主題頁尾顏色套用至最後一列。 |
回攻員
Banding
- 新的頻帶。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
auto Fill(destination, series)
根據這個範圍內的資料,填入 destination
的資料。新值也由指定的 series
類型決定。目的地範圍必須包含這個範圍,且只能往一個方向延伸。舉例來說,以下程式碼會根據 A1:A4
中的目前值,為 A1:A20
填入一系列遞增的數字:
const sheet = SpreadsheetApp.getActiveSheet(); // Has values [1, 2, 3, 4]. const sourceRange = sheet.getRange('A1:A4'); // The range to fill with values. const destination = sheet.getRange('A1:A20'); // Inserts new values in A5:A20, continuing the pattern expressed in A1:A4 sourceRange.autoFill(destination, SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);
參數
名稱 | 類型 | 說明 |
---|---|---|
destination | Range | 要自動填入值的範圍。目的地範圍應包含這個範圍,並只向一個方向 (向上、向下、向左或向右) 延伸。 |
series | Auto | 應用於計算新值的自動填入序列類型。這一系列的效果會因來源資料的類型和數量而異。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
auto Fill To Neighbor(series)
計算範圍,以便根據相鄰儲存格填入新資料,並根據該範圍內的資料,自動為該範圍填入新值。這些新值也會由指定的 series
類型決定。
計算的目標範圍會考量周圍資料,判斷應在何處插入新值:如果在自動填入的資料欄左側或右側有資料,新值只會延伸到相鄰的資料。
舉例來說,如果 A1:A20
填入一系列遞增的數字,並在包含一系列日期的範圍 B1:B4
上呼叫此方法,則新值只會插入 B5:B20
。這樣一來,這些新值就會「黏附」在 A 欄中含有值的儲存格中。
const sheet = SpreadsheetApp.getActiveSheet(); // A1:A20 has values [1, 2, 3, ... 20]. // B1:B4 has values [1/1/2017, 1/2/2017, ...] const sourceRange = sheet.getRange('B1:B4'); // Results in B5:B20 having values [1/5/2017, ... 1/20/2017] sourceRange.autoFillToNeighbor(SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);
參數
名稱 | 類型 | 說明 |
---|---|---|
series | Auto | 應用於計算新值的自動填入序列類型。這一系列的效果會因來源資料的類型和數量而異。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
break Apart()
再次將範圍內的任何多欄儲存格拆分為個別儲存格。
在指定範圍上呼叫這個函式,等同於選取範圍,然後依序點選「格式」>「合併儲存格」>「取消合併」。
// Opens the spreadsheet by its URL. If you created your script from within a // Google Sheets spreadsheet, 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 the range A1:C6 on Sheet1. const range = sheet.getRange('A1:C6'); // Unmerges the range A1:C6 into individual cells. range.breakApart();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
can Edit()
判斷使用者是否有權編輯該範圍中的每個儲存格。試算表擁有者一律可以編輯受保護的範圍和試算表。
// Opens the spreadsheet by its URL. If you created your script from within a // Google Sheets spreadsheet, 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 the range A1:C6 on Sheet1. const range = sheet.getRange('A1:C6'); // Logs whether the user has permission to edit every cell in the range. console.log(range.canEdit());
回攻員
Boolean
:如果使用者有權編輯範圍中的每個儲存格,則為 true
;否則為 false
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
check()
將範圍內的核取方塊狀態變更為「已勾選」。忽略目前不含已勾選或未勾選值的範圍內儲存格。
// Changes the state of cells which currently contain either the checked or // unchecked value configured in the range A1:B10 to 'checked'. const range = SpreadsheetApp.getActive().getRange('A1:B10'); range.check();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
clear()
清除內容和格式範圍。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:D10'); range.clear();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
clear(options)
清除指定進階選項所指定的內容範圍、格式、資料驗證規則和/或註解。根據預設,系統會清除所有資料。
// The code below clears range C2:G7 in the active sheet, but preserves the // format, data validation rules, and comments. SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 5).clear({ contentsOnly: true });
參數
名稱 | 類型 | 說明 |
---|---|---|
options | Object | 指定進階參數的 JavaScript 物件,如下所列。 |
進階參數
名稱 | 類型 | 說明 |
---|---|---|
comments | Boolean | 是否只清除留言。 |
contents | Boolean | 是否只清除內容。 |
format | Boolean | 是否只清除格式;請注意,清除格式也會清除資料驗證規則。 |
validations | Boolean | 是否只清除資料驗證規則。 |
skip | Boolean | 是否要避免清除篩選出的資料列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
clear Content()
清除指定範圍的內容,但保留格式設定。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:D10'); range.clearContent();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
clear Data Validations()
清除指定範圍的資料驗證規則。
// Clear the data validation rules for cells A1:B5. const range = SpreadsheetApp.getActive().getRange('A1:B5'); range.clearDataValidations();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
clear Format()
清除這個範圍的格式。
這會清除範圍內儲存格或儲存格的文字格式,但不會重設任何數字格式規則。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:D10'); range.clearFormat();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
clear Note()
清除指定儲存格或儲存格中的備註。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:D10'); range.clearNote();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
collapse Groups()
收合完全包含在範圍內的所有群組。如果沒有任何群組完全位於範圍內,系統會收合部分位於範圍內的展開最深層的群組。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getActiveRange(); // All row and column groups within the range are collapsed. range.collapseGroups();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
copy Format To Range(gridId, column, columnEnd, row, rowEnd)
將範圍的格式複製到指定位置。如果目的地大於或小於來源範圍,系統會相應重複或截斷來源。請注意,這個方法只會複製格式。
如需 gridId 參數的詳細說明,請參閱 get
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const source = ss.getSheets()[0]; const range = source.getRange('B2:D4'); // This copies the formatting in B2:D4 in the source sheet to // D4:F6 in the sheet with gridId 1555299895. Note that you can get the gridId // of a sheet by calling sheet.getSheetId() or range.getGridId(). range.copyFormatToRange(1555299895, 4, 6, 4, 6);
參數
名稱 | 類型 | 說明 |
---|---|---|
grid | Integer | 試算表中工作表的專屬 ID,不論位置為何。 |
column | Integer | 目標範圍的第一欄。 |
column | Integer | 目標範圍的結束欄。 |
row | Integer | 目標範圍的起始列。 |
row | Integer | 目標範圍的結尾列。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
copy Format To Range(sheet, column, columnEnd, row, rowEnd)
將範圍的格式複製到指定位置。如果目的地大於或小於來源範圍,系統會相應重複或截斷來源。請注意,這個方法只會複製格式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const source = ss.getSheets()[0]; const destination = ss.getSheets()[1]; const range = source.getRange('B2:D4'); // This copies the formatting in B2:D4 in the source sheet to // D4:F6 in the second sheet range.copyFormatToRange(destination, 4, 6, 4, 6);
參數
名稱 | 類型 | 說明 |
---|---|---|
sheet | Sheet | 目標工作表。 |
column | Integer | 目標範圍的第一欄。 |
column | Integer | 目標範圍的結束欄。 |
row | Integer | 目標範圍的起始列。 |
row | Integer | 目標範圍的結尾列。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
copy To(destination)
將資料從某個儲存格範圍複製到另一個儲存格範圍。系統會複製值和格式。
// The code below copies the first 5 columns over to the 6th column. const sheet = SpreadsheetApp.getActiveSheet(); const rangeToCopy = sheet.getRange(1, 1, sheet.getMaxRows(), 5); rangeToCopy.copyTo(sheet.getRange(1, 6));
參數
名稱 | 類型 | 說明 |
---|---|---|
destination | Range | 要複製到的目的地範圍,只有左上方的儲存格位置相關。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
copy To(destination, copyPasteType, transposed)
將資料從某個儲存格範圍複製到另一個儲存格範圍。
// The code below copies only the values of the first 5 columns over to the 6th // column. const sheet = SpreadsheetApp.getActiveSheet(); sheet.getRange('A:E').copyTo( sheet.getRange('F1'), SpreadsheetApp.CopyPasteType.PASTE_VALUES, false, );
參數
名稱 | 類型 | 說明 |
---|---|---|
destination | Range | 要複製到的目的地範圍,只有左上方的儲存格位置相關。 |
copy | Copy | 指定範圍內容如何貼到目的地的類型。 |
transposed | Boolean | 是否要以轉置的方向貼上範圍。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
copy To(destination, options)
將資料從某個儲存格範圍複製到另一個儲存格範圍。根據預設,系統會複製值和格式,但可以使用進階引數覆寫這項設定。
// The code below copies only the values of the first 5 columns over to the 6th // column. const sheet = SpreadsheetApp.getActiveSheet(); sheet.getRange('A:E').copyTo(sheet.getRange('F1'), {contentsOnly: true});
參數
名稱 | 類型 | 說明 |
---|---|---|
destination | Range | 要複製到的目的地範圍,只有左上方的儲存格位置相關。 |
options | Object | 指定進階參數的 JavaScript 物件,如下所列。 |
進階參數
名稱 | 類型 | 說明 |
---|---|---|
format | Boolean | 指定只應複製格式 |
contents | Boolean | 表示只應複製內容 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
copy Values To Range(gridId, column, columnEnd, row, rowEnd)
將指定範圍的內容複製到指定位置。如果目的地大於或小於來源範圍,系統會相應重複或截斷來源。
如需 gridId 參數的詳細說明,請參閱 get
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const source = ss.getSheets()[0]; const range = source.getRange('B2:D4'); // This copies the data in B2:D4 in the source sheet to // D4:F6 in the sheet with gridId 0 range.copyValuesToRange(0, 4, 6, 4, 6);
參數
名稱 | 類型 | 說明 |
---|---|---|
grid | Integer | 試算表中工作表的專屬 ID,不論位置為何。 |
column | Integer | 目標範圍的第一欄。 |
column | Integer | 目標範圍的結束欄。 |
row | Integer | 目標範圍的起始列。 |
row | Integer | 目標範圍的結尾列。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
copy Values To Range(sheet, column, columnEnd, row, rowEnd)
將指定範圍的內容複製到指定位置。如果目的地大於或小於來源範圍,系統會相應重複或截斷來源。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const source = ss.getSheets()[0]; const destination = ss.getSheets()[1]; const range = source.getRange('B2:D4'); // This copies the data in B2:D4 in the source sheet to // D4:F6 in the second sheet range.copyValuesToRange(destination, 4, 6, 4, 6);
參數
名稱 | 類型 | 說明 |
---|---|---|
sheet | Sheet | 目標工作表。 |
column | Integer | 目標範圍的第一欄。 |
column | Integer | 目標範圍的結束欄。 |
row | Integer | 目標範圍的起始列。 |
row | Integer | 目標範圍的結尾列。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
create Data Source Pivot Table(dataSource)
從資料來源建立空白資料來源資料透視表,並將其固定在這個範圍內的第一個儲存格。
本例說明如何建立及設定新的資料來源資料轉換表。
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); const anchorCell = spreadsheet.getSheets()[0].getRange('A1'); const dataSource = spreadsheet.getDataSources()[0]; const pivotTable = anchorCell.createDataSourcePivotTable(dataSource); pivotTable.addRowGroup('dataColumnA'); pivotTable.addColumnGroup('dataColumnB'); pivotTable.addPivotValue( 'dataColumnC', SpreadsheetApp.PivotTableSummarizeFunction.SUM, ); pivotTable.addFilter( 'dataColumnA', SpreadsheetApp.newFilterCriteria().whenTextStartsWith('A').build(), );
參數
名稱 | 類型 | 說明 |
---|---|---|
data | Data | 要用來建立資料透視表的資料來源。 |
回攻員
Data
:新建立的資料來源資料透視表。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
create Data Source Table(dataSource)
從資料來源建立空白資料來源資料表,並將資料表繫結至這個範圍中的第一個儲存格。
本範例說明如何建立及設定新的資料來源資料表。
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); const anchorCell = spreadsheet.getSheets()[0].getRange('A1'); const dataSource = spreadsheet.getDataSources()[0]; const dataSourceTable = anchorCell.createDataSourceTable(dataSource) .addColumns('dataColumnA', 'dataColumnB', 'dataColumnC') .addSortSpec('dataColumnA', true) // ascending=true .addSortSpec('dataColumnB', false); // ascending=false
參數
名稱 | 類型 | 說明 |
---|---|---|
data | Data | 要用來建立資料透視表的資料來源。 |
回攻員
Data
:新建立的資料來源表格。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
create Developer Metadata Finder()
傳回 DeveloperMetadataFinderApi,用於在這個範圍內尋找開發人員中繼資料。只有當中繼資料完全包含在該範圍內時,才會屬於該範圍的範圍。舉例來說,與「3:3」列相關聯的中繼資料不在「A1:D5」範圍內,但在「1:5」範圍內。
// 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 the range A1:C6. const range = sheet.getRange('A1:C6'); // Creates a developer metadata finder to search for metadata in the scope of // this range. const developerMetaDataFinder = range.createDeveloperMetadataFinder(); // Logs information about the developer metadata finder to the console. const developerMetaData = developerMetaDataFinder.find()[0]; console.log(developerMetaData.getKey()); console.log(developerMetaData.getValue()); console.log(developerMetaData.getVisibility().toString());
回攻員
Developer
:開發人員中繼資料搜尋工具,可搜尋這個範圍內的中繼資料。
create Filter()
建立篩選器,並套用至工作表的指定範圍。你無法在工作表中建立多個篩選器。如要在建立篩選器後存取及修改篩選器,請使用 get
或 Sheet.getFilter()
。
const ss = SpreadsheetApp.getActiveSheet(); const range = ss.getRange('A1:C20'); // Creates a new filter and applies it to the range A1:C20 on the active sheet. function createFilter() { range.createFilter(); } // Gets the filter and applies criteria that only shows cells that aren't empty. function getFilterAddCriteria() { const filter = range.getFilter(); const criteria = SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build(); filter.setColumnFilterCriteria(2, criteria); }使用這個方法為
Grid
試算表 (試算表的預設類型) 建立篩選器。格狀試算表是指未連結至資料庫的試算表。如要建立其他類型的篩選器,請參閱以下文章:
- 使用
Pivot
建立資料透視表篩選器Table.addFilter(sourceDataColumn, filterCriteria) - 為透過
Data
連結至資料庫的工作表建立篩選器Source Sheet.addFilter(columnName, filterCriteria) - 使用
Data
為與資料庫連結的資料透視表建立篩選器Source Pivot Table.addFilter(columnName, filterCriteria)
回攻員
Filter
:新篩選器。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
create Pivot Table(sourceData)
從指定的 source
建立空資料透視表,該 source
錨定於此範圍中的第一個儲存格。
// 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 as a range in order to place the pivot table. const range = sheet.getRange('A1'); // Gets the range of the source data for the pivot table. const dataRange = sheet.getRange('E12:G20'); // Creates an empty pivot table from the specified source data. const pivotTable = range.createPivotTable(dataRange); // Logs the values from the pivot table's source data to the console. console.log(pivotTable.getSourceDataRange().getValues());
參數
名稱 | 類型 | 說明 |
---|---|---|
source | Range | 用來建立資料透視表的資料。 |
回攻員
Pivot
:新建立的 Pivot
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
create Text Finder(findText)
為指定範圍建立文字尋找器,以便尋找及取代該範圍內的文字。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getActiveRange(); // Creates a text finder for the range. const textFinder = range.createTextFinder('dog'); // Returns the first occurrence of 'dog'. const firstOccurrence = textFinder.findNext(); // Replaces the last found occurrence of 'dog' with 'cat' and returns the number // of occurrences replaced. const numOccurrencesReplaced = textFinder.replaceWith('cat');
參數
名稱 | 類型 | 說明 |
---|---|---|
find | String | 要搜尋的文字。 |
回攻員
Text
:範圍的 Text
delete Cells(shiftDimension)
刪除這個儲存格範圍。沿著提供的維度,工作表中現有的資料會移至刪除的範圍。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:D10'); range.deleteCells(SpreadsheetApp.Dimension.COLUMNS);
參數
名稱 | 類型 | 說明 |
---|---|---|
shift | Dimension | 沿著哪個維度移動現有資料。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
expand Groups()
展開範圍或控制切換按鈕與此範圍相交的收合群組。控制切換鈕的位置是顯示控制切換鈕的索引,視設定而定,可能會直接放在群組前或後。如果同一個位置有兩個以上的群組,系統會展開最淺的群組。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getActiveRange(); // All row and column groups within the range are expanded. range.expandGroups();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getA1Notation()
以 A1 標記法傳回指定範圍的字串說明。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange(1, 1, 2, 5); // Logs "A1:E2" Logger.log(range.getA1Notation());
回攻員
String
:範圍的字串說明,以 A1 標記法表示。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Background()
傳回指定範圍 (例如 '#ffffff'
) 中左上角儲存格的背景顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B5'); Logger.log(cell.getBackground());
回攻員
String
:背景的顏色代碼。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Background Object()
傳回指定範圍中左上方儲存格的背景顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B5'); Logger.log(cell.getBackgroundObject().asRgbColor().asHexString());
回攻員
Color
:範圍中左上方儲存格的背景顏色。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Background Objects()
傳回指定範圍內儲存格的背景顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B5:C6'); const bgColors = range.getBackgroundObjects(); for (const i in bgColors) { for (const j in bgColors[i]) { Logger.log(bgColors[i][j].asRgbColor().asHexString()); } }
回攻員
Color[][]
:背景顏色的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Backgrounds()
傳回範圍內儲存格的背景顏色 (例如 '#ffffff'
)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B5:C6'); const bgColors = range.getBackgrounds(); for (const i in bgColors) { for (const j in bgColors[i]) { Logger.log(bgColors[i][j]); } }
回攻員
String[][]
:背景顏色代碼的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Bandings()
傳回套用至此範圍內任何儲存格的所有區塊。
// 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 a range. const range = sheet.getRange('A1:K50'); // Gets the banding info for the range. const bandings = range.getBandings(); // Logs the second row color for each banding to the console. for (const banding of bandings) { console.log(banding.getSecondRowColor()); }
回攻員
Banding[]
:套用至此範圍內任何儲存格中的所有區塊。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Cell(row, column)
傳回指定範圍內的儲存格。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); // The row and column here are relative to the range // getCell(1,1) in this code returns the cell at B2 const cell = range.getCell(1, 1); Logger.log(cell.getValue());
參數
名稱 | 類型 | 說明 |
---|---|---|
row | Integer | 相對於範圍的儲存格列。 |
column | Integer | 相對於範圍的儲存格欄。 |
回攻員
Range
:範圍,其中包含指定座標處的單一儲存格。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Column()
傳回此範圍的起始欄位置。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); // Logs "2.0" Logger.log(range.getColumn());
回攻員
Integer
:範圍在試算表中的起始欄位。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Region()
傳回在四個主要 Direction
中擴展的範圍副本,涵蓋所有含有資料的鄰近儲存格。如果範圍四周都是空白儲存格 (不包括對角線上的儲存格),系統會傳回範圍本身。這與在編輯器中選取範圍並輸入 Ctrl+A
類似。
// Assume the active spreadsheet is blank. const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; sheet.getRange('C2').setValue(100); sheet.getRange('B3').setValue(100); sheet.getRange('D3').setValue(100); sheet.getRange('C4').setValue(100); // Logs "B2:D4" Logger.log(sheet.getRange('C3').getDataRegion().getA1Notation());
回攻員
Range
:範圍的資料區域,或整個試算表的範圍。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Region(dimension)
如果指定的維度為 Dimension.ROWS
,則會傳回範圍展開的副本 Direction.UP
和 Direction.DOWN
;如果維度為 Dimension.COLUMNS
,則會傳回 Direction.NEXT
和 Direction.PREVIOUS
。範圍的擴展方式是根據範圍旁邊的資料,以表格形式進行排序。展開的範圍涵蓋沿著指定維度 (包括資料表邊界) 的所有相鄰儲存格。如果原始範圍沿著指定維度被空白儲存格包圍,系統會傳回範圍本身。這個方法類似於在編輯器中選取範圍,然後輸入資料列的
Ctrl+Space
或資料欄的 Shift+Space
。
// Assume the active spreadsheet is blank. const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; sheet.getRange('C2').setValue(100); sheet.getRange('B3').setValue(100); sheet.getRange('D3').setValue(100); sheet.getRange('C4').setValue(100); // Logs "C2:C4" Logger.log( sheet.getRange('C3') .getDataRegion(SpreadsheetApp.Dimension.ROWS) .getA1Notation(), ); // Logs "B3:D3" Logger.log( sheet.getRange('C3') .getDataRegion(SpreadsheetApp.Dimension.COLUMNS) .getA1Notation(), );
參數
名稱 | 類型 | 說明 |
---|---|---|
dimension | Dimension | 要沿著哪個維度擴展範圍。 |
回攻員
Range
:範圍的資料區域,或涵蓋原始範圍內每個欄或每個資料列的範圍。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Source Formula()
傳回範圍中第一個儲存格的 Data
,如果儲存格不包含資料來源公式,則傳回 null
。
// 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 Sheet1 by its name. const sheet = ss.getSheetByName('Sheet1'); // Gets the range A1 on Sheet1. const range = sheet.getRange('A1'); // Gets the data source formula from cell A1. const dataSourceFormula = range.getDataSourceFormula(); // Gets the formula. const formula = dataSourceFormula.getFormula(); // Logs the formula. console.log(formula);
回攻員
Data
:儲存格的 Data
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Source Formulas()
傳回範圍內儲存格中的 Data
。
// 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 Sheet1 by its name. const sheet = ss.getSheetByName('Sheet1'); // Gets the range A1:B5 on Sheet1. const range = sheet.getRange('A1:B5'); // Gets an array of the data source formulas in the range A1:B5. const dataSourceFormulas = range.getDataSourceFormulas(); // Logs the first formula in the array. console.log(dataSourceFormulas[0].getFormula());
回攻員
Data
:Data
的陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Source Pivot Tables()
取得與指定範圍相交的所有資料來源資料透視表。
// 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 Sheet1 by its name. const sheet = ss.getSheetByName('Sheet1'); // Gets the range A1:G50 on Sheet1. const range = sheet.getRange('A1:G50'); // Gets an array of the data source pivot tables in the range A1:G50. const dataSourcePivotTables = range.getDataSourcePivotTables(); // Logs the last time that the first pivot table in the array was refreshed. console.log(dataSourcePivotTables[0].getStatus().getLastRefreshedTime());
回攻員
Data
:資料來源資料透視表清單。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Source Tables()
取得與指定範圍相交的所有資料來源資料表。
// 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 Sheet1 by its name. const sheet = ss.getSheetByName('Sheet1'); // Gets the range A1:G50 on Sheet1. const range = sheet.getRange('A1:G50'); // Gets the first data source table in the range A1:G50. const dataSourceTable = range.getDataSourceTables()[0]; // Logs the time of the last completed data execution on the data source table. console.log(dataSourceTable.getStatus().getLastExecutionTime());
回攻員
Data
:資料來源表清單。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Source Url()
傳回這個範圍內資料的網址,可用於建立圖表和查詢。
Code.gs
function doGet() { const ss = SpreadsheetApp.openById( '1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c', ); const sheet = ss.getSheetByName('ContinentData'); const range = sheet.getRange('A1:B8'); const template = HtmlService.createTemplateFromFile('piechart'); template.dataSourceUrl = range.getDataSourceUrl(); return template.evaluate(); }
piechart.html
<!DOCTYPE html> <html> <head> <!--Load the AJAX API--> <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script> <script type="text/javascript"> // Load the Visualization API and the corechart package. google.charts.load('current', {'packages': ['corechart']}); // Set a callback to run when the Google Visualization API is loaded. google.charts.setOnLoadCallback(queryData); function queryData() { var query = new google.visualization.Query('<?= dataSourceUrl ?>'); query.send(drawChart); } // Callback that creates and populates a data table, // instantiates the pie chart, passes in the data and // draws it. function drawChart(response) { if (response.isError()) { alert('Error: ' + response.getMessage() + ' ' + response.getDetailedMessage()); return; } var data = response.getDataTable(); // Set chart options. var options = { title: 'Population by Continent', width: 400, height: 300 }; // Instantiate and draw the chart, passing in some options. var chart = new google.visualization.PieChart(document.getElementById('chart_div')); chart.draw(data, options); } </script> </head> <body> <!-- Div that holds the pie chart. --> <div id="chart_div"></div> </body> </html>
回攻員
String
:這個範圍的網址,可做為資料來源,傳遞至圖表等其他 API。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Table()
將這個物件內的資料做為 DataTable 傳回。
// 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 Sheet1 by its name. const sheet = ss.getSheetByName('Sheet1'); // Gets the range A1:B7 on Sheet1. const range = sheet.getRange('A1:B7'); // Gets the range A1:B7 as a data table. The values in each column must be of // the same type. const datatable = range.getDataTable(); // Uses the Charts service to build a bar chart from the data table. // This doesn't build an embedded chart. To do that, use // sheet.newChart().addRange() instead. const chart = Charts.newBarChart() .setDataTable(datatable) .setOption('title', 'Your Chart Title Here') .build();
回攻員
Data
:資料為資料表格。
get Data Table(firstRowIsHeader)
將此範圍內的資料以 DataTable 的形式傳回。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B7'); // Calling this method with "true" sets the first line to be the title of the // axes const datatable = range.getDataTable(true); // Note that this doesn't build an EmbeddedChart, so you can't just use // Sheet#insertChart(). To do that, use sheet.newChart().addRange() instead. const chart = Charts.newBarChart() .setDataTable(datatable) .setOption('title', 'Your Title Here') .build();
參數
名稱 | 類型 | 說明 |
---|---|---|
first | Boolean | 是否將第一列視為標頭。 |
回攻員
Data
:資料為資料表格。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Validation()
傳回指定範圍中左上方儲存格的資料驗證規則。如果儲存格尚未設定資料驗證,這個方法會傳回 null
。
// Log information about the data validation rule for cell A1. const cell = SpreadsheetApp.getActive().getRange('A1'); const rule = cell.getDataValidation(); if (rule != null) { const criteria = rule.getCriteriaType(); const args = rule.getCriteriaValues(); Logger.log('The data validation rule is %s %s', criteria, args); } else { Logger.log('The cell does not have a data validation rule.'); }
回攻員
Data
:範圍中左上角儲存格的資料驗證規則。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Data Validations()
傳回指定範圍內所有儲存格的資料驗證規則。如果未在特定儲存格上設定資料驗證,這個方法會針對該儲存格在陣列中的位置傳回 null
。
// Change existing data validation rules that require a date in 2013 to require // a date in 2014. const oldDates = [new Date('1/1/2013'), new Date('12/31/2013')]; const newDates = [new Date('1/1/2014'), new Date('12/31/2014')]; const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns()); const rules = range.getDataValidations(); for (let i = 0; i < rules.length; i++) { for (let j = 0; j < rules[i].length; j++) { const rule = rules[i][j]; if (rule != null) { const criteria = rule.getCriteriaType(); const args = rule.getCriteriaValues(); if (criteria === SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN && args[0].getTime() === oldDates[0].getTime() && args[1].getTime() === oldDates[1].getTime()) { // Create a builder from the existing rule, then change the dates. rules[i][j] = rule.copy().withCriteria(criteria, newDates).build(); } } } } range.setDataValidations(rules);
回攻員
Data
:與範圍內儲存格相關聯的資料驗證規則二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Developer Metadata()
取得與此範圍相關聯的開發人員中繼資料。
// 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 row 2 on Sheet1. const range = sheet.getRange('2:2'); // Adds metadata to row 2. range.addDeveloperMetadata('NAME', 'GOOGLE'); // Logs the metadata to console. for (const metadata of range.getDeveloperMetadata()) { console.log(`${metadata.getKey()}: ${metadata.getValue()}`); }
回攻員
Developer
:與這個範圍相關聯的開發人員中繼資料。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Display Value()
傳回範圍中左上角儲存格的顯示值。值為 String
。顯示的值會考量日期、時間和貨幣格式,包括試算表的語言代碼設定自動套用的格式。空白儲存格會傳回空字串。
// 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 A30 and sets its value to 'Test code.' const cell = sheet.getRange('A30'); cell.setValue('Test code'); // Gets the value and logs it to the console. console.log(cell.getDisplayValue());
回攻員
String
:這個儲存格中顯示的值。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Display Values()
傳回這個範圍的值矩形格線。
傳回顯示值的二維陣列,並以列為索引,然後以欄為索引。這些值是 String
物件。系統會根據日期、時間和貨幣格式,以及試算表的語言設定自動套用的格式,顯示相關值。空白儲存格在陣列中會以空字串表示。請注意,雖然範圍索引從 1, 1
開始,但 JavaScript 陣列的索引是從 [0][0]
開始。
// The code below gets the displayed values for the range C2:G8 // in the active spreadsheet. Note that this is a JavaScript array. const values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getDisplayValues(); Logger.log(values[0][0]);
回攻員
String[][]
:值的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Filter()
傳回此範圍所屬工作表的篩選器,如果工作表上沒有篩選器,則傳回 null
。
const ss = SpreadsheetApp.getActiveSheet(); const range = ss.getRange('A1:C20'); // Gets the existing filter on the sheet that the given range belongs to. const filter = range.getFilter();
回攻員
Filter
:篩選器。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Color Object()
傳回指定範圍左上角儲存格的字型顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getFontColorObject().asRgbColor().asHexString());
回攻員
Color
:範圍中左上角儲存格的字型顏色。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Color Objects()
傳回指定範圍內儲存格的字型顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getFontColorObjects(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j].asRgbColor().asHexString()); } }
回攻員
Color[][]
:與範圍內儲存格相關聯的字型顏色二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Families()
傳回指定範圍內儲存格的字型系列。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getFontFamilies(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:與範圍內儲存格相關聯的字型系列二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Family()
傳回指定範圍左上角儲存格中的字型系列。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getFontFamily());
回攻員
String
:儲存格字型系列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Line()
取得範圍左上角儲存格 ('underline'
、'line-through'
或 'none'
) 的線條樣式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getFontLine());
回攻員
String
:字型行。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Lines()
取得範圍內儲存格的線條樣式 ('underline'
、'line-through'
或 'none'
)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getFontLines(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:與範圍內儲存格相關聯的字型行平面陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Size()
傳回範圍左上角儲存格字型大小的點大小。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getFontSize());
回攻員
Integer
:字型大小 (以點為單位)。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Sizes()
傳回指定範圍內儲存格的字型大小。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getFontSizes(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
Integer[][]
:與範圍內儲存格相關聯的文字字型大小的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Style()
傳回範圍左上角儲存格的字型樣式 ('italic'
或 'normal'
)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getFontStyle());
回攻員
String
:儲存格文字的字型樣式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Styles()
傳回指定範圍內儲存格的字型樣式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getFontStyles(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:與範圍內儲存格相關聯的文字字型樣式二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Weight()
傳回指定範圍左上角儲存格的字型粗細 (一般/粗體)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getFontWeight());
回攻員
String
:儲存格文字的字型粗細。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Font Weights()
傳回指定範圍內儲存格字型的粗細。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getFontWeights(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:與範圍內儲存格相關聯的文字字型粗細的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Formula()
傳回指定範圍左上角儲存格的公式 (A1 標記法),如果儲存格為空白或不含公式,則傳回空字串。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // This assumes you have a function in B5 that sums up // B2:B4 const range = sheet.getRange('B5'); // Logs the calculated value and the formula Logger.log( 'Calculated value: %s Formula: %s', range.getValue(), range.getFormula(), );
回攻員
String
:儲存格的公式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Formula R1C1()
傳回指定儲存格中的公式 (R1C1 標記法),如果沒有則傳回 null
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B5'); const formula = range.getFormulaR1C1(); Logger.log(formula);
回攻員
String
:R1C1 標記法中的公式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Formulas()
傳回範圍內儲存格中的公式 (A1 標記法)。2D 陣列中的項目是空字串,代表沒有公式的儲存格。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B5:C6'); const formulas = range.getFormulas(); for (const i in formulas) { for (const j in formulas[i]) { Logger.log(formulas[i][j]); } }
回攻員
String[][]
:以字串格式呈現的公式二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Formulas R1C1()
傳回範圍內儲存格中的公式 (R1C1 標記法)。對於沒有公式的儲存格,2D 陣列中的項目為 null
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B5:C6'); const formulas = range.getFormulasR1C1(); for (const i in formulas) { for (const j in formulas[i]) { Logger.log(formulas[i][j]); } }
回攻員
String[][]
:以 R1C1 標記法表示的公式二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Grid Id()
傳回範圍父工作表的格狀 ID。ID 是隨機的非負整數值。
// Log the grid ID of the first sheet (by tab position) in the spreadsheet. const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getGridId());
回攻員
Integer
:父項工作表的格狀 ID。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Height()
傳回範圍的高度。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); // logs 3.0 Logger.log(range.getHeight());
回攻員
Integer
:範圍的高度。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Horizontal Alignment()
傳回指定範圍左上角儲存格文字的水平對齊方式 (左/置中/右)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getHorizontalAlignment());
回攻員
String
:儲存格中文字的水平對齊方式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Horizontal Alignments()
傳回範圍內儲存格水平對齊方式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getHorizontalAlignments(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:二維陣列,其中包含與範圍內儲存格相關聯的文字水平對齊方式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Last Column()
傳回結束欄位。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); // Logs "4.0" Logger.log(range.getLastColumn());
回攻員
Integer
:範圍在試算表中的結尾欄位。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Last Row()
傳回結束列位置。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); // Logs "4.0" Logger.log(range.getLastRow());
回攻員
Integer
:範圍在試算表中的結束列位置。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Merged Ranges()
傳回 Range
物件的陣列,代表完全位於目前範圍內的合併儲存格,或在目前範圍內至少包含一個儲存格。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B3'); const mergedRanges = range.getMergedRanges(); for (let i = 0; i < mergedRanges.length; i++) { Logger.log(mergedRanges[i].getA1Notation()); Logger.log(mergedRanges[i].getDisplayValue()); }
回攻員
get Next Data Cell(direction)
從範圍第一列和第一行的儲存格開始,傳回指定方向中的下一個儲存格,該儲存格是含有資料的連續儲存格範圍邊緣,或試算表在該方向邊緣的儲存格。這相當於在編輯器中輸入
Ctrl+[arrow key]
。
// Assume the active spreadsheet is blank. const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('C3:E5'); // Logs "C1" Logger.log(range.getNextDataCell(SpreadsheetApp.Direction.UP).getA1Notation());
參數
名稱 | 類型 | 說明 |
---|---|---|
direction | Direction | 尋找下一個資料區域邊緣儲存格時的方向。 |
回攻員
Range
:資料區域邊緣儲存格或試算表邊緣的儲存格。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Note()
傳回與指定範圍相關聯的附註。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getNote());
回攻員
String
:與指定儲存格相關聯的註解。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Notes()
傳回與範圍內儲存格相關聯的備註。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getNotes(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:與範圍內儲存格相關聯的筆記二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Num Columns()
傳回這個範圍內的欄數。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D5'); Logger.log(range.getNumColumns());
回攻員
Integer
:這個範圍內的欄數。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Num Rows()
傳回這個範圍內的列數。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D5'); Logger.log(range.getNumRows());
回攻員
Integer
:這個範圍內的資料列數。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Number Format()
取得指定範圍左上方儲存格的數字或日期格式。如要瞭解傳回的格式模式,請參閱 Sheets API 說明文件。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('C4'); Logger.log(cell.getNumberFormat());
回攻員
String
:範圍左上角儲存格的數值格式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Number Formats()
傳回指定範圍內儲存格中的數字或日期格式。如需瞭解傳回的格式模式,請參閱 Sheets API 說明文件。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B5:C6'); const formats = range.getNumberFormats(); for (const i in formats) { for (const j in formats[i]) { Logger.log(formats[i][j]); } }
回攻員
String[][]
:數字格式的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Rich Text Value()
傳回指定範圍左上角儲存格的富文字值,如果儲存格值不是文字,則傳回 null
。
// Gets the Rich Text value of cell D4. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('D4:F6'); const richText = range.getRichTextValue(); console.log(richText.getText());
回攻員
Rich
:範圍中左上角儲存格的富文字值,如果儲存格值不是文字,則為 null
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Rich Text Values()
傳回範圍內儲存格中的 RTF 值。
// Gets the Rich Text values for all cells in range B5:C6 const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B5:C6'); const values = range.getRichTextValues(); for (let i = 0; i < values.length; i++) { for (let j = 0; j < values[i].length; j++) { console.log(values[i][j].getText()); } }
回攻員
Rich
:RTF 值的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Row()
傳回此範圍的列位置。與 get
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2'); Logger.log(range.getRow());
回攻員
Integer
:範圍的列位置。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Row Index()
傳回此範圍的列位置。與 get
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2'); Logger.log(range.getRowIndex());
回攻員
Integer
:範圍的列位置。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
get Sheet()
傳回這個範圍所屬的工作表。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Gets the sheet that the range belongs to. const rangeSheet = range.getSheet(); // Gets the sheet name and logs it to the console. console.log(rangeSheet.getName());
回攻員
Sheet
:這個範圍所屬的試算表。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Text Direction()
傳回指定範圍左上方儲存格的文字方向。如果使用自動偵測功能判斷儲存格文字方向,則傳回 null
。
// Get the text direction of cell B1. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B1:D4'); Logger.log(range.getTextDirection());
回攻員
Text
:範圍中左上角儲存格的文字方向。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Text Directions()
傳回指定範圍內儲存格中的文字方向。2D 陣列中的項目是使用自動偵測功能的儲存格 null
。
// Get the text directions for all cells in range B5:C6 const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B5:C6'); const directions = range.getTextDirections(); for (let i = 0; i < directions.length; i++) { for (let j = 0; j < directions[i].length; j++) { Logger.log(directions[i][j]); } }
回攻員
Text
:文字方向的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Text Rotation()
傳回指定範圍左上方儲存格的文字旋轉設定。
// Log the text rotation settings for a cell. const sheet = SpreadsheetApp.getActiveSheet(); const cell = sheet.getRange('A1'); Logger.log(cell.getTextRotation());
回攻員
Text
:文字旋轉設定。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Text Rotations()
傳回指定範圍內儲存格文字旋轉設定。
const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B2:D4'); const results = range.getTextRotations(); for (const i in results) { for (const j in results[i]) { const rotation = results[i][j]; Logger.log('Cell [%s, %s] has text rotation: %v', i, j, rotation); } }
回攻員
Text
:與指定範圍內儲存格相關聯的文字旋轉角度 2D 陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Text Style()
傳回指定範圍左上角儲存格的文字樣式。
// Get the text style of cell D4. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('D4:F6'); const style = range.getTextStyle(); Logger.log(style);
回攻員
Text
:範圍中左上角儲存格的文字樣式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Text Styles()
傳回指定範圍內儲存格使用的文字樣式。
// Get the text styles for all cells in range B5:C6 const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B5:C6'); const styles = range.getTextStyles(); for (let i = 0; i < styles.length; i++) { for (let j = 0; j < styles[i].length; j++) { Logger.log(styles[i][j]); } }
回攻員
Text
:文字樣式的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Value()
傳回範圍中左上角儲存格的值。這個值的類型可能為 Number
、Boolean
、Date
或 String
,具體取決於儲存格值。空白儲存格會傳回空字串。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Gets the value of the top-left cell in the range and logs it to the console. console.log(range.getValue());
回攻員
Object
:這個儲存格中的值。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Values()
傳回這個範圍的值矩形格線。
傳回值的二維陣列,以列為索引,然後以欄為索引。這些值的類型可能為 Number
、Boolean
、Date
或 String
,具體取決於儲存格值。空白儲存格在陣列中會以空字串表示。請注意,範圍索引從 1, 1
開始,而 JavaScript 陣列的索引則從 [0][0]
開始。
// The code below gets the values for the range C2:G8 // in the active spreadsheet. Note that this is a JavaScript array. const values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues(); Logger.log(values[0][0]);在網頁應用程式中,
Date
值不是有效的參數。如果範圍含有內含 Date
值的儲存格,get Values()
就無法將資料傳回至網頁應用程式。請改為將從工作表擷取的所有值轉換為支援的 JavaScript 原始值,例如 Number
、Boolean
或 String
。回攻員
Object[][]
:值的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Vertical Alignment()
傳回指定區間左上角儲存格垂直對齊方式 (頂端/中間/底部)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getVerticalAlignment());
回攻員
String
:儲存格中文字的垂直對齊方式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Vertical Alignments()
傳回範圍內儲存格的垂直對齊方式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getVerticalAlignments(); for (const i in results) { for (const j in results[i]) { Logger.log(results[i][j]); } }
回攻員
String[][]
:二維陣列,其中包含與範圍內儲存格相關聯的文字垂直對齊方式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Width()
傳回範圍在資料欄中的寬度。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Gets the width of the range in number of columns and logs it to the console. console.log(range.getWidth());
回攻員
Integer
:範圍中的欄數。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Wrap()
傳回儲存格中的文字是否會換行。如需更精細的包裝策略,請使用 get
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.getWrap());
回攻員
Boolean
:儲存格文字是否會換行。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Wrap Strategies()
傳回範圍內儲存格適用的文字斷行策略。
// Get the text wrapping strategies for all cells in range B5:C6 const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B5:C6'); const strategies = range.getWrapStrategies(); for (let i = 0; i < strategies.length; i++) { for (let j = 0; j < strategies[i].length; j++) { Logger.log(strategies[i][j]); } }
回攻員
Wrap
:文字換行策略的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Wrap Strategy()
傳回指定範圍左上角儲存格的文字斷行策略。
// Get the text wrapping strategy of cell B1. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B1:D4'); Logger.log(range.getWrapStrategy());
回攻員
Wrap
:範圍中左上角儲存格的文字斷行策略。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
get Wraps()
傳回儲存格中的文字是否會換行。如需更精細的包裝策略,請使用 get
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); const results = range.getVerticalAlignments(); for (const i in results) { for (const j in results[i]) { const isWrapped = results[i][j]; if (isWrapped) { Logger.log('Cell [%s, %s] has wrapped text', i, j); } } }
回攻員
Boolean[][]
:二維陣列,其中包含與範圍內儲存格相關聯的文字垂直對齊方式。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
insert Cells(shiftDimension)
在這個範圍內插入空白儲存格。新的儲存格會保留先前佔用此範圍的儲存格中的任何格式。在所提供維度中,工作表中的現有資料會從插入的範圍移出。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:D10'); range.insertCells(SpreadsheetApp.Dimension.COLUMNS);
參數
名稱 | 類型 | 說明 |
---|---|---|
shift | Dimension | 沿著哪個維度移動現有資料。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
insert Checkboxes()
在範圍內的每個儲存格中插入核取方塊,並以 true
代表已勾選,以 false
代表未勾選。將範圍內所有儲存格中的值都設為 false
。
const range = SpreadsheetApp.getActive().getRange('A1:B10'); // Inserts checkboxes into each cell in the range A1:B10 configured with 'true' // for checked and 'false' for unchecked. Also, sets the value of each cell in // the range A1:B10 to 'false'. range.insertCheckboxes();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
insert Checkboxes(checkedValue)
在範圍內的每個儲存格中插入核取方塊,並設定勾選狀態的值和空白字串。將範圍中每個儲存格的值設為空字串。
const range = SpreadsheetApp.getActive().getRange('A1:B10'); // Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' // for checked and the empty string for unchecked. Also, sets the value of each // cell in the range A1:B10 to // the empty string. range.insertCheckboxes('yes');
參數
名稱 | 類型 | 說明 |
---|---|---|
checked | Object | 核取方塊資料驗證的勾選值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
insert Checkboxes(checkedValue, uncheckedValue)
在範圍內的每個儲存格中插入核取方塊,並為已勾選和未勾選狀態設定自訂值。將範圍中每個儲存格中的值設為自訂未勾選值。
const range = SpreadsheetApp.getActive().getRange('A1:B10'); // Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' // for checked and 'no' for unchecked. Also, sets the value of each cell in the // range A1:B10 to 'no'. range.insertCheckboxes('yes', 'no');
參數
名稱 | 類型 | 說明 |
---|---|---|
checked | Object | 核取方塊資料驗證的勾選值。 |
unchecked | Object | 核取方塊資料驗證的未勾選值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
is Blank()
如果範圍完全空白,就會傳回 true
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D4'); Logger.log(range.isBlank());
回攻員
Boolean
:如果範圍為空白,則傳回 true
;否則傳回 false
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
is Checked()
傳回範圍內所有儲存格的核取方塊狀態是否為「已勾選」。如果部分儲存格已勾選,而其餘儲存格未勾選,或部分儲存格沒有核取方塊資料驗證,則會傳回 null
。
const range = SpreadsheetApp.getActive().getRange('A1:A3'); // Inserts checkboxes and sets each cell value to 'no' in the range A1:A3. range.insertCheckboxes('yes', 'no'); const range1 = SpreadsheetApp.getActive().getRange('A1'); range1.setValue('yes'); // Sets the value of isRange1Checked as true as it contains the checked value. const isRange1Checked = range1.isChecked(); const range2 = SpreadsheetApp.getActive().getRange('A2'); range2.setValue('no'); // Sets the value of isRange2Checked as false as it contains the unchecked // value. const isRange2Checked = range2.isChecked(); const range3 = SpreadsheetApp.getActive().getRange('A3'); range3.setValue('random'); // Sets the value of isRange3Checked as null, as it contains an invalid checkbox // value. const isRange3Checked = range3.isChecked();
回攻員
Boolean
:如果範圍內的所有儲存格都已勾選,則為 true
;如果範圍內的所有儲存格都未勾選,則為 false
;如果有任何儲存格未勾選或沒有核取方塊資料驗證,則為 null
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
is End Column Bounded()
判斷範圍的結尾是否已繫結至特定欄。舉例來說,如果範圍 A1:B10
或 B:B
綁定至範圍結尾的資料欄,這個方法會傳回 true
;如果範圍 3:7
或 A1:5
只綁定至範圍結尾的特定資料列,這個方法會傳回 false
。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Determines if the end of the range is bound to a particular column and logs // it to the console. console.log(range.isEndColumnBounded());
回攻員
Boolean
:如果範圍結尾已繫結至特定欄,則為 true
;否則為 false
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
is End Row Bounded()
判斷範圍的結尾是否已繫結至特定資料列。舉例來說,如果範圍 A1:B10
或 3:7
已繫結至範圍結尾的資料列,這個方法會傳回 true
;如果範圍 B:B
或 A1:C
只繫結至範圍結尾的特定資料欄,這個方法會傳回 false
。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Determines if the end of the range is bound to a particular row and logs it // to the console. console.log(range.isEndRowBounded());
回攻員
Boolean
:如果範圍結尾綁定至特定資料列,則為 true
;否則為 false
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
is Part Of Merge()
如果目前範圍內的儲存格與任何合併儲存格重疊,就會傳回 true
。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:B3'); // True if any of the cells in A1:B3 is included in a merge. const isPartOfMerge = range.isPartOfMerge();
回攻員
Boolean
:如果範圍與任何已合併的儲存格重疊,則會傳回 true
;否則會傳回 false
。
is Start Column Bounded()
判斷範圍的起始值是否已繫結至特定欄。舉例來說,如果範圍 A1:B10
或 B:B
綁定至範圍開頭的資料欄,此方法會傳回 true
;如果範圍 3:7
只綁定至範圍開頭的資料列,此方法會傳回 false
。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Determines if the start of the range is bound to a particular column and logs // it to the console. console.log(range.isStartColumnBounded());
回攻員
Boolean
:如果範圍的起始值已繫結至特定欄,則為 true
;否則為 false
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
is Start Row Bounded()
判斷範圍的起始值是否已繫結至特定資料列。舉例來說,如果範圍 A1:B10
或 3:7
已繫結至範圍開頭的資料列,此方法會傳回 true
;如果範圍 B:B
只繫結至範圍開頭的特定欄,此方法會傳回 false
。
// 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 the range A1:D10 on Sheet1. const range = sheet.getRange('A1:D10'); // Determines if the start of the range is bound to a particular row and logs it // to the console. console.log(range.isStartRowBounded());
回攻員
Boolean
:如果範圍的起始值已繫結至特定資料列,則為 true
;否則為 false
。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
merge()
將範圍內的儲存格合併為單一區塊。
const sheet = SpreadsheetApp.getActiveSheet(); // The code below 2-dimensionally merges the cells in A1 to B3 sheet.getRange('A1:B3').merge();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
merge Across()
合併範圍內的儲存格,並跨越範圍內的資料欄。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The code below merges cells C5:E5 into one cell const range1 = sheet.getRange('C5:E5'); range1.mergeAcross(); // The code below creates 2 horizontal cells, F5:H5 and F6:H6 const range2 = sheet.getRange('F5:H6'); range2.mergeAcross();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
merge Vertically()
將範圍內的儲存格合併。
const sheet = SpreadsheetApp.getActiveSheet(); // The code below vertically merges the cells in A1 to A10 sheet.getRange('A1:A10').mergeVertically(); // The code below creates 3 merged columns: B1 to B10, C1 to C10, and D1 to D10 sheet.getRange('B1:D10').mergeVertically();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
move To(target)
將這個範圍的格式和值剪下並貼到目標範圍。
// The code below moves the first 5 columns over to the 6th column const sheet = SpreadsheetApp.getActiveSheet(); sheet.getRange('A1:E').moveTo(sheet.getRange('F1'));
參數
名稱 | 類型 | 說明 |
---|---|---|
target | Range | 要複製這個範圍的目標範圍,只有左上方的儲存格位置才有相關性。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
offset(rowOffset, columnOffset)
傳回從這個範圍偏移指定列數和欄數 (可能為負數) 的新範圍。新的範圍大小與原始範圍相同。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('A1'); // newCell references B2 const newCell = cell.offset(1, 1);
參數
名稱 | 類型 | 說明 |
---|---|---|
row | Integer | 從範圍左上角儲存格往下移動的列數;負值代表從範圍左上角儲存格往上移動的列數。 |
column | Integer | 範圍左上角儲存格右側的欄數;負值代表範圍左上角儲存格左側的欄。 |
回攻員
Range
:這個範圍,用於鏈結。
offset(rowOffset, columnOffset, numRows)
傳回相對於目前範圍的新範圍,其左上角點會從目前範圍偏移指定的列數和欄數,且儲存格高度為指定的高度。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('A1'); // newCell references B2:B3 const newRange = cell.offset(1, 1, 2);
參數
名稱 | 類型 | 說明 |
---|---|---|
row | Integer | 從範圍左上角儲存格往下移動的列數;負值代表從範圍左上角儲存格往上移動的列數。 |
column | Integer | 範圍左上角儲存格右側的欄數;負值代表範圍左上角儲存格左側的欄。 |
num | Integer | 新範圍的列高度。 |
回攻員
Range
:這個範圍,用於鏈結。
offset(rowOffset, columnOffset, numRows, numColumns)
傳回相對於目前範圍的新範圍,其左上角點會從目前範圍偏移指定的列數和欄數,且儲存格具有指定的高度和寬度。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('A1'); // newCell references B2:C3 const newRange = cell.offset(1, 1, 2, 2);
參數
名稱 | 類型 | 說明 |
---|---|---|
row | Integer | 從範圍左上角儲存格往下移動的列數;負值代表從範圍左上角儲存格往上移動的列數。 |
column | Integer | 範圍左上角儲存格右側的欄數;負值代表範圍左上角儲存格左側的欄。 |
num | Integer | 新範圍的列高度。 |
num | Integer | 新範圍的資料欄寬度。 |
回攻員
Range
:這個範圍,用於鏈結。
protect()
建立可保護範圍的物件,只有具備權限的使用者才能編輯該範圍。在指令碼實際變更範圍的編輯者清單 (透過呼叫 Protection.removeEditor(emailAddress)
、Protection.removeEditor(user)
、Protection.removeEditors(emailAddresses)
、Protection.addEditor(emailAddress)
、Protection.addEditor(user)
、Protection.addEditors(emailAddresses)
或為 Protection.setDomainEdit(editable)
設定新值) 之前,權限會與試算表本身的權限相同,也就是說範圍仍未受保護。如果範圍已受到保護,這個方法會建立與現有範圍重疊的新受保護範圍。如果儲存格受到多個受保護的範圍保護,而其中任何一個範圍都禁止特定使用者編輯該儲存格,則該使用者將無法編輯該儲存格。
// Protect range A1:B10, then remove all other users from the list of editors. const ss = SpreadsheetApp.getActive(); const range = ss.getRange('A1:B10'); const protection = range.protect().setDescription('Sample protected range'); // Ensure the current user is an editor before removing others. Otherwise, if // the user's edit permission comes from a group, the script throws an exception // upon removing the group. const me = Session.getEffectiveUser(); protection.addEditor(me); protection.removeEditors(protection.getEditors()); if (protection.canDomainEdit()) { protection.setDomainEdit(false); }
回攻員
Protection
:代表保護設定的物件。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
randomize()
隨機排列指定範圍內的資料列。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:C7'); // Randomizes the range range.randomize();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
remove Checkboxes()
從指定範圍移除所有核取方塊。清除每個儲存格的資料驗證,如果儲存格含有勾選或未勾選的值,則一併清除其值。
const range = SpreadsheetApp.getActive().getRange('A1:B10'); // Inserts checkboxes and sets each cell value to 'no' in the range A1:B10. range.insertCheckboxes('yes', 'no'); const range1 = SpreadsheetApp.getActive().getRange('A1'); range1.setValue('yes'); // Removes the checkbox data validation in cell A1 and clears its value. range1.removeCheckboxes(); const range2 = SpreadsheetApp.getActive().getRange('A2'); range2.setValue('random'); // Removes the checkbox data validation in cell A2 but does not clear its value. range2.removeCheckboxes();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
remove Duplicates()
移除此範圍內的資料列,如果其中的值與任何前一個資料列的值重複,就會遭到移除。只要資料列中的值相同,系統就會視其為重複項目,即使字母大小寫、格式或公式不同亦然。這個方法也會移除隱藏在檢視畫面中的重複資料列 (例如因篩選器而隱藏的資料列)。超出這個範圍的內容不會遭到移除。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B1:D7'); // Remove duplicate rows in the range. range.removeDuplicates();
回攻員
Range
:移除重複值後的結果範圍。每移除一列,範圍的大小就會減少一列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
remove Duplicates(columnsToCompare)
移除此範圍內的資料列,這些資料列在指定欄中包含與先前任何資料列重複的值。只要資料列中的值相同,系統就會視其為重複項目,即使字母大小寫、格式或公式不同亦然。這個方法也會移除從檢視畫面隱藏的重複資料列 (例如因篩選條件而隱藏)。超出這個範圍的內容不會遭到移除。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B1:D7'); // Remove rows which have duplicate values in column B. range.removeDuplicates([2]); // Remove rows which have duplicate values in both columns B and D. range.removeDuplicates([2, 4]);
參數
名稱 | 類型 | 說明 |
---|---|---|
columns | Integer[] | 要分析重複值的資料欄。如果未提供任何資料欄,系統會分析所有資料欄,找出重複項目。 |
回攻員
Range
:移除重複值後的結果範圍。每移除一列,範圍的大小就會減少一列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Background(color)
使用 CSS 符號 (例如 '#ffffff'
或 'white'
) 設定指定範圍內所有儲存格的背景顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('B2:D5'); range.setBackground('red');
參數
名稱 | 類型 | 說明 |
---|---|---|
color | String | CSS 符號中的顏色代碼 (例如 '#ffffff' 或 'white' );null 值會重設顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Background Object(color)
設定指定範圍內所有儲存格的背景顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const bgColor = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND) .build(); const range = sheet.getRange('B2:D5'); range.setBackgroundObject(bgColor);
參數
名稱 | 類型 | 說明 |
---|---|---|
color | Color | 要設定的背景顏色;null 值會重設背景顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Background Objects(color)
設定背景顏色的矩形格線 (必須符合此範圍的尺寸)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const colorAccent1 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1) .build(); const colorAccent2 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2) .build(); const colorAccent3 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3) .build(); const colorAccent4 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4) .build(); const colors = [ [colorAccent1, colorAccent2], [colorAccent3, colorAccent4], ]; const cell = sheet.getRange('B5:C6'); cell.setBackgroundObjects(colors);
參數
名稱 | 類型 | 說明 |
---|---|---|
color | Color[][] | 二維顏色陣列;null 值會重設顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Background RGB(red, green, blue)
使用 RGB 值 (整數介於 0 和 255 之間) 將背景設為指定的顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); // Sets the background to white cell.setBackgroundRGB(255, 255, 255); // Sets the background to red cell.setBackgroundRGB(255, 0, 0);
參數
名稱 | 類型 | 說明 |
---|---|---|
red | Integer | RGB 標記法中的紅色值。 |
green | Integer | RGB 符號中的綠色值。 |
blue | Integer | RGB 符號中的藍色值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Backgrounds(color)
設定背景顏色的矩形格線 (必須符合此範圍的尺寸)。顏色以 CSS 符號表示 (例如 '#ffffff'
或 'white'
)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const colors = [ ['red', 'white', 'blue'], ['#FF0000', '#FFFFFF', '#0000FF'], // These are the hex equivalents ]; const cell = sheet.getRange('B5:D6'); cell.setBackgrounds(colors);
參數
名稱 | 類型 | 說明 |
---|---|---|
color | String[][] | CSS 符號 (例如 '#ffffff' 或 'white' ) 中的二維陣列顏色;null 值會重設顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Border(top, left, bottom, right, vertical, horizontal)
設定邊框屬性。有效值為 true
(開啟)、false
(關閉) 和 null
(不變)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); // Sets borders on the top and bottom, but leaves the left and right unchanged cell.setBorder(true, null, true, null, false, false);
參數
名稱 | 類型 | 說明 |
---|---|---|
top | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
left | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
bottom | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
right | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
vertical | Boolean | true 代表內部垂直邊框,false 代表無邊框,null 代表不變。 |
horizontal | Boolean | true 代表內部水平邊框,false 代表無邊框,null 代表不變。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Border(top, left, bottom, right, vertical, horizontal, color, style)
使用顏色和/或樣式設定邊框屬性。有效值為 true
(開啟)、false
(關閉) 和 null
(不變)。如要指定顏色,請使用 CSS 符號 (例如 '#ffffff'
或 'white'
) 中的顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); // Sets borders on the top and bottom, but leaves the left and right unchanged // Also sets the color to "red", and the border to "DASHED". cell.setBorder( true, null, true, null, false, false, 'red', SpreadsheetApp.BorderStyle.DASHED, );
參數
名稱 | 類型 | 說明 |
---|---|---|
top | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
left | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
bottom | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
right | Boolean | true 代表邊框,false 代表無邊框,null 代表不變更。 |
vertical | Boolean | true 代表內部垂直邊框,false 代表無邊框,null 代表不變。 |
horizontal | Boolean | true 代表內部水平邊框,false 代表無邊框,null 代表不變。 |
color | String | CSS 符號中的顏色 (例如 '#ffffff' 或 'white' ),null 為預設顏色 (黑色)。 |
style | Border | 框線樣式,null 為預設樣式 (實心)。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Data Validation(rule)
為範圍內的所有儲存格設定一個資料驗證規則。
// Set the data validation rule for cell A1 to require a value from B1:B10. const cell = SpreadsheetApp.getActive().getRange('A1'); const range = SpreadsheetApp.getActive().getRange('B1:B10'); const rule = SpreadsheetApp.newDataValidation().requireValueInRange(range).build(); cell.setDataValidation(rule);
參數
名稱 | 類型 | 說明 |
---|---|---|
rule | Data | 要設定的資料驗證規則,或 null 以移除資料驗證。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Data Validations(rules)
為範圍內的所有儲存格設定資料驗證規則。這個方法會採用二維資料驗證陣列,並依序為資料列和資料欄編號。陣列維度必須與範圍維度相符。
// Set the data validation rules for Sheet1!A1:B5 to require a value from // Sheet2!A1:A10. const destinationRange = SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5'); const sourceRange = SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10'); const rule = SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build(); const rules = destinationRange.getDataValidations(); for (let i = 0; i < rules.length; i++) { for (let j = 0; j < rules[i].length; j++) { rules[i][j] = rule; } } destinationRange.setDataValidations(rules);
參數
名稱 | 類型 | 說明 |
---|---|---|
rules | Data | 要設定的資料驗證規則二維陣列;null 值會移除資料驗證。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Color(color)
以 CSS 符號 (例如 '#ffffff'
或 'white'
) 設定字型顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setFontColor('red');
參數
名稱 | 類型 | 說明 |
---|---|---|
color | String | CSS 符號中的字型顏色 (例如 '#ffffff' 或 'white' );null 值會重設顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Color Object(color)
設定指定範圍的字型顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const color = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT) .build(); const cell = sheet.getRange('B2'); cell.setFontColor(color);
參數
名稱 | 類型 | 說明 |
---|---|---|
color | Color | 要設定的字型顏色;null 值會重設顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Color Objects(colors)
設定字型顏色的矩形格線 (必須與此範圍的尺寸相符)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const colorAccent1 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1) .build(); const colorAccent2 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2) .build(); const colorAccent3 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3) .build(); const colorAccent4 = SpreadsheetApp.newColor() .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4) .build(); const colors = [ [colorAccent1, colorAccent2], [colorAccent3, colorAccent4], ]; const cell = sheet.getRange('B5:C6'); cell.setFontColorObjects(colors);
參數
名稱 | 類型 | 說明 |
---|---|---|
colors | Color[][] | 二維顏色陣列;null 值會重設字型顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Colors(colors)
設定矩形格狀的字型顏色 (必須符合此範圍的尺寸)。顏色會以 CSS 符號表示 (例如 '#ffffff'
或 'white'
)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const colors = [ ['red', 'white', 'blue'], ['#FF0000', '#FFFFFF', '#0000FF'], // These are the hex equivalents ]; const cell = sheet.getRange('B5:D6'); cell.setFontColors(colors);
參數
名稱 | 類型 | 說明 |
---|---|---|
colors | Object[][] | CSS 符號 (例如 '#ffffff' 或 'white' ) 中的二維陣列顏色;null 值會重設顏色。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Families(fontFamilies)
設定字型系列的矩形格線 (必須符合此範圍的尺寸)。字型系列的例子包括「Arial」或「Helvetica」。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const fonts = [ ['Arial', 'Helvetica', 'Verdana'], ['Courier New', 'Arial', 'Helvetica'], ]; const cell = sheet.getRange('B2:D3'); cell.setFontFamilies(fonts);
參數
名稱 | 類型 | 說明 |
---|---|---|
font | Object[][] | 字型系列的二維陣列;null 值會重設字型系列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Family(fontFamily)
設定字型系列,例如「Arial」或「Helvetica」。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setFontFamily('Helvetica');
參數
名稱 | 類型 | 說明 |
---|---|---|
font | String | 要設定的字型系列;null 值會重設字型系列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Line(fontLine)
設定指定範圍的字型線條樣式 ('underline'
、'line-through'
或 'none'
)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setFontLine('line-through');
參數
名稱 | 類型 | 說明 |
---|---|---|
font | String | 字型線條樣式,可選 'underline' 、'line-through' 或 'none' ;null 值會重設字型線條樣式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Lines(fontLines)
設定線條樣式的矩形格線 (必須符合此範圍的尺寸)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const fontLines = [['underline', 'line-through', 'none']]; const range = sheet.getRange('B2:D2'); range.setFontLines(fontLines);
參數
名稱 | 類型 | 說明 |
---|---|---|
font | Object[][] | 字型線條樣式的二維陣列 ('underline' 、'line-through' 或 'none' );null 值會重設字型線條樣式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Size(size)
設定字型大小,大小為要使用的點大小。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setFontSize(20);
參數
名稱 | 類型 | 說明 |
---|---|---|
size | Integer | 以點為單位的字型大小。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Sizes(sizes)
設定矩形格狀的字型大小 (必須符合此範圍的尺寸)。尺寸以點為單位。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const fontSizes = [[16, 20, 24]]; const range = sheet.getRange('B2:D2'); range.setFontSizes(fontSizes);
參數
名稱 | 類型 | 說明 |
---|---|---|
sizes | Object[][] | 尺寸的二維陣列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Style(fontStyle)
為指定範圍 ('italic'
或 'normal'
) 設定字型樣式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setFontStyle('italic');
參數
名稱 | 類型 | 說明 |
---|---|---|
font | String | 字型樣式,為 'italic' 或 'normal' ;null 值會重設字型樣式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Styles(fontStyles)
設定矩形的字型樣式格線 (必須符合此範圍的尺寸)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const fontStyles = [['italic', 'normal']]; const range = sheet.getRange('B2:C2'); range.setFontStyles(fontStyles);
參數
名稱 | 類型 | 說明 |
---|---|---|
font | Object[][] | 字型樣式的二維陣列,可為 'italic' 或 'normal' ;null 值會重設字型樣式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Weight(fontWeight)
設定指定範圍的字型粗細 (一般/粗體)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setFontWeight('bold');
參數
名稱 | 類型 | 說明 |
---|---|---|
font | String | 字型粗細,可為 'bold' 或 'normal' ;null 值會重設字型粗細。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Font Weights(fontWeights)
設定字型粗細的矩形格線 (必須符合此範圍的尺寸)。字型粗細的範例為「粗體」。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const fontStyles = [['bold', 'bold', 'normal']]; const range = sheet.getRange('B2:D2'); range.setFontWeights(fontStyles);
參數
名稱 | 類型 | 說明 |
---|---|---|
font | Object[][] | 字型粗細的二維陣列,可為 'bold' 或 'normal' ;null 值會重設字型粗細。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Formula(formula)
更新這個範圍的公式。給定的公式必須採用 A1 符號。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B5'); cell.setFormula('=SUM(B3:B4)');
參數
名稱 | 類型 | 說明 |
---|---|---|
formula | String | 代表要為儲存格設定的公式的字串。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Formula R1C1(formula)
更新這個範圍的公式。給定的公式必須採用 R1C1 符號。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B5'); // This sets the formula to be the sum of the 3 rows above B5 cell.setFormulaR1C1('=SUM(R[-3]C[0]:R[-1]C[0])');
參數
名稱 | 類型 | 說明 |
---|---|---|
formula | String | 字串公式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Formulas(formulas)
設定公式的矩形格狀 (必須符合此範圍的維度)。提供的公式必須採用 A1 符號。這個方法會採用公式的二維陣列,並依序以資料列和資料欄編號。陣列維度必須與範圍維度相符。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // This sets the formulas to be a row of sums, followed by a row of averages // right below. The size of the two-dimensional array must match the size of the // range. const formulas = [ ['=SUM(B2:B4)', '=SUM(C2:C4)', '=SUM(D2:D4)'], ['=AVERAGE(B2:B4)', '=AVERAGE(C2:C4)', '=AVERAGE(D2:D4)'], ]; const cell = sheet.getRange('B5:D6'); cell.setFormulas(formulas);
參數
名稱 | 類型 | 說明 |
---|---|---|
formulas | String[][] | 公式的二維字串陣列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Formulas R1C1(formulas)
設定公式的矩形格狀 (必須符合此範圍的維度)。給定的公式必須採用 R1C1 符號。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // This creates formulas for a row of sums, followed by a row of averages. const sumOfRowsAbove = '=SUM(R[-3]C[0]:R[-1]C[0])'; const averageOfRowsAbove = '=AVERAGE(R[-4]C[0]:R[-2]C[0])'; // The size of the two-dimensional array must match the size of the range. const formulas = [ [sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove], [averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove], ]; const cell = sheet.getRange('B5:D6'); // This sets the formula to be the sum of the 3 rows above B5. cell.setFormulasR1C1(formulas);
參數
名稱 | 類型 | 說明 |
---|---|---|
formulas | String[][] | 以 R1C1 格式呈現的公式二維陣列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Horizontal Alignment(alignment)
為指定範圍 (左/置中/右) 設定水平 (由左至右) 對齊方式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setHorizontalAlignment('center');
參數
名稱 | 類型 | 說明 |
---|---|---|
alignment | String | 對齊方式 ('left' 、'center' 或 'normal' );null 值會重設對齊方式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Horizontal Alignments(alignments)
設定水平對齊的矩形格線。請參閱 set
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const horizontalAlignments = [['left', 'right', 'center']]; const range = sheet.getRange('B2:D2'); range.setHorizontalAlignments(horizontalAlignments);
參數
名稱 | 類型 | 說明 |
---|---|---|
alignments | Object[][] | 對齊方式的二維陣列,可為 'left' 、'center' 或 'normal' ;null 值會重設對齊方式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
set Note(note)
將筆記設為指定的值。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setNote('This is a note');
參數
名稱 | 類型 | 說明 |
---|---|---|
note | String | 要為範圍設定的註解值;null 值會移除註解。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Notes(notes)
設定矩形的筆記格狀 (必須符合此範圍的尺寸)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const notes = [ ['it goes', 'like this', 'the fourth, the fifth'], ['the minor fall', 'and the', 'major lift'], ]; const cell = sheet.getRange('B2:D3'); cell.setNotes(notes);
參數
名稱 | 類型 | 說明 |
---|---|---|
notes | Object[][] | 筆記的二維陣列;null 值會移除筆記。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
set Number Format(numberFormat)
將數字或日期格式設為指定的格式字串。Sheets API 說明文件說明瞭可接受的格式模式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); // Always show 3 decimal points cell.setNumberFormat('0.000');
參數
名稱 | 類型 | 說明 |
---|---|---|
number | String | 數字格式字串。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Number Formats(numberFormats)
設定數字或日期格式的矩形格狀 (必須符合此範圍的尺寸)。這些值是格式模式字串,如 Sheets API 說明文件所述。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const formats = [['0.000', '0,000,000', '$0.00']]; const range = sheet.getRange('B2:D2'); range.setNumberFormats(formats);
參數
名稱 | 類型 | 說明 |
---|---|---|
number | Object[][] | 數字格式的二維陣列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Rich Text Value(value)
為範圍內的儲存格設定 RTF 格式值。
// Sets all cells in range B2:D4 to have the text "Hello world", with "Hello" // bolded. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B2:D4'); const bold = SpreadsheetApp.newTextStyle().setBold(true).build(); const richText = SpreadsheetApp.newRichTextValue() .setText('Hello world') .setTextStyle(0, 5, bold) .build(); range.setRichTextValue(richText);
參數
名稱 | 類型 | 說明 |
---|---|---|
value | Rich | 所需的 RTF 格式值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Rich Text Values(values)
設定 RTF 格式值的矩形格狀。
// Sets the cells in range A1:A2 to have Rich Text values. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('A1:A2'); const bold = SpreadsheetApp.newTextStyle().setBold(true).build(); const italic = SpreadsheetApp.newTextStyle().setItalic(true).build(); const richTextA1 = SpreadsheetApp.newRichTextValue() .setText('This cell is bold') .setTextStyle(bold) .build(); const richTextA2 = SpreadsheetApp.newRichTextValue() .setText('bold words, italic words') .setTextStyle(0, 11, bold) .setTextStyle(12, 24, italic) .build(); range.setRichTextValues([[richTextA1], [richTextA2]]);
參數
名稱 | 類型 | 說明 |
---|---|---|
values | Rich | 所需的 RTF 格式值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Show Hyperlink(showHyperlink)
設定範圍是否應顯示超連結。
// Opens the spreadsheet file by its URL. If you created your script from within // a Google Sheets file, you can useSpreadsheetApp.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 A30 and sets its hyperlink value. const range = sheet.getRange('A30'); range.setValue('https://www.example.com'); // Sets cell A30 to show hyperlinks. range.setShowHyperlink(true);
參數
名稱 | 類型 | 說明 |
---|---|---|
show | Boolean | 是否顯示超連結。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Direction(direction)
設定指定範圍內的儲存格文字方向。如果指定的方向為 null
,系統會推斷方向,然後進行設定。
// Sets right-to-left text direction for the range. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B5:C6'); range.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);
參數
名稱 | 類型 | 說明 |
---|---|---|
direction | Text | 所需的文字方向;如果為 null ,系統會在設定前推斷方向。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Directions(directions)
設定文字方向的矩形網格。如果指定的方向為 null
,系統會推斷方向,然後進行設定。
// Copies all of the text directions from range A1:B2 over to range C5:D6. const sheet = SpreadsheetApp.getActiveSheet(); const range1 = sheet.getRange('A1:B2'); const range2 = sheet.getRange('C5:D6'); range2.setTextRotations(range1.getTextDirections());
參數
名稱 | 類型 | 說明 |
---|---|---|
directions | Text | 所需的文字方向。如果指定的方向為 null ,系統會在設定前推斷。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Rotation(degrees)
為指定範圍中的儲存格設定文字旋轉設定。輸入值對應於標準文字方向和所需方向之間的角度。如果輸入值為零,表示文字已設為標準方向。
如果文字方向是從左到右,正角度會以逆時針方向計算,如果文字方向是從右到左,則會以順時針方向計算。
// Sets all cell's in range B2:D4 to have text rotated up 45 degrees. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B2:D4'); range.setTextRotation(45);
參數
名稱 | 類型 | 說明 |
---|---|---|
degrees | Integer | 標準方向和所需方向之間的角度。對於從左到右的文字,正角度為逆時針方向。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Rotation(rotation)
為指定範圍中的儲存格設定文字旋轉角度。
// Sets all cell's in range B2:D4 to have the same text rotation settings as // cell A1. const sheet = SpreadsheetApp.getActiveSheet(); const rotation = sheet.getRange('A1').getTextRotation(); sheet.getRange('B2:D4').setTextRotation(rotation);
參數
名稱 | 類型 | 說明 |
---|---|---|
rotation | Text | 所需的文字旋轉設定。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Rotations(rotations)
設定文字旋轉的矩形格線。
// Copies all of the text rotations from range A1:B2 over to range C5:D6. const sheet = SpreadsheetApp.getActiveSheet(); const range1 = sheet.getRange('A1:B2'); const range2 = sheet.getRange('C5:D6'); range2.setTextRotations(range1.getTextRotations());
參數
名稱 | 類型 | 說明 |
---|---|---|
rotations | Text | 所需的文字旋轉設定。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Style(style)
設定指定範圍內儲存格文字的樣式。
// Sets the cells in range C5:D6 to have underlined size 15 font. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('C5:D6'); const style = SpreadsheetApp.newTextStyle().setFontSize(15).setUnderline(true).build(); range.setTextStyle(style);
參數
名稱 | 類型 | 說明 |
---|---|---|
style | Text | 所需的文字樣式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Text Styles(styles)
設定文字樣式的矩形格線。
// Sets text styles for cells in range A1:B2 const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('A1:B2'); const bold = SpreadsheetApp.newTextStyle().setBold(true).build(); const otherStyle = SpreadsheetApp.newTextStyle() .setBold(true) .setUnderline(true) .setItalic(true) .setForegroundColor('#335522') .setFontSize(44) .build(); range.setTextStyles([ [bold, otherStyle], [otherStyle, bold], ]);
參數
名稱 | 類型 | 說明 |
---|---|---|
styles | Text | 所需的文字樣式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Value(value)
設定範圍的值。值可以是數字、字串、布林值或日期。如果開頭為 '='
,系統會將其解讀為公式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setValue(100);
參數
名稱 | 類型 | 說明 |
---|---|---|
value | Object | 範圍的值。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Values(values)
設定矩形值格狀圖 (必須符合此範圍的維度)。如果值的開頭是 =
,系統會將其解讀為公式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const values = [['2.000', '1,000,000', '$2.99']]; const range = sheet.getRange('B2:D2'); range.setValues(values);
參數
名稱 | 類型 | 說明 |
---|---|---|
values | Object[][] | 值的二維陣列。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Vertical Alignment(alignment)
為指定範圍 (頂端/中間/底部) 設定垂直 (由上至下) 對齊方式。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setVerticalAlignment('middle');
參數
名稱 | 類型 | 說明 |
---|---|---|
alignment | String | 對齊方式 ('top' 、'middle' 或 'bottom' );null 值會重設對齊方式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Vertical Alignments(alignments)
設定垂直對齊的矩形格線 (必須符合此範圍的尺寸)。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const alignments = [['top', 'middle', 'bottom']]; const range = sheet.getRange('B2:D2'); range.setVerticalAlignments(alignments);
參數
名稱 | 類型 | 說明 |
---|---|---|
alignments | Object[][] | 對齊方式的二維陣列,可為 'top' 、'middle' 或 'bottom' ;null 值會重設對齊方式。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
set Vertical Text(isVertical)
設定是否要為範圍內的儲存格堆疊文字。如果文字是垂直堆疊,系統會忽略文字旋轉角度設定。
// Sets all cell's in range B2:D4 to have vertically stacked text. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B2:D4'); range.setVerticalText(true);
參數
名稱 | 類型 | 說明 |
---|---|---|
is | Boolean | 是否要堆疊文字。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Wrap(isWrapEnabled)
設定指定範圍的單元格換行。
啟用自動換行功能 (預設) 的儲存格會調整大小,以便顯示完整內容。停用自動換行的儲存格會盡可能在儲存格中顯示內容,不會調整大小或延伸至多行。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const cell = sheet.getRange('B2'); cell.setWrap(true);
參數
名稱 | 類型 | 說明 |
---|---|---|
is | Boolean | 是否要換行文字。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Wrap Strategies(strategies)
設定矩形網格的包覆策略。
// Copies all of the wrap strategies from range A1:B2 over to range C5:D6. const sheet = SpreadsheetApp.getActiveSheet(); const range1 = sheet.getRange('A1:B2'); const range2 = sheet.getRange('C5:D6'); range2.setWrapStrategies(range1.getWrapStrategies());
參數
名稱 | 類型 | 說明 |
---|---|---|
strategies | Wrap | 所需的換行策略。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Wrap Strategy(strategy)
為指定範圍內的儲存格設定文字斷行策略。
// Sets all cells in range B2:D4 to use the clip wrap strategy. const sheet = SpreadsheetApp.getActiveSheet(); const range = sheet.getRange('B2:D4'); range.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);
參數
名稱 | 類型 | 說明 |
---|---|---|
strategy | Wrap | 所需的換行策略。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
set Wraps(isWrapEnabled)
設定文字斷行政策的矩形格線 (必須符合此範圍的尺寸)。啟用自動換行功能 (預設) 的儲存格會調整大小,以便顯示完整內容。停用自動換行的儲存格會盡可能在儲存格中顯示內容,不會調整大小或延伸至多行。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; // The size of the two-dimensional array must match the size of the range. const wraps = [[true, true, false]]; const range = sheet.getRange('B2:D2'); range.setWraps(wraps);
參數
名稱 | 類型 | 說明 |
---|---|---|
is | Object[][] | 兩維陣列的環繞變數,用於判斷是否要將文字環繞在儲存格中。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
另請參閱
shift Column Group Depth(delta)
以指定的幅度變更範圍的欄群組深度。
這會產生建立、修改或刪除與範圍重疊的群組的效果。如果是正值差異,系統會建立及/或修改群組;如果是負值差異,系統會刪除及/或修改群組。
如果將群組深度調降至低於零或高於八,這項設定就不會生效。
如果 column group control position
是 BEFORE
,則在嘗試轉移第一列的深度時會擲回錯誤。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getActiveRange(); // The column grouping depth is increased by 1. range.shiftColumnGroupDepth(1); // The column grouping depth is decreased by 1. range.shiftColumnGroupDepth(-1);
參數
名稱 | 類型 | 說明 |
---|---|---|
delta | Integer | 變更這個範圍的欄群組深度。 |
回攻員
Range
:這個範圍,用於鏈結。
擲回
Error
:當控制位置為 Group
時,嘗試變更第一欄的深度
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
shift Row Group Depth(delta)
以指定的幅度變更範圍的列分組深度。
這會產生建立、修改或刪除與範圍重疊的群組的效果。如果是正值差異,系統會建立及/或修改群組;如果是負值差異,系統會刪除及/或修改群組。
如果將群組深度調降至低於零或高於八,這項設定就不會生效。
如果 row group control position
是 BEFORE
,則在嘗試轉移第一列的深度時會擲回錯誤。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getActiveRange(); // The row grouping depth is increased by 1. range.shiftRowGroupDepth(1); // The row grouping depth is decreased by 1. range.shiftRowGroupDepth(-1);
參數
名稱 | 類型 | 說明 |
---|---|---|
delta | Integer | 這個範圍的列群組深度變更量。 |
回攻員
Range
:這個範圍,用於鏈結。
擲回
Error
- 當控制項位置為 Group
時,嘗試變更第一列的深度
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
sort(sortSpecObj)
依指定的資料欄和順序,排序指定範圍內的儲存格。
const ss = SpreadsheetApp.getActiveSpreadsheet(); const sheet = ss.getSheets()[0]; const range = sheet.getRange('A1:C7'); // Sorts by the values in the first column (A) range.sort(1); // Sorts by the values in the second column (B) range.sort(2); // Sorts descending by column B range.sort({column: 2, ascending: false}); // Sorts descending by column B, then ascending by column A // Note the use of an array range.sort([ {column: 2, ascending: false}, {column: 1, ascending: true}, ]); // For rows that are sorted in ascending order, the "ascending" parameter is // optional, and just an integer with the column can be used instead. Note that // in general, keeping the sort specification consistent results in more // readable code. You can express the earlier sort as: range.sort([{column: 2, ascending: false}, 1]); // Alternatively, if you want all columns to be in ascending order, you can use // the following (this makes column 2 ascending) range.sort([2, 1]); // ... which is equivalent to range.sort([ {column: 2, ascending: true}, {column: 1, ascending: true}, ]);
參數
名稱 | 類型 | 說明 |
---|---|---|
sort | Object | 要依據的資料欄。 |
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
split Text To Columns()
根據自動偵測的分隔符號,將一欄文字分割為多個資料欄。
// A1:A3 has the following values: // A B C // 1 |one,one,one | | | // 2 |two,two,two | | | // 3 |three,three,three| | | const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3'); range.splitTextToColumns(); // Result after splitting the text to columns: // A B C // 1 |one |one |one | // 2 |two |two |two | // 3 |three |three |three |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
split Text To Columns(delimiter)
使用指定的字串做為自訂分隔符號,將一欄文字分割為多個資料欄。
// A1:A3 has the following values: // A B C // 1 |one#one#one | | | // 2 |two#two#two | | | // 3 |three#three#three| | | const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3'); range.splitTextToColumns('#'); // Result after splitting the text to columns: // A B C // 1 |one |one |one | // 2 |two |two |two | // 3 |three |three |three |
參數
名稱 | 類型 | 說明 |
---|---|---|
delimiter | String | 要用來分割的自訂分隔符號。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
split Text To Columns(delimiter)
根據指定的分隔符號,將一欄文字分割為多個資料欄。
// A1:A3 has the following values: // A B C // 1 |one;one;one | | | // 2 |two;two;two | | | // 3 |three;three;three| | | const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3'); range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON); // Result after splitting the text to columns: // A B C // 1 |one |one |one | // 2 |two |two |two | // 3 |three |three |three |
參數
名稱 | 類型 | 說明 |
---|---|---|
delimiter | Text | 要用來分割的預設分隔符號。 |
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
trim Whitespace()
會修剪指定範圍內每個儲存格中的空白字元 (例如空格、Tab 或換行符號)。移除每個儲存格文字開頭和結尾的所有空格,並將任何剩餘空格字元的子序減為單一空格。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0]; const range = sheet.getRange('A1:A4'); range.activate(); range.setValues([ ' preceding space', 'following space ', 'two middle spaces', ' =SUM(1,2)', ]); range.trimWhitespace(); const values = range.getValues(); // Values are ['preceding space', 'following space', 'two middle spaces', // '=SUM(1,2)']
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
uncheck()
將範圍內的核取方塊狀態變更為「未勾選」。忽略目前不含已勾選或未勾選值的範圍內儲存格。
// Changes the state of cells which currently contain either the checked or // unchecked value configured in the range A1:B10 to 'unchecked'. const range = SpreadsheetApp.getActive().getRange('A1:B10'); range.uncheck();
回攻員
Range
:這個範圍,用於鏈結。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets