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 在必要时重新计算工作表，则为 true。如果 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

notes

返回工作表中所有备注对象的集合。

readonly notes: Excel.NoteCollection;

属性值

Excel.NoteCollection

注解

API 集：ExcelApi 1.18

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

注解

showDataTypeIcons

指定数据类型图标在工作表上是否可见。默认情况下，数据类型图标可见。

showDataTypeIcons: boolean;

属性值

boolean

注解

API 集：ExcelApi 1.19

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。如果工作表可见，但选项卡颜色设置为自动，则将返回一个空字符串。否则，该属性将设置为颜色，形式 #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

注解

API 集：ExcelApi BETA (仅预览版)

tasks

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

返回工作表中存在的任务集合。

readonly tasks: Excel.DocumentTaskCollection;

属性值

Excel.DocumentTaskCollection

注解

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

注解

API 集：ExcelApiDesktop 1.1

示例

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

没错，将所有标记为脏。

返回

void

注解

API 集：ExcelApi 1.6

checkSpelling(options)

检查此工作表中单词的拼写。此方法在 Excel UI 中打开“拼写检查”对话框。

checkSpelling(options?: Excel.CheckSpellingOptions): void;

参数

options: Excel.CheckSpellingOptions

可选。用于检查拼写的选项。

返回

void

注解

clearArrows()

清除指定工作表的追踪箭头。

clearArrows(): void;

返回

void

注解

API 集：ExcelApiDesktop 1.1

copy(positionType, relativeTo)

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

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

参数

positionType: Excel.WorksheetPositionType

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

relativeTo: Excel.Worksheet

用于确定新创建工作表位置的现有工作表。仅当为“之前”或“之后”时 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(positionType, relativeTo)

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

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

参数

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

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

relativeTo: Excel.Worksheet

用于确定新创建工作表位置的现有工作表。仅当为“之前”或“之后”时 positionType 才需要这样做。

返回

Excel.Worksheet

新创建的工作表。

注解

delete()

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

delete(): void;

返回

void

注解

API 集：ExcelApiDesktop 1.1

示例

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

evaluate(name)

返回公式字符串的计算结果。仅支持公式输入。如果公式名称无效， InvalidArgument 则引发错误。

evaluate(name: string): OfficeExtension.ClientResult<any>;

参数

name: string

要运行的公式的名称。

返回

OfficeExtension.ClientResult<any>

注解

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”。如果未指定，则返回整个工作表区域。此字符 address 的长度限制为 8192 个字符。如果地址超过字符限制，此方法将返回错误 InvalidArgument 。

返回

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)

按大纲级别显示行或列组。大纲、组和汇总工作表中的数据列表。和 columnLevels 参数指定rowLevels显示大纲的级别数。可接受的参数范围介于 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();
});

onCalculationBusy

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

在异步计算工作表中的单元格时发生。

此事件在计算周期结束时触发，类似于事件 onCalculated 。通常，当单元格的计算完成时， onCalculated 将触发该事件。但是，如果计算放置了暂时挂起值，则 (例如“#BUSY！”然后触发 ) ， onCalculationBusy 而是被触发以指示电池的状态已更改，尽管最终值的计算尚未完成。当后续计算周期完成该单元格的计算时，将触发该 onCalculated 事件。

JavaScript User-Defined 函数和 =PY 公式等公式功能可能会触发此事件。

readonly onCalculationBusy: OfficeExtension.EventHandlers<Excel.WorksheetCalculationBusyEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorksheetCalculationBusyEventArgs>

注解

API 集：ExcelApi BETA (仅预览版)

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.WorksheetFilteredEventArgs>

示例

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

onFiltered

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。请勿在生产环境中使用此 API。

在特定工作表上应用筛选器时出现。

readonly onFiltered: OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>;

事件类型

注解

API 集：ExcelApi BETA (仅预览版)

onFormatChanged

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

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

事件类型

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>;

事件类型

注解