Excel. Worksheet class

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-auto-filter.yaml

// This function adds a percentage AutoFilter to the active worksheet 
// and applies the filter to a column of the used range.
await Excel.run(async (context) => {
    // Retrieve the active worksheet and the used range on that worksheet.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const farmData = sheet.getUsedRange();

    // Add a filter that will only show the rows with the top 50% of values in column 3.
    sheet.autoFilter.apply(farmData, 3, {
        criterion1: "50",
        filterOn: Excel.FilterOn.topPercent
    });

    await context.sync();
});

charts

返回属于工作表的图表集合。

readonly charts: Excel.ChartCollection;

属性值

Excel.ChartCollection

注解

comments

返回工作表上的所有 Comments 对象的集合。

readonly comments: Excel.CommentCollection;

属性值

Excel.CommentCollection

注解

context

与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Excel.RequestContext

customProperties

获取工作表级自定义属性的集合。

readonly customProperties: Excel.WorksheetCustomPropertyCollection;

属性值

Excel.WorksheetCustomPropertyCollection

注解

[ API 集：ExcelApi 1.12 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/custom-properties.yaml

await Excel.run(async (context) => {
  // Load the keys and values of all custom properties in the current worksheet.
  const customWorksheetProperties = context.workbook.worksheets.getActiveWorksheet().customProperties;
  customWorksheetProperties.load(["key", "value"]);
  await context.sync();

  // Log each custom property to the console.
  // Note that your document may have more properties than those you have set using this snippet.
  customWorksheetProperties.items.forEach((property) => {
    console.log(`${property.key}:${property.value}`);
  });
});

enableCalculation

确定 Excel 是否应在必要时重新计算工作表。如此如果 Excel 在必要时重新计算工作表。如果 Excel 不重新计算工作表，则该值为 False。

enableCalculation: boolean;

属性值

boolean

注解

freezePanes

获取一个对象，该对象可用于操作工作表上的冻结窗格。

readonly freezePanes: Excel.WorksheetFreezePanes;

属性值

Excel.WorksheetFreezePanes

注解

horizontalPageBreaks

获取工作表的水平分页符集合。此集合仅包含手动分页符。

readonly horizontalPageBreaks: Excel.PageBreakCollection;

属性值

Excel.PageBreakCollection

注解

id

返回用于唯一标识指定工作簿中工作表的值。即使工作表被重命名或移动，标识符的值仍然相同。

readonly id: string;

属性值

string

注解

name

工作表的显示名称。名称必须少于 32 个字符。

name: string;

属性值

string

注解

namedSheetViews

返回工作表中存在的工作表视图的集合。

readonly namedSheetViews: Excel.NamedSheetViewCollection;

属性值

Excel.NamedSheetViewCollection

注解

[ API 集：ExcelApiOnline 1.1 ]

names

一组范围限定到当前工作表的名称。

readonly names: Excel.NamedItemCollection;

属性值

Excel.NamedItemCollection

注解

[ API 集：ExcelApi 1.4 ]

pageLayout

获取 PageLayout 工作表的对象。

readonly pageLayout: Excel.PageLayout;

属性值

Excel.PageLayout

注解

pivotTables

一组属于工作表的数据透视表对象。

readonly pivotTables: Excel.PivotTableCollection;

属性值

Excel.PivotTableCollection

注解

[ API 集：ExcelApi 1.3 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  // Get the names of all the PivotTables in the current worksheet.
  const pivotTables = context.workbook.worksheets.getActiveWorksheet().pivotTables;
  pivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current worksheet:")
  pivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

position

工作表在工作簿中的位置，从零开始。

position: number;

属性值

number

注解

示例

// Set worksheet position.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.position = 2;
    await context.sync(); 
});

protection

返回工作表的工作表保护对象。

readonly protection: Excel.WorksheetProtection;

属性值

Excel.WorksheetProtection

注解

[ API 集：ExcelApi 1.2 ]

示例

// Unprotecting a worksheet with unprotect() will remove all 
// WorksheetProtectionOptions options applied to a worksheet.
// To remove only a subset of WorksheetProtectionOptions use the 
// protect() method and set the options you wish to remove to true.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sheet1");
  sheet.protection.protect({
    allowInsertRows: false, // Protect row insertion
    allowDeleteRows: true // Unprotect row deletion
  });
});

shapes

返回工作表上的所有 Shape 对象的集合。

readonly shapes: Excel.ShapeCollection;

属性值

Excel.ShapeCollection

注解

showGridlines

指定网格线是否对用户可见。

showGridlines: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.8 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/gridlines.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.showGridlines = true;

    await context.sync();
});

showHeadings

指定标题是否对用户可见。

showHeadings: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.8 ]

slicers

返回属于工作表的切片器的集合。

readonly slicers: Excel.SlicerCollection;

属性值

Excel.SlicerCollection

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-slicer.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Pivot");
    const slicer = sheet.slicers.add(
        "Farm Sales", /* The slicer data source. For PivotTables, this can be the PivotTable object reference or name. */
        "Type" /* The field in the data source to filter by. For PivotTables, this can be a PivotField object reference or ID. */
    );
    slicer.name = "Fruit Slicer";
    await context.sync();
});

standardHeight

返回工作表中所有行的标准（默认）行高，以磅为单位。

readonly standardHeight: number;

属性值

number

注解

standardWidth

指定工作表中所有列的标准 (默认) 宽度。一个列宽单位等于“常规”样式中一个字符的宽度。对于比例字体，则使用字符 0（零）的宽度。

standardWidth: number;

属性值

number

注解

tabColor

工作表的选项卡颜色。检索选项卡颜色时，如果工作表不可见，则值为 null。如果工作表可见，但选项卡颜色设置为 auto，将返回空字符串。否则，属性将设置为颜色，格式 #RRGGBB (例如“FFA500”) 。设置颜色时，请使用空字符串设置“自动”颜色，否则使用实色。

tabColor: string;

属性值

string

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/tab-color.yaml

await Excel.run(async (context) => {
    const activeSheet = context.workbook.worksheets.getActiveWorksheet();
    activeSheet.tabColor = "#FF0000";

    await context.sync();
});

tabId

返回一个值，该值表示可由 Open Office XML 读取的此工作表。这是一个整数值，它不同于 worksheet.id (返回全局唯一标识符) 和 worksheet.name 返回值（如“Sheet1”) ）的 (。

readonly tabId: number;

属性值

number

注解

[ API 集：ExcelApi 1.14 ]

tables

属于工作表的表的集合。

readonly tables: Excel.TableCollection;

属性值

Excel.TableCollection

注解

verticalPageBreaks

获取工作表的垂直分页符集合。此集合仅包含手动分页符。

readonly verticalPageBreaks: Excel.PageBreakCollection;

属性值

Excel.PageBreakCollection

注解

[ API 集：ExcelApi 1.1 用于读取可见性;1.2 用于设置它。 ]

visibility

工作表的可见性。

visibility: Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden";

属性值

Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden"

注解

方法详细信息

activate()

在 Excel UI 中激活工作表。

activate(): void;

void

注解

示例

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

calculate(markAllDirty)

计算工作表上的所有单元格。

calculate(markAllDirty: boolean): void;

参数

markAllDirty: boolean

如果为 True，则全部标记为脏。

void

注解

[ API 集：ExcelApi 1.6 ]

copy(positionType, relativeTo)

复制工作表并将其放置在指定位置。

copy(positionType?: Excel.WorksheetPositionType, relativeTo?: Excel.Worksheet): Excel.Worksheet;

参数

positionType: Excel.WorksheetPositionType

要放置新创建的工作表的工作簿中的位置。默认值为“None”，它将工作表插入工作表的开头。

relativeTo: Excel.Worksheet

确定新创建工作表位置的现有工作表。仅当为“Before”或“After”时才 positionType 需要此项。

Excel.Worksheet

新创建的工作表。

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-copy.yaml

await Excel.run(async (context) => {

    let myWorkbook = context.workbook;
    let sampleSheet = myWorkbook.worksheets.getActiveWorksheet();
    let copiedSheet = sampleSheet.copy("End")

    sampleSheet.load("name");
    copiedSheet.load("name");

    await context.sync();

    console.log("'" + sampleSheet.name + "' was copied to '" + copiedSheet.name + "'")
});

copy(positionTypeString, relativeTo)

复制工作表并将其放置在指定位置。

copy(positionTypeString?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Excel.Worksheet): Excel.Worksheet;

参数

positionTypeString: "None" | "Before" | "After" | "Beginning" | "End"

要放置新创建的工作表的工作簿中的位置。默认值为“None”，它将工作表插入工作表的开头。

relativeTo: Excel.Worksheet

确定新创建工作表位置的现有工作表。仅当为“Before”或“After”时才 positionType 需要此项。

Excel.Worksheet

新创建的工作表。

注解

delete()

从工作簿中删除工作表。请注意，如果工作表的可见性设置为“VeryHidden”，则删除操作将失败并出现 InvalidOperation 异常。删除之前，应首先将其可见性更改为隐藏或可见。

delete(): void;

void

注解

示例

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.delete();
    await context.sync(); 
});

findAll(text, criteria)

根据指定的条件查找给定字符串的所有匹配项，并将其作为 RangeAreas 对象返回，包括一个或多个矩形区域。

findAll(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;

参数

text: string

要查找的字符串。

criteria: Excel.WorksheetSearchCriteria

其他搜索条件，包括搜索是需要匹配整个单元格还是区分大小写。

Excel.RangeAreas

一个 RangeAreas 对象，由一个或多个矩形区域组成，与搜索条件匹配。如果没有单元格满足此条件， ItemNotFound 将引发错误。

注解

findAllOrNullObject(text, criteria)

根据指定的条件查找给定字符串的所有匹配项，并将其作为 RangeAreas 对象返回，包括一个或多个矩形区域。

findAllOrNullObject(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;

参数

text: string

要查找的字符串。

criteria: Excel.WorksheetSearchCriteria

其他搜索条件，包括搜索是需要匹配整个单元格还是区分大小写。

Excel.RangeAreas

一个 RangeAreas 对象，由一个或多个矩形区域组成，与搜索条件匹配。如果没有匹配项，则此方法返回对象的 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-find-all.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const foundRanges = sheet.findAllOrNullObject("Complete", {
        completeMatch: true,
        matchCase: false
    });

    await context.sync();

    if (foundRanges.isNullObject) {
        console.log("No complete projects");
    } else {
        foundRanges.format.fill.color = "green"
    }
});

getCell(row, column)

Range获取包含基于行号和列号的单个单元格的对象。单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。

getCell(row: number, column: number): Excel.Range;

参数

row: number

要检索的单元格的行号。从零开始编制索引。

column: number

要检索的单元格的列号。从零开始编制索引。

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const cell = worksheet.getCell(0,0);
    cell.load('address');
    await context.sync();

    console.log(cell.address);
});

getNext(visibleOnly)

获取此工作表后面的工作表。如果此工作表之后没有工作表，此方法将引发错误。

getNext(visibleOnly?: boolean): Excel.Worksheet;

参数

visibleOnly: boolean

可选。如果 true为，则仅考虑可见工作表，跳过任何隐藏工作表。

Excel.Worksheet

注解

示例

// 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();
});

getNextOrNullObject(visibleOnly)

获取此工作表后面的工作表。如果此工作表之后没有工作表，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getNextOrNullObject(visibleOnly?: boolean): Excel.Worksheet;

参数

visibleOnly: boolean

可选。如果 true为，则仅考虑可见工作表，跳过任何隐藏工作表。

Excel.Worksheet

注解

getPrevious(visibleOnly)

获取此工作表之前的工作表。如果没有以前的工作表，此方法将引发错误。

getPrevious(visibleOnly?: boolean): Excel.Worksheet;

参数

visibleOnly: boolean

可选。如果 true为，则仅考虑可见工作表，跳过任何隐藏工作表。

Excel.Worksheet

注解

示例

// 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;
    const currentSheet = sheets.getActiveWorksheet();
    const previousYearSheet = currentSheet.getPrevious();
    const currentTaxDueRange = currentSheet.getRange("C2");
    const previousTaxDueRange = previousYearSheet.getRange("C2");

    currentSheet.load("name");
    previousYearSheet.load("name");
    currentTaxDueRange.load("text");
    previousTaxDueRange.load("text");

    await context.sync();

    let currentYear = currentSheet.name.substr(5, 4);
    let previousYear = previousYearSheet.name.substr(5, 4);
    console.log("Two Year Tax Due Comparison", `Tax due for ${currentYear} was ${currentTaxDueRange.text[0][0]}\nTax due for ${previousYear} was ${previousTaxDueRange.text[0][0]}`)

    await context.sync();
});

getPreviousOrNullObject(visibleOnly)

获取此工作表之前的工作表。如果没有以前的工作表，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getPreviousOrNullObject(visibleOnly?: boolean): Excel.Worksheet;

参数

visibleOnly: boolean

可选。如果 true为，则仅考虑可见工作表，跳过任何隐藏工作表。

Excel.Worksheet

注解

getRange(address)

Range获取对象，该对象表示由地址或名称指定的单个矩形单元格块。

getRange(address?: string): Excel.Range;

参数

address: string

可选。表示范围地址或名称的字符串。例如，“A1：B2”。如果未指定，则返回整个工作表区域。

Excel.Range

注解

示例

// Use the range address to get the range object.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

获取对象， Range 从特定的行索引和列索引开始，并跨越一定数量的行和列。

getRangeByIndexes(startRow: number, startColumn: number, rowCount: number, columnCount: number): Excel.Range;

参数

startRow: number

零索引) (起始行。

startColumn: number

零索引) (启动列。

rowCount: number

要包括在区域中的行数。

columnCount: number

要包括在区域中的列数。

Excel.Range

注解

getRanges(address)

RangeAreas获取对象，该对象表示由地址或名称指定的一个或多个矩形区域块。

getRanges(address?: string): Excel.RangeAreas;

参数

address: string

可选。一个字符串，包含逗号分隔或分号分隔的地址或各个区域的名称。例如，“A1：B2、A5：B5”或“A1：B2;A5：B5”。如果未指定， RangeAreas 则返回整个工作表的对象。

Excel.RangeAreas

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const specifiedRanges = sheet.getRanges("D3:D5, G3:G5");
    specifiedRanges.format.fill.color = "pink";

    await context.sync();
})

getUsedRange(valuesOnly)

使用的区域是包含分配了值或格式化的任何单元格的最小区域。如果整个工作表为空，此函数将返回左上角的单元格 (即不会) 引发错误。

getUsedRange(valuesOnly?: boolean): Excel.Range;

参数

valuesOnly: boolean

可选。如果 true为，则仅将值视为已用单元格的单元格， (忽略格式设置) 。 [Api 集：ExcelApi 1.2]

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    const usedRange = worksheet.getUsedRange();
    usedRange.load('address');
    await context.sync();
    
    console.log(usedRange.address);
});

getUsedRangeOrNullObject(valuesOnly)

使用的区域是包含分配了值或格式化的任何单元格的最小区域。如果整个工作表为空，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;

参数

valuesOnly: boolean

可选。仅将有值的单元格视为已使用的单元格。

Excel.Range

注解

[ API 集：ExcelApi 1.4 ]

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(options?: Excel.Interfaces.WorksheetLoadOptions): Excel.Worksheet;

参数

options: Excel.Interfaces.WorksheetLoadOptions

提供要加载对象的属性的选项。

Excel.Worksheet

load(propertyNames)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(propertyNames?: string | string[]): Excel.Worksheet;

参数

propertyNames: string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

Excel.Worksheet

示例

// Get worksheet properties based on sheet name.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.load('position')
    await context.sync();
    
    console.log(worksheet.position);
});

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Worksheet;

参数

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。

Excel.Worksheet

replaceAll(text, replacement, criteria)

根据当前工作表中指定的条件查找并替换给定的字符串。

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

参数

text: string

要查找的字符串。

replacement: string

替换原始字符串的字符串。

criteria: Excel.ReplaceCriteria

其他替换条件。

OfficeExtension.ClientResult<number>

执行的替换次数。

注解

set(properties, options)

同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。

set(properties: Interfaces.WorksheetUpdateData, options?: OfficeExtension.UpdateOptions): void;

参数

properties: Excel.Interfaces.WorksheetUpdateData

一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。

options: OfficeExtension.UpdateOptions

提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。

void

示例

// Set the color and name of the current worksheet.
await Excel.run(async (context) => {
  const activeSheet = context.workbook.worksheets.getActiveWorksheet();
  activeSheet.set({
    tabColor: "yellow",
    name: "MySheet"
  });

  await context.sync();
});

set(properties)

基于现有的已加载对象，同时对对象设置多个属性。

set(properties: Excel.Worksheet): void;

参数

properties: Excel.Worksheet

void

showOutlineLevels(rowLevels, columnLevels)

按大纲级别显示行或列组。在工作表中概述组和汇总数据列表。 rowLevels和 columnLevels 参数指定显示大纲的级别。可接受的参数范围介于 0 和 8 之间。值为 0 不会更改当前显示。大于当前级别数的值将显示所有级别。

showOutlineLevels(rowLevels: number, columnLevels: number): void;

参数

rowLevels: number

要显示的大纲的行级别数。

columnLevels: number

要显示的大纲的列级别数。

void

注解

OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This shows the top 3 outline levels; collapsing any additional sublevels.
    sheet.showOutlineLevels(3, 3);
    await context.sync();
});

toJSON()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来又调用toJSON传递给它的对象的方法。) 而原始 Excel.Worksheet 对象是 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.WorksheetData) ，其中包含从原始对象加载的任何子属性的浅表副本。

toJSON(): Excel.Interfaces.WorksheetData;

Excel.Interfaces.WorksheetData

事件详细信息

onActivated

激活工作表时发生。

readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>

示例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onActivated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The activated worksheet ID is: " + event.worksheetId);
            await context.sync();
        });
    });
    await context.sync();
});

onCalculated

在计算工作表时发生。

readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;

事件类型

注解

[ API 集：ExcelApi 1.8 ]

示例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onCalculated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The worksheet has recalculated.");
            await context.sync();
        });
    });
    await context.sync();
});

onChanged

在特定工作表中的数据更改时发生。

readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>

注解

OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onChanged.add(onChange);
    await context.sync();

    console.log("Added a worksheet-level data-changed event handler.");
});

onColumnSorted

在已对一个或多个列进行排序时发生。这是从左到右排序操作的结果。

readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

await Excel.run(async (context) => {
    console.log("Adding column handler");
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This will fire whenever a column has been moved as the result of a sort action.
    sheet.onColumnSorted.add((event) => {
        return Excel.run((context) => {
            console.log("Column sorted: " + event.address);
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            // Clear formatting for section, then highlight the sorted area.
            sheet.getRange("A1:E5").format.fill.clear();
            if (event.address !== "") {
                sheet.getRanges(event.address).format.fill.color = "yellow";
            }

            return context.sync();
        });
    });
});

onDeactivated

在停用工作表时发生。

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>

示例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onDeactivated.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The deactivated worksheet is: " + event.worksheetId);
            await context.sync();
        });
    });
    await context.sync();
});

onFormatChanged

在特定工作表上更改格式时发生。

readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>

onFormulaChanged

在此工作表中更改一个或多个公式时发生。此事件适用于公式本身发生更改时，而不是公式计算产生的数据值。

readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;

事件类型

注解

[ API 集：ExcelApi 1.13 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-formula-changed.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet named "Sample".
  let sheet = context.workbook.worksheets.getItem("Sample");
  
  // Register the formula changed event handler for this worksheet.
  sheet.onFormulaChanged.add(formulaChangeHandler);
  await context.sync();
  
  console.log("Registered a formula changed event handler for this worksheet.");
});

...

async function formulaChangeHandler(event: Excel.WorksheetFormulaChangedEventArgs) {
  await Excel.run(async (context) => {
    // Retrieve details about the formula change event.
    const cellAddress = event.formulaDetails[0].cellAddress;
    const previousFormula = event.formulaDetails[0].previousFormula;
    const source = event.source;
    
    // Print out the change event details.
    console.log(
      `The formula in cell ${cellAddress} changed. 
      The previous formula was: ${previousFormula}. 
      The source of the change was: ${source}.`
    );
  });
}

onNameChanged

更改工作表名称时发生。

readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>

注解

[ API 集：ExcelApi 1.17 ]

onProtectionChanged

更改工作表保护状态时发生。

readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>

注解

[ API 集：ExcelApi 1.14 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet-protection.yaml

// This function registers an event handler for the onProtectionChanged event of a worksheet.
await Excel.run(async (context) => {
    // Set "Sample" as the active worksheet.
    context.workbook.worksheets.getItemOrNullObject("Sample").delete();
    const sheet = context.workbook.worksheets.add("Sample");
    sheet.activate();

    // Register the onProtectionChanged event handler.
    sheet.onProtectionChanged.add(checkProtection);
    await context.sync();
    console.log("Added a worksheet protection change event handler.");
});

...

async function checkProtection(event: Excel.WorksheetProtectionChangedEventArgs) {
    // This function is an event handler that returns the protection status of a worksheet
    // and information about the changed worksheet.
    await Excel.run(async (context) => {
        const protectionStatus = event.isProtected;
        const worksheetId = event.worksheetId;
        const source = event.source;
        console.log("Protection status changed. Protection status is now: " + protectionStatus + ".");
        console.log("    ID of changed worksheet: " + worksheetId + ".");
        console.log("    Source of change event: " + source + ".");
    });
}

onRowHiddenChanged

在特定工作表上更改一行或多行的隐藏状态时发生。

readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>

注解

[ API 集：ExcelApi 1.11 ]

示例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onRowHiddenChanged.add(function (event) {
        return Excel.run(async (context) => {
            console.log(`Row ${event.address} is now ${event.changeType}`);
            await context.sync();
        });
    });
    await context.sync();
});

onRowSorted

在已对一个或多个行进行排序时发生。这是从上到下排序操作的结果。

readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>

注解

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

await Excel.run(async (context) => {
    console.log("Adding row handler");
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // This will fire whenever a row has been moved as the result of a sort action.
    sheet.onRowSorted.add((event) => {
        return Excel.run((context) => {
            console.log("Row sorted: " + event.address);
            const sheet = context.workbook.worksheets.getActiveWorksheet();

            // Clear formatting for section, then highlight the sorted area.
            sheet.getRange("A1:E5").format.fill.clear();
            if (event.address !== "") {
                sheet.getRanges(event.address).format.fill.color = "yellow";
            }

            return context.sync();
        });
    });
});

onSelectionChanged

在特定工作表上更改所选内容时发生。

readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>

示例

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    sheet.onSelectionChanged.add(function (event) {
        return Excel.run(async (context) => {
            console.log("The selected range has changed to: " + event.address);
            await context.sync();
        });
    });
    await context.sync();
});

onSingleClicked

在工作表中发生左键单击/点击操作时发生。在以下情况下，单击时不会触发此事件：

用户拖动鼠标进行多选。
当为公式引用选择单元格参数时，用户将在模式下选择单元格。

readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;

事件类型

注解