Excel. Worksheet class

context

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

context: RequestContext;

属性值

Excel.RequestContext

freezePanes

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

readonly freezePanes: Excel.WorksheetFreezePanes;

属性值

Excel.WorksheetFreezePanes

注解

id

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

readonly id: string;

属性值

string

注解

name

工作表的显示名称。

name: string;

属性值

string

注解

names

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

readonly names: Excel.NamedItemCollection;

属性值

Excel.NamedItemCollection

注解

[ API 集：ExcelApi 1.4 ]

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

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

tables

属于工作表的表的集合。

readonly tables: Excel.TableCollection;

属性值

Excel.TableCollection

注解

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

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

注解

getUsedRange(valuesOnly)

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

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

参数

valuesOnly: boolean

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

Excel.Range

注解

OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>

示例

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

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

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

示例

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

onChanged

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

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

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

示例

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

onDeactivated

在停用工作表时发生。

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

事件类型

注解

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

示例

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

onSelectionChanged

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

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

事件类型

注解