Excel.WorksheetCollection class
表示属于工作簿的 worksheet 对象的集合。
方法
| add(name) | 向工作簿添加新工作表。 工作表将添加到现有工作表的末尾。 如果您想激活新添加的工作表，请调用 |
| add |
将工作簿的指定工作表插入当前工作簿。
注意：此 API 目前仅支持 Windows 版和 Mac 版 Office。 它已被弃用，请改用 |
| add |
将工作簿的指定工作表插入当前工作簿。
注意：此 API 目前仅支持 Windows 版和 Mac 版 Office。 它已被弃用，请改用 |
| get |
获取工作簿中当前处于活动状态的工作表。 |
| get |
获取集合中的工作表数量。 |
| get |
获取集合中的第一个工作表。 |
| get |
使用其名称或 ID 获取 worksheet 对象。 |
| get |
使用其名称或 ID 获取 worksheet 对象。 如果工作表不存在，则此方法返回其 |
| get |
获取集合中的最后一个工作表。 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| toJSON() | 覆盖 JavaScript |
活动
| on |
激活工作簿中的任何工作表时发生。 |
| on |
在将新工作表添加到工作簿时发生。 |
| on |
计算工作簿中的任何工作表时发生。 |
| on |
在异步计算工作表中的单元格时发生。 此事件在计算周期结束时触发，类似于事件 JavaScript User-Defined 函数和 =PY 公式等公式功能可能会触发此事件。 |
| on |
在更改工作簿中的任何工作表时发生。 |
| on |
在已对一个或多个列进行排序时发生。 这是从左到右排序操作的结果。 |
| on |
当停用工作簿中的任何工作表时发生。 |
| on |
从工作簿中删除工作表时发生。 |
| on |
在工作簿中应用任何工作表的筛选器时发生。 |
| on |
当工作簿中的任何工作表的格式发生更改时发生。 |
| on |
当此集合的任何工作表中的一个或多个公式发生更改时发生。 此事件适用于公式本身发生更改的情况，而不是公式计算生成的数据值。 |
| on |
在工作簿中移动工作表时发生。 仅当工作簿中直接移动工作表时，才会触发此事件。 间接更改工作表的位置时（例如，插入新工作表并导致现有工作表更改位置时），不会触发此事件。 |
| on |
当工作表集合中的工作表名称发生更改时发生。 |
| on |
在工作表保护状态更改时发生。 |
| on |
当特定工作表上一行或多行的隐藏状态发生更改时发生。 |
| on |
在已对一个或多个行进行排序时发生。 这是从上到下排序操作的结果。 |
| on |
在任何工作表上更改选择时发生。 |
| on |
在工作表集合中发生左键单击/点击操作时发生。 在以下情况下单击时不会触发此事件： - 用户拖动鼠标进行多选。 - 为公式引用选择单元格参数时，用户在模式中选择一个单元格。 |
| on |
当工作表集合中的工作表可见性发生更改时发生。 |
属性详细信息
context
items
方法详细信息
add(name)
向工作簿添加新工作表。 工作表将添加到现有工作表的末尾。 如果您想激活新添加的工作表，请调用 .activate() 它。
add(name?: string): Excel.Worksheet;参数
- name
-
string
可选。 要添加的工作表的名称。 如果指定，则名称应是唯一的。 如果未指定，Excel 将确定新工作表的名称。
返回
注解
示例
await Excel.run(async (context) => {
const wSheetName = 'Sample Name';
const worksheet = context.workbook.worksheets.add(wSheetName);
worksheet.load('name');
await context.sync();
console.log(worksheet.name);
});
addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)
注意
此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。
将工作簿的指定工作表插入当前工作簿。
注意：此 API 目前仅支持 Windows 版和 Mac 版 Office。 它已被弃用，请改用 Workbook.insertWorksheetFromBase64 。
addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: Excel.WorksheetPositionType, relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;参数
- base64File
-
string
必填。 表示源工作簿文件的 Base64 编码字符串。
- sheetNamesToInsert
-
string[]
可选。 要插入的各个工作表的名称。 默认情况下，将插入源工作簿中的所有工作表。
- positionType
- Excel.WorksheetPositionType
可选。 将在当前工作簿中的何处插入新工作表。 有关详细信息，请参阅 Excel.WorksheetPositionType。 默认值为“开始”。
- relativeTo
-
Excel.Worksheet | string
可选。 当前工作簿中参数 positionType 引用的工作表。 默认值为 null 并且，基于 positionType，它将在当前工作簿的开头或末尾插入工作表。
返回
OfficeExtension.ClientResult<string[]>
与每个新插入的工作表对应的 ID 数组。
注解
addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)
注意
此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。
将工作簿的指定工作表插入当前工作簿。
注意：此 API 目前仅支持 Windows 版和 Mac 版 Office。 它已被弃用，请改用 Workbook.insertWorksheetFromBase64 。
addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;参数
- base64File
-
string
必填。 表示源工作簿文件的 Base64 编码字符串。
- sheetNamesToInsert
-
string[]
可选。 要插入的各个工作表的名称。 默认情况下，将插入源工作簿中的所有工作表。
- positionType
-
"None" | "Before" | "After" | "Beginning" | "End"
可选。 将在当前工作簿中的何处插入新工作表。 有关详细信息，请参阅 Excel.WorksheetPositionType。 默认值为“开始”。
- relativeTo
-
Excel.Worksheet | string
可选。 当前工作簿中参数 positionType 引用的工作表。 默认值为 null 并且，基于 positionType，它将在当前工作簿的开头或末尾插入工作表。
返回
OfficeExtension.ClientResult<string[]>
与每个新插入的工作表对应的 ID 数组。
注解
getActiveWorksheet()
获取工作簿中当前处于活动状态的工作表。
getActiveWorksheet(): Excel.Worksheet;返回
注解
示例
await Excel.run(async (context) => {
const activeWorksheet = context.workbook.worksheets.getActiveWorksheet();
activeWorksheet.load('name');
await context.sync();
console.log(activeWorksheet.name);
});
getCount(visibleOnly)
获取集合中的工作表数量。
getCount(visibleOnly?: boolean): OfficeExtension.ClientResult<number>;参数
- visibleOnly
-
boolean
可选。 如果 true，仅考虑可见的工作表，跳过任何隐藏的工作表。
返回
OfficeExtension.ClientResult<number>
注解
getFirst(visibleOnly)
获取集合中的第一个工作表。
getFirst(visibleOnly?: boolean): Excel.Worksheet;参数
- visibleOnly
-
boolean
可选。 如果 true，仅考虑可见的工作表，跳过任何隐藏的工作表。
返回
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml
await Excel.run(async (context) => {
const sheets = context.workbook.worksheets;
// We don't want to include the default worksheet that was created
// when the workbook was created, so our "firstSheet" will be the one
// after the literal first. Note chaining of navigation methods.
const firstSheet = sheets.getFirst().getNext();
const lastSheet = sheets.getLast();
const firstTaxRateRange = firstSheet.getRange("B2");
const lastTaxRateRange = lastSheet.getRange("B2");
firstSheet.load("name");
lastSheet.load("name");
firstTaxRateRange.load("text");
lastTaxRateRange.load("text");
await context.sync();
let firstYear = firstSheet.name.substr(5, 4);
let lastYear = lastSheet.name.substr(5, 4);
console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)
await context.sync();
});
getItem(key)
使用其名称或 ID 获取 worksheet 对象。
getItem(key: string): Excel.Worksheet;参数
- key
-
string
工作表的名称或 ID。
返回
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-axis-formatting.yaml
function displayUnit(context: Excel.RequestContext) {
let sheet = context.workbook.worksheets.getItem("Sample");
let chart = sheet.charts.getItem("SalesChart");
let axis = chart.axes.valueAxis;
axis.displayUnit = "Thousands";
}
getItemOrNullObject(key)
使用其名称或 ID 获取 worksheet 对象。 如果工作表不存在，则此方法返回其 isNullObject 属性设置为 true的对象。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getItemOrNullObject(key: string): Excel.Worksheet;参数
- key
-
string
工作表的名称或 ID。
返回
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/performance-optimization.yaml
/** Helper to create or recreate a worksheet. */
async function forceCreateSheet(workbook: Excel.Workbook, sheetName: string): Promise<Excel.Worksheet> {
workbook.worksheets.getItemOrNullObject(sheetName).delete();
await workbook.context.sync();
return workbook.worksheets.add(sheetName);
}
getLast(visibleOnly)
获取集合中的最后一个工作表。
getLast(visibleOnly?: boolean): Excel.Worksheet;参数
- visibleOnly
-
boolean
可选。 如果 true，仅考虑可见的工作表，跳过任何隐藏的工作表。
返回
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml
await Excel.run(async (context) => {
const sheets = context.workbook.worksheets;
// We don't want to include the default worksheet that was created
// when the workbook was created, so our "firstSheet" will be the one
// after the literal first. Note chaining of navigation methods.
const firstSheet = sheets.getFirst().getNext();
const lastSheet = sheets.getLast();
const firstTaxRateRange = firstSheet.getRange("B2");
const lastTaxRateRange = lastSheet.getRange("B2");
firstSheet.load("name");
lastSheet.load("name");
firstTaxRateRange.load("text");
lastTaxRateRange.load("text");
await context.sync();
let firstYear = firstSheet.name.substr(5, 4);
let lastYear = lastSheet.name.substr(5, 4);
console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)
await context.sync();
});
load(options)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(options?: Excel.Interfaces.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.WorksheetCollection;参数
为要加载的对象属性提供选项。
返回
load(propertyNames)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNames?: string | string[]): Excel.WorksheetCollection;参数
- propertyNames
-
string | string[]
指定要加载的属性的逗号分隔的字符串或字符串数组。
返回
示例
await Excel.run(async (context) => {
const worksheets = context.workbook.worksheets;
worksheets.load('items');
await context.sync();
for (let i = 0; i < worksheets.items.length; i++) {
console.log(worksheets.items[i].name);
}
});
load(propertyNamesAndPaths)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.WorksheetCollection;参数
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串，以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。
返回
toJSON()
覆盖 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Excel.WorksheetCollection 对象是 API 对象，但该 toJSON 方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.WorksheetCollectionData) ，其中包含一个“items”数组，其中包含从集合的 items 中加载的任何属性的浅层副本。
toJSON(): Excel.Interfaces.WorksheetCollectionData;返回
事件详细信息
onActivated
激活工作簿中的任何工作表时发生。
readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;事件类型
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml
await Excel.run(async (context) => {
let sheets = context.workbook.worksheets;
sheets.onActivated.add(onActivate);
await context.sync();
console.log("A handler has been registered for the OnActivate event.");
});
onAdded
在将新工作表添加到工作簿时发生。
readonly onAdded: OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>;事件类型
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml
await Excel.run(async (context) => {
let sheet = context.workbook.worksheets;
sheet.onAdded.add(onWorksheetAdd);
await context.sync();
console.log("A handler has been registered for the OnAdded event.");
});
onCalculated
计算工作簿中的任何工作表时发生。
readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;事件类型
注解
onCalculationBusy
注意
此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。
在异步计算工作表中的单元格时发生。
此事件在计算周期结束时触发，类似于事件 onCalculated 。 通常，当单元格的计算完成时， onCalculated 将触发该事件。 但是，如果计算放置了暂时挂起值，则 (例如“#BUSY！”然后触发 ) ， onCalculationBusy 而是被触发以指示电池的状态已更改，尽管最终值的计算尚未完成。 当后续计算周期完成该单元格的计算时，将触发该 onCalculated 事件。
JavaScript User-Defined 函数和 =PY 公式等公式功能可能会触发此事件。
readonly onCalculationBusy: OfficeExtension.EventHandlers<Excel.WorksheetCalculationBusyEventArgs>;事件类型
注解
onChanged
在更改工作簿中的任何工作表时发生。
readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;事件类型
注解
onColumnSorted
在已对一个或多个列进行排序时发生。 这是从左到右排序操作的结果。
readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;事件类型
注解
onDeactivated
当停用工作簿中的任何工作表时发生。
readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;事件类型
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml
await Excel.run(async (context) => {
let sheets = context.workbook.worksheets;
sheets.onDeactivated.add(onDeactivate);
await context.sync();
console.log("A handler has been registered for the OnDeactivate event.");
});
onDeleted
从工作簿中删除工作表时发生。
readonly onDeleted: OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>;事件类型
注解
onFiltered
注意
此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。
在工作簿中应用任何工作表的筛选器时发生。
readonly onFiltered: OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>;事件类型
注解
onFormatChanged
当工作簿中的任何工作表的格式发生更改时发生。
readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;事件类型
注解
onFormulaChanged
当此集合的任何工作表中的一个或多个公式发生更改时发生。 此事件适用于公式本身发生更改的情况，而不是公式计算生成的数据值。
readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;事件类型
注解
onMoved
在工作簿中移动工作表时发生。 仅当工作簿中直接移动工作表时，才会触发此事件。 间接更改工作表的位置时（例如，插入新工作表并导致现有工作表更改位置时），不会触发此事件。
readonly onMoved: OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>;事件类型
注解
onNameChanged
当工作表集合中的工作表名称发生更改时发生。
readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;事件类型
注解
onProtectionChanged
在工作表保护状态更改时发生。
readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;事件类型
注解
onRowHiddenChanged
当特定工作表上一行或多行的隐藏状态发生更改时发生。
readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;事件类型
注解
onRowSorted
在已对一个或多个行进行排序时发生。 这是从上到下排序操作的结果。
readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;事件类型
注解
onSelectionChanged
在任何工作表上更改选择时发生。
readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;事件类型
注解
onSingleClicked
在工作表集合中发生左键单击/点击操作时发生。 在以下情况下单击时不会触发此事件： - 用户拖动鼠标进行多选。 - 为公式引用选择单元格参数时，用户在模式中选择一个单元格。
readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;事件类型
注解
onVisibilityChanged
当工作表集合中的工作表可见性发生更改时发生。
readonly onVisibilityChanged: OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>;事件类型
注解
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-visibility.yaml
await Excel.run(async (context) => {
// Register an event handler for visibility changes to any worksheet in the collection.
context.workbook.worksheets.onVisibilityChanged.add(onWorksheetCollectionVisibilityChanged);
await context.sync();
console.log("Registered the worksheet collection visibility changed event handler.");
});
...
async function onWorksheetCollectionVisibilityChanged(args: Excel.WorksheetVisibilityChangedEventArgs) {
console.log(`Worksheet collection event: Worksheet ${args.worksheetId} visibility changed from ${args.visibilityBefore} to ${args.visibilityAfter}.`);
}