Class DataSourceSheet

数据源工作表

访问和修改现有数据源工作表。如需创建新的数据源工作表，请使用 Spreadsheet.insertDataSourceSheet(spec)。

仅将此类用于与数据库关联的数据。

方法

方法	返回类型	简介
addFilter(columnName, filterCriteria)	DataSourceSheet	添加应用于数据源工作表的过滤条件。
asSheet()	Sheet	将数据源工作表作为常规工作表对象返回。
autoResizeColumn(columnName)	DataSourceSheet	自动调整指定列的宽度。
autoResizeColumns(columnNames)	DataSourceSheet	自动调整指定列的宽度。
cancelDataRefresh()	DataSourceSheet	取消与此对象关联的数据刷新（如果当前正在运行）。
forceRefreshData()	DataSourceSheet	刷新此对象的数据，无论当前状态如何。
getColumnWidth(columnName)	Integer	返回指定列的宽度。
getDataSource()	DataSource	获取对象关联的数据源。
getFilters()	DataSourceSheetFilter[]	返回应用于数据源工作表的所有过滤条件。
getSheetValues(columnName)	Object[]	返回指定列名称的数据源工作表的所有值。
getSheetValues(columnName, startRow, numRows)	Object[]	返回指定数据源工作表中指定列名称的所有值，从指定的起始行（从 1 开始）到指定的 numRows。
getSortSpecs()	SortSpec[]	获取数据源工作表中的所有排序规范。
getStatus()	DataExecutionStatus	获取对象的数据执行状态。
refreshData()	DataSourceSheet	刷新对象的数据。
removeFilters(columnName)	DataSourceSheet	移除应用于数据源工作表列的所有过滤条件。
removeSortSpec(columnName)	DataSourceSheet	移除数据源工作表中列的排序规范。
setColumnWidth(columnName, width)	DataSourceSheet	设置指定列的宽度。
setColumnWidths(columnNames, width)	DataSourceSheet	设置指定列的宽度。
setSortSpec(columnName, ascending)	DataSourceSheet	设置数据源工作表中列的排序规范。
setSortSpec(columnName, sortOrder)	DataSourceSheet	设置数据源工作表中列的排序规范。
waitForCompletion(timeoutInSeconds)	DataExecutionStatus	等待当前执行操作完成，并在提供的秒数后超时。

详细文档

addFilter(columnName, filterCriteria)

添加应用于数据源工作表的过滤条件。

参数

名称	类型	说明
columnName	String	要应用此过滤条件的列的名称。
filterCriteria	FilterCriteria	要应用的过滤条件。

返回

DataSourceSheet - 数据源工作表，用于方法链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

asSheet()

将数据源工作表作为常规工作表对象返回。

返回

Sheet - 常规工作表。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

autoResizeColumn(columnName)

自动调整指定列的宽度。

参数

名称	类型	说明
columnName	String	列名称。

返回

DataSourceSheet - 此数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

autoResizeColumns(columnNames)

自动调整指定列的宽度。

参数

名称	类型	说明
columnNames	String[]	要更新的列名称的列表。

返回

DataSourceSheet - 此数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

cancelDataRefresh()

取消与此对象关联的数据刷新（如果当前正在运行）。

以下示例展示了如何取消公式刷新。

const spreadsheet = SpreadsheetApp.getActive();
const formula = spreadsheet.getDataSourceFormulas()[0];
// Cancel the ongoing refresh on the formula.
formula.cancelDataRefresh();

如果数据源类型未启用，则会抛出异常。使用 SpreadsheetApp#enable...Execution() 方法为特定数据源类型启用数据执行。

返回

DataSourceSheet - 数据对象。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

forceRefreshData()

无论当前状态如何，都会刷新此对象的数据。如需了解详情，请参阅 refreshData()。如果您想取消当前正在运行的此对象刷新，请参阅 cancelDataRefresh()。

如果数据源类型未启用，则会抛出异常。使用 SpreadsheetApp#enable...Execution() 方法为特定数据源类型启用数据执行。

返回

DataSourceSheet - 数据对象。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getColumnWidth(columnName)

返回指定列的宽度。

参数

名称	类型	说明
columnName	String	列名称。

返回

Integer - 列的宽度，如果列使用默认宽度，则为 null。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getDataSource()

获取对象关联的数据源。

返回

DataSource - 数据源。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getFilters()

返回应用于数据源工作表的所有过滤条件。

返回

DataSourceSheetFilter[] - 应用于数据源工作表的所有过滤条件的数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getSheetValues(columnName)

返回指定列名称的数据源工作表的所有值。

参数

名称	类型	说明
columnName	String	要提取值的数据源列名称。

返回

Object[] - 值的一维数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getSheetValues(columnName, startRow, numRows)

返回指定数据源工作表中指定列名称的所有值，从指定的起始行（从 1 开始）到指定的 numRows。

参数

名称	类型	说明
columnName	String	要提取值的数据源列名称。
startRow	Integer	开始提取值的行位置。
numRows	Integer	要提取的行数。

返回

Object[] - 值的一维数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getSortSpecs()

获取数据源工作表中的所有排序规范。

返回

SortSpec[] - 排序规范列表。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

getStatus()

获取对象的数据执行状态。

返回

DataExecutionStatus - 数据执行状态。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

refreshData()

刷新对象的数据。

如果当前处于 error 状态，则会抛出异常。使用 DataSource#updateSpec() 更新规范。建议使用此方法，而不是 forceRefreshData()，以防止对数据源进行意外修改。

如果数据源类型未启用，则会抛出异常。使用 SpreadsheetApp#enable...Execution() 方法为特定数据源类型启用数据执行。

返回

DataSourceSheet - 数据对象。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

removeFilters(columnName)

移除应用于数据源工作表列的所有过滤条件。

参数

名称	类型	说明
columnName	String	要移除过滤条件的列的名称。

返回

DataSourceSheet - 数据源工作表，用于方法链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

removeSortSpec(columnName)

移除数据源工作表中列的排序规范。

参数

名称	类型	说明
columnName	String	列的名称。

返回

DataSourceSheet - 数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

setColumnWidth(columnName, width)

设置指定列的宽度。

参数

名称	类型	说明
columnName	String	列名称。
width	Integer	列的新宽度。

返回

DataSourceSheet - 此数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

setColumnWidths(columnNames, width)

设置指定列的宽度。

参数

名称	类型	说明
columnNames	String[]	要更新的列名称的列表。
width	Integer	列的新宽度。

返回

DataSourceSheet - 此数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

setSortSpec(columnName, ascending)

设置数据源工作表中列的排序规范。

参数

名称	类型	说明
columnName	String	要排序的列的名称。
ascending	Boolean	如果为 true，则按升序对此列排序；如果为 false，则按降序对此列排序。

返回

DataSourceSheet - 数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

setSortSpec(columnName, sortOrder)

设置数据源工作表中列的排序规范。

参数

名称	类型	说明
columnName	String	要排序的列的名称。
sortOrder	SortOrder	排序顺序。

返回

DataSourceSheet - 数据源工作表，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

---

waitForCompletion(timeoutInSeconds)

等待当前执行操作完成，并在提供的秒数后超时。 如果超时时执行未完成，则会抛出异常，但不会取消数据执行。

参数

名称	类型	说明
timeoutInSeconds	Integer	等待数据执行的时间（以秒为单位）。最长为 300 秒。

返回

DataExecutionStatus - 数据执行状态。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets