Excel.Worksheet class

参考

包:: excel

Excel 工作表是由单元格组成的网格。它可以包含数据、表、图表等。若要了解有关工作表对象模型的详细信息，请阅读使用 Excel JavaScript API 处理工作表。

扩展: OfficeExtension.ClientObject

注解

示例

// Get a Worksheet object by its name and activate it.
await Excel.run(async (context) => { 
    const wSheetName = 'Sheet1';
    const worksheet = context.workbook.worksheets.getItem(wSheetName);
    worksheet.activate();
    await context.sync(); 
});

属性

charts	返回属于工作表的图表集合。
context	与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。
id	返回用于唯一标识指定工作簿中工作表的值。即使工作表被重命名或移动，标识符的值仍然相同。
name	工作表的显示名称。名称必须少于 32 个字符。
names	一组范围限定到当前工作表的名称。
pivotTables	一组属于工作表的数据透视表对象。
position	工作表在工作簿中的位置，从零开始。
protection	返回工作表的工作表保护对象。
tables	属于工作表的表的集合。
visibility	工作表的可见性。

方法

activate()	在 Excel UI 中激活工作表。
calculate(markAllDirty)	计算工作表上的所有单元格。
delete()	从工作簿中删除工作表。请注意，如果工作表的可见性设置为“VeryHidden”，则删除操作将失败并出现 `InvalidOperation` 异常。删除之前，应首先将其可见性更改为隐藏或可见。
getCell(row, column)	`Range`获取包含基于行号和列号的单个单元格的对象。单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。
getNext(visibleOnly)	获取此工作表后面的工作表。如果此工作表之后没有工作表，此方法将引发错误。
getNextOrNullObject(visibleOnly)	获取此工作表后面的工作表。如果此工作表之后没有工作表，则此方法返回一个对象，其 `isNullObject` 属性设置为 `true`。有关详细信息，请参阅 *OrNullObject 方法和属性。
getPrevious(visibleOnly)	获取此工作表之前的工作表。如果没有以前的工作表，此方法将引发错误。
getPreviousOrNullObject(visibleOnly)	获取此工作表之前的工作表。如果没有以前的工作表，则此方法返回一个对象，其 `isNullObject` 属性设置为 `true`。有关详细信息，请参阅 *OrNullObject 方法和属性。
getRange(address)	`Range`获取对象，该对象表示由地址或名称指定的单个矩形单元格块。
getUsedRange(valuesOnly)	使用的区域是包含分配了值或格式化的任何单元格的最小区域。如果整个工作表为空，此函数将返回左上角的单元格 (即不会) 引发错误。
getUsedRangeOrNullObject(valuesOnly)	使用的区域是包含分配了值或格式化的任何单元格的最小区域。如果整个工作表为空，则此方法返回一个对象，其 `isNullObject` 属性设置为 `true`。有关详细信息，请参阅 *OrNullObject 方法和属性。
load(options)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNames)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNamesAndPaths)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
set(properties, options)	同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。
set(properties)	基于现有的已加载对象，同时对对象设置多个属性。
toJSON()	重写 JavaScript `toJSON()` 方法，以便在将 API 对象传递给 `JSON.stringify()`时提供更有用的输出。 `JSON.stringify` (，反过来又调用`toJSON`传递给它的对象的方法。) 而原始 Excel.Worksheet 对象是 API 对象，`toJSON`该方法返回一个纯 JavaScript 对象， (类型为 `Excel.Interfaces.WorksheetData`) ，其中包含从原始对象加载的任何子属性的浅表副本。

属性详细信息

charts

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

readonly charts: Excel.ChartCollection;

属性值

Excel.ChartCollection

注解

[ API 集：ExcelApi 1.1 ]

context

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

context: RequestContext;

属性值

Excel.RequestContext

id

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

readonly id: string;

属性值

string

注解

[ API 集：ExcelApi 1.1 ]

name

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

name: string;

属性值

string

注解

[ API 集：ExcelApi 1.1 ]

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

注解

[ API 集：ExcelApi 1.1 ]

示例

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

tables

属于工作表的表的集合。

readonly tables: Excel.TableCollection;

属性值

Excel.TableCollection

注解

[ API 集：ExcelApi 1.1 ]

visibility

工作表的可见性。

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

属性值

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

注解

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

方法详细信息

activate()

在 Excel UI 中激活工作表。

activate(): void;

void

注解

[ API 集：ExcelApi 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

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

void

注解

[ API 集：ExcelApi 1.6 ]

delete()

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

delete(): void;

void

注解

[ API 集：ExcelApi 1.1 ]

示例

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

注解

[ API 集：ExcelApi 1.1 ]

示例

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

注解

[ API 集：ExcelApi 1.5 ]

示例

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

注解

[ API 集：ExcelApi 1.5 ]

getPrevious(visibleOnly)

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

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

参数

visibleOnly: boolean

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

Excel.Worksheet

注解

[ API 集：ExcelApi 1.5 ]

示例

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

注解

[ API 集：ExcelApi 1.5 ]

getRange(address)

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

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

参数

address: string

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

Excel.Range

注解

[ API 集：ExcelApi 1.1 ]

示例

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

getUsedRange(valuesOnly)

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

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

参数

valuesOnly: boolean

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

Excel.Range

注解

[ API 集：ExcelApi 1.1 ]

示例

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

通过

Excel.Worksheet class

注解

示例

属性

方法

属性详细信息

charts

属性值

注解

context

属性值

id

属性值

注解

name

属性值

注解

names

属性值

注解

pivotTables

属性值

注解

示例

position

属性值

注解

示例

protection

属性值

注解

示例

tables

属性值

注解

visibility

属性值

注解

方法详细信息

activate()

返回

注解

示例

calculate(markAllDirty)

参数

返回

注解

delete()

返回

注解

示例

getCell(row, column)

参数

返回

注解

示例

getNext(visibleOnly)

参数

返回

注解

示例

getNextOrNullObject(visibleOnly)

参数

返回

注解

getPrevious(visibleOnly)

参数

返回

注解

示例

getPreviousOrNullObject(visibleOnly)

参数

返回

注解

getRange(address)

参数

返回

注解

示例