存取及修改試算表區間。範圍可以是工作表中的單一儲存格，也可以是工作表中一組相鄰的儲存格。
方法
已淘汰的方法
| 方法 | 傳回類型 | 簡短說明 |
|---|---|---|
| String | 以 CSS 符號 (例如 '#ffffff' 或 'white') 的形式，傳回範圍左上角儲存格的字型顏色。 |
| String[][] | 以 CSS 符號 (例如 '#ffffff' 或 'white') 傳回指定範圍內儲存格的字型顏色。 |
內容詳盡的說明文件
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：這個範圍，用於鏈結。
activateAsCurrentCell()
將指定的儲存格設為 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
addDeveloperMetadata(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
addDeveloperMetadata(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
addDeveloperMetadata(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
addDeveloperMetadata(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
applyColumnBanding()
將預設的欄帶主題套用至指定範圍。根據預設，分割帶有頁首，但沒有頁尾顏色。
// 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
applyColumnBanding(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
applyColumnBanding(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
applyRowBanding()
將預設的列分割主題套用至指定範圍。根據預設，分割帶有頁首，但沒有頁尾顏色。
// 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
applyRowBanding(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
applyRowBanding(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
autoFill(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
autoFillToNeighbor(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
breakApart()
再次將範圍內的任何多欄儲存格拆分為個別儲存格。
在指定範圍上呼叫這個函式，等同於選取範圍，然後依序點選「格式」>「合併儲存格」>「取消合併」。
// 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
canEdit()
判斷使用者是否有權編輯該範圍中的每個儲存格。試算表擁有者一律可以編輯受保護的範圍和試算表。
// 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()
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
clearContent()
清除指定範圍的內容，但保留格式設定。
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
clearDataValidations()
清除指定範圍的資料驗證規則。
// 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
clearFormat()
清除這個範圍的格式。
這會清除範圍內儲存格或儲存格的文字格式，但不會重設任何數字格式規則。
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
clearNote()
清除指定儲存格或儲存格中的備註。
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
collapseGroups()
收合完全包含在範圍內的所有群組。如果沒有任何群組完全位於範圍內，系統會收合部分位於範圍內的展開最深層的群組。
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
copyFormatToRange(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
另請參閱
copyFormatToRange(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
copyTo(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
copyTo(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
copyTo(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
copyValuesToRange(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
另請參閱
copyValuesToRange(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
createDataSourcePivotTable(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
createDataSourceTable(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
createDeveloperMetadataFinder()
傳回 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：開發人員中繼資料搜尋工具，可搜尋這個範圍內的中繼資料。
createFilter()
建立篩選器，並套用至工作表的指定範圍。你無法在工作表中建立多個篩選器。如要在建立篩選器後存取及修改篩選器，請使用 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
createPivotTable(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
createTextFinder(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
deleteCells(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
expandGroups()
展開範圍或控制切換按鈕與此範圍相交的收合群組。控制切換鈕的位置是顯示控制切換鈕的索引，視設定而定，可能會直接放在群組前或後。如果同一個位置有兩個以上的群組，系統會展開最淺的群組。
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
getBackground()
傳回指定範圍 (例如 '#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
getBackgroundObject()
傳回指定範圍中左上方儲存格的背景顏色。
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
getBackgroundObjects()
傳回指定範圍內儲存格的背景顏色。
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
getBackgrounds()
傳回範圍內儲存格的背景顏色 (例如 '#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
getBandings()
傳回套用至此範圍內任何儲存格的所有區塊。
// 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
getCell(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
getColumn()
傳回此範圍的起始欄位置。
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
getDataRegion()
傳回在四個主要 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
getDataRegion(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
getDataSourceFormula()
傳回範圍中第一個儲存格的 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
getDataSourceFormulas()
傳回範圍內儲存格中的 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
getDataSourcePivotTables()
取得與指定範圍相交的所有資料來源資料透視表。
// 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
getDataSourceTables()
取得與指定範圍相交的所有資料來源資料表。
// 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
getDataSourceUrl()
傳回這個範圍內資料的網址，可用於建立圖表和查詢。
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();
}
<!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
getDataTable()
將這個物件內的資料做為 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：資料為資料表格。
getDataTable(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
getDataValidation()
傳回指定範圍中左上方儲存格的資料驗證規則。如果儲存格尚未設定資料驗證，這個方法會傳回 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
getDataValidations()
傳回指定範圍內所有儲存格的資料驗證規則。如果未在特定儲存格上設定資料驗證，這個方法會針對該儲存格在陣列中的位置傳回 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
getDeveloperMetadata()
取得與此範圍相關聯的開發人員中繼資料。
// 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
getDisplayValue()
傳回範圍中左上角儲存格的顯示值。值為 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
getDisplayValues()
傳回這個範圍的值矩形格線。
傳回顯示值的二維陣列，並以列為索引，然後以欄為索引。這些值是 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
getFilter()
傳回此範圍所屬工作表的篩選器，如果工作表上沒有篩選器，則傳回 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
getFontColorObject()
傳回指定範圍左上角儲存格的字型顏色。
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
getFontColorObjects()
傳回指定範圍內儲存格的字型顏色。
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
getFontFamilies()
傳回指定範圍內儲存格的字型系列。
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
getFontFamily()
傳回指定範圍左上角儲存格中的字型系列。
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
getFontLine()
取得範圍左上角儲存格 ('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
getFontLines()
取得範圍內儲存格的線條樣式 ('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
getFontSize()
傳回範圍左上角儲存格字型大小的點大小。
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
getFontSizes()
傳回指定範圍內儲存格的字型大小。
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
getFontStyle()
傳回範圍左上角儲存格的字型樣式 ('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
getFontStyles()
傳回指定範圍內儲存格的字型樣式。
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
getFontWeight()
傳回指定範圍左上角儲存格的字型粗細 (一般/粗體)。
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
getFontWeights()
傳回指定範圍內儲存格字型的粗細。
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
getFormula()
傳回指定範圍左上角儲存格的公式 (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
getFormulaR1C1()
傳回指定儲存格中的公式 (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
getFormulas()
傳回範圍內儲存格中的公式 (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
getFormulasR1C1()
傳回範圍內儲存格中的公式 (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
getGridId()
傳回範圍父工作表的格狀 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
getHeight()
傳回範圍的高度。
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
getHorizontalAlignment()
傳回指定範圍左上角儲存格文字的水平對齊方式 (左/置中/右)。
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
getHorizontalAlignments()
傳回範圍內儲存格水平對齊方式。
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
getLastColumn()
傳回結束欄位。
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
getLastRow()
傳回結束列位置。
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
getMergedRanges()
傳回 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());
}
回攻員
getNextDataCell(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
getNote()
傳回與指定範圍相關聯的附註。
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
getNotes()
傳回與範圍內儲存格相關聯的備註。
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
getNumColumns()
傳回這個範圍內的欄數。
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
getNumRows()
傳回這個範圍內的列數。
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
getNumberFormat()
取得指定範圍左上方儲存格的數字或日期格式。如要瞭解傳回的格式模式，請參閱 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
getNumberFormats()
傳回指定範圍內儲存格中的數字或日期格式。如需瞭解傳回的格式模式，請參閱 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
getRichTextValue()
傳回指定範圍左上角儲存格的富文字值，如果儲存格值不是文字，則傳回 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
getRichTextValues()
傳回範圍內儲存格中的 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
getRow()
傳回此範圍的列位置。與 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
getRowIndex()
傳回此範圍的列位置。與 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
另請參閱
getSheet()
傳回這個範圍所屬的工作表。
// 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
getTextDirection()
傳回指定範圍左上方儲存格的文字方向。如果使用自動偵測功能判斷儲存格文字方向，則傳回 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
getTextDirections()
傳回指定範圍內儲存格中的文字方向。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
getTextRotation()
傳回指定範圍左上方儲存格的文字旋轉設定。
// 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
getTextRotations()
傳回指定範圍內儲存格文字旋轉設定。
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
getTextStyle()
傳回指定範圍左上角儲存格的文字樣式。
// 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
getTextStyles()
傳回指定範圍內儲存格使用的文字樣式。
// 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
getValue()
傳回範圍中左上角儲存格的值。這個值的類型可能為 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
getValues()
傳回這個範圍的值矩形格線。
傳回值的二維陣列，以列為索引，然後以欄為索引。這些值的類型可能為 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 值的儲存格，getValues() 就無法將資料傳回至網頁應用程式。請改為將從工作表擷取的所有值轉換為支援的 JavaScript 原始值，例如 Number、Boolean 或 String。回攻員
Object[][]：值的二維陣列。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getVerticalAlignment()
傳回指定區間左上角儲存格垂直對齊方式 (頂端/中間/底部)。
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
getVerticalAlignments()
傳回範圍內儲存格的垂直對齊方式。
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
getWidth()
傳回範圍在資料欄中的寬度。
// 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
getWrap()
傳回儲存格中的文字是否會換行。如需更精細的包裝策略，請使用 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
getWrapStrategies()
傳回範圍內儲存格適用的文字斷行策略。
// 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
getWrapStrategy()
傳回指定範圍左上角儲存格的文字斷行策略。
// 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
getWraps()
傳回儲存格中的文字是否會換行。如需更精細的包裝策略，請使用 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
insertCells(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
insertCheckboxes()
在範圍內的每個儲存格中插入核取方塊，並以 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
insertCheckboxes(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
insertCheckboxes(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
isBlank()
如果範圍完全空白，就會傳回 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
isChecked()
傳回範圍內所有儲存格的核取方塊狀態是否為「已勾選」。如果部分儲存格已勾選，而其餘儲存格未勾選，或部分儲存格沒有核取方塊資料驗證，則會傳回 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
isEndColumnBounded()
判斷範圍的結尾是否已繫結至特定欄。舉例來說，如果範圍 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
isEndRowBounded()
判斷範圍的結尾是否已繫結至特定資料列。舉例來說，如果範圍 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
isPartOfMerge()
如果目前範圍內的儲存格與任何合併儲存格重疊，就會傳回 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。
isStartColumnBounded()
判斷範圍的起始值是否已繫結至特定欄。舉例來說，如果範圍 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
isStartRowBounded()
判斷範圍的起始值是否已繫結至特定資料列。舉例來說，如果範圍 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
mergeAcross()
合併範圍內的儲存格，並跨越範圍內的資料欄。
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
mergeVertically()
將範圍內的儲存格合併。
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
moveTo(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
removeCheckboxes()
從指定範圍移除所有核取方塊。清除每個儲存格的資料驗證，如果儲存格含有勾選或未勾選的值，則一併清除其值。
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
removeDuplicates()
移除此範圍內的資料列，如果其中的值與任何前一個資料列的值重複，就會遭到移除。只要資料列中的值相同，系統就會視其為重複項目，即使字母大小寫、格式或公式不同亦然。這個方法也會移除隱藏在檢視畫面中的重複資料列 (例如因篩選器而隱藏的資料列)。超出這個範圍的內容不會遭到移除。
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
removeDuplicates(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
setBackground(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
setBackgroundObject(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
setBackgroundObjects(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
setBackgroundRGB(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
setBackgrounds(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
setBorder(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
setBorder(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
setDataValidation(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
setDataValidations(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
setFontColor(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
setFontColorObject(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
setFontColorObjects(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
setFontColors(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
setFontFamilies(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
setFontFamily(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
setFontLine(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
setFontLines(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
setFontSize(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
setFontSizes(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
setFontStyle(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
setFontStyles(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
setFontWeight(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
setFontWeights(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
setFormula(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
setFormulaR1C1(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
setFormulas(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
setFormulasR1C1(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
setHorizontalAlignment(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
setHorizontalAlignments(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
另請參閱
setNote(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
setNotes(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
另請參閱
setNumberFormat(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
setNumberFormats(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
setRichTextValue(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
setRichTextValues(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
setShowHyperlink(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
setTextDirection(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
setTextDirections(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
setTextRotation(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
setTextRotation(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
setTextRotations(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
setTextStyle(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
setTextStyles(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
setValue(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
setValues(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
setVerticalAlignment(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
setVerticalAlignments(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
另請參閱
setVerticalText(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
setWrap(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
setWrapStrategies(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
setWrapStrategy(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
setWraps(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
另請參閱
shiftColumnGroupDepth(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
shiftRowGroupDepth(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
splitTextToColumns()
根據自動偵測的分隔符號，將一欄文字分割為多個資料欄。
// 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
splitTextToColumns(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
splitTextToColumns(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
trimWhitespace()
會修剪指定範圍內每個儲存格中的空白字元 (例如空格、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
已淘汰的方法
getFontColor()
getFontColor()
已淘汰。已替換為 get
以 CSS 符號 (例如 '#ffffff' 或 'white') 的形式，傳回範圍左上角儲存格的字型顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontColor());
回攻員
String：CSS 符號中的字型顏色 (例如 '#ffffff' 或 'white')。
授權
使用這個方法的腳本需要具備下列一或多個範圍的授權：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontColors()
getFontColors()
已淘汰。已替換為 get
以 CSS 符號 (例如 '#ffffff' 或 'white') 傳回範圍內儲存格的字型顏色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontColors();
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