Excel. Workbook class

autoSave

指定工作簿是否处于自动保存模式。

readonly autoSave: boolean;

属性值

boolean

注解

bindings

表示属于工作簿的绑定的集合。

readonly bindings: Excel.BindingCollection;

属性值

Excel.BindingCollection

注解

calculationEngineVersion

返回有关 Excel 计算引擎的版本号。

readonly calculationEngineVersion: number;

属性值

number

注解

chartDataPointTrack

如果工作簿中的所有图表都跟踪它们所附加的实际数据点，则为 True。如果图表跟踪数据点的索引，则为 False。

chartDataPointTrack: boolean;

属性值

boolean

注解

comments

表示与工作簿关联的注释集合。

readonly comments: Excel.CommentCollection;

属性值

Excel.CommentCollection

注解

context

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

context: RequestContext;

属性值

Excel.RequestContext

customXmlParts

表示此工作簿包含的自定义 XML 部件的集合。

readonly customXmlParts: Excel.CustomXmlPartCollection;

属性值

Excel.CustomXmlPartCollection

注解

API 集：ExcelApi 1.5

dataConnections

表示工作簿中的所有数据连接。

readonly dataConnections: Excel.DataConnectionCollection;

属性值

Excel.DataConnectionCollection

注解

externalCodeServiceTimeout

注意

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

指定分配给依赖外部代码服务的公式完成的最大时间长度（以秒为单位）。有效范围为 1 到 86400（含）。

externalCodeServiceTimeout: number;

属性值

number

注解

functions

表示可用于计算的工作表函数集合。

readonly functions: Excel.Functions;

属性值

Excel.Functions

注解

API 集：ExcelApi 1.2

isDirty

指定自上次保存工作簿以来是否进行了更改。如果要关闭已修改的工作簿而不保存它或系统提示其保存，则可以将此属性设置为。true

isDirty: boolean;

属性值

boolean

注解

linkedEntityDataDomains

返回工作簿中可用的链接实体数据域的集合。

readonly linkedEntityDataDomains: Excel.LinkedEntityDataDomainCollection;

属性值

Excel.LinkedEntityDataDomainCollection

注解

API 集：ExcelApi 1.19

linkedWorkbooks

返回链接工作簿的集合。在公式中，工作簿链接可用于引用 (当前工作簿外部) 单元格值和名称的数据。

readonly linkedWorkbooks: Excel.LinkedWorkbookCollection;

属性值

Excel.LinkedWorkbookCollection

注解

API 集：ExcelApiOnline 1.1

localImage

注意

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

返回与工作簿关联的 LocalImage 对象。

readonly localImage: Excel.LocalImage;

属性值

Excel.LocalImage

注解

name

获取工作簿名称。

readonly name: string;

属性值

string

注解

names

表示工作簿范围内的命名项的集合， (命名范围和常量) 。

readonly names: Excel.NamedItemCollection;

属性值

Excel.NamedItemCollection

注解

notes

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

readonly notes: Excel.NoteCollection;

属性值

Excel.NoteCollection

注解

API 集：ExcelApi 1.18

pivotTables

表示一组与 workbook 相关联的 PivotTable 对象。

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 workbook.
  const pivotTables = context.workbook.pivotTables;
  pivotTables.load("name");
  await context.sync();

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

pivotTableStyles

表示一组与工作簿相关联的 PivotTableStyles。

readonly pivotTableStyles: Excel.PivotTableStyleCollection;

属性值

Excel.PivotTableStyleCollection

注解

previouslySaved

指定工作簿是保存在本地还是联机保存。

readonly previouslySaved: boolean;

属性值

boolean

注解

properties

获取工作簿属性。

readonly properties: Excel.DocumentProperties;

属性值

Excel.DocumentProperties

注解

示例

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

await Excel.run(async (context) => {
    let titleValue = "Excel document properties API";
    let subjectValue = "Set and get document properties";
    let keywordsValue = "Set and get operations";
    let commentsValue = "This is an Excel document properties API code sample";
    let categoryValue = "Office Add-ins";
    let managerValue = "John";
    let companyValue = "Microsoft";

    let docProperties = context.workbook.properties;

    // Set the writeable document properties.
    docProperties.title = titleValue;
    docProperties.subject = subjectValue;
    docProperties.keywords = keywordsValue;
    docProperties.comments = commentsValue;
    docProperties.category = categoryValue;
    docProperties.manager = managerValue;
    docProperties.company = companyValue;

    await context.sync();

    console.log("Set the following document properties: title, subject, keywords, comments, category, manager, company.");
});

protection

返回工作簿的保护对象。

readonly protection: Excel.WorkbookProtection;

属性值

Excel.WorkbookProtection

注解

queries

返回属于工作簿一部分的 Power Query 查询集合。

readonly queries: Excel.QueryCollection;

属性值

Excel.QueryCollection

注解

API 集：ExcelApi 1.14

readOnly

如果工作簿以只读模式打开，则返回 true 。

readonly readOnly: boolean;

属性值

boolean

注解

API 集：ExcelApi 1.8

sensitivityLabel

注意

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

返回工作簿的敏感度标签。

readonly sensitivityLabel: Excel.SensitivityLabel;

属性值

Excel.SensitivityLabel

注解

settings

表示与工作簿关联的设置集合。

readonly settings: Excel.SettingCollection;

属性值

Excel.SettingCollection

注解

API 集：ExcelApi 1.4

showPivotFieldList

注意

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

指定是否在工作簿级别显示数据透视表的字段列表窗格。

showPivotFieldList: boolean;

属性值

boolean

注解

slicers

表示与工作簿关联的切片器的集合。

readonly slicers: Excel.SlicerCollection;

属性值

Excel.SlicerCollection

注解

slicerStyles

表示一组与工作簿相关联的 SlicerStyles。

readonly slicerStyles: Excel.SlicerStyleCollection;

属性值

Excel.SlicerStyleCollection

注解

styles

表示与工作簿关联的样式的集合。

readonly styles: Excel.StyleCollection;

属性值

Excel.StyleCollection

注解

示例

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

await Excel.run(async (context) => {
    let styles = context.workbook.styles;

    // Add a new style to the style collection.
    // Styles is in the Home tab ribbon.
    styles.add("Diagonal Orientation Style");
          
    let newStyle = styles.getItem("Diagonal Orientation Style");
    
    // The "Diagonal Orientation Style" properties.
    newStyle.textOrientation = 38;
    newStyle.autoIndent = true;
    newStyle.includeProtection = true;
    newStyle.shrinkToFit = true;
    newStyle.locked = false;
    
    await context.sync();

    console.log("Successfully added a new style with diagonal orientation to the Home tab ribbon.");
});

tables

表示与工作簿关联的表的集合。

readonly tables: Excel.TableCollection;

属性值

Excel.TableCollection

注解

tableStyles

表示一组与工作簿相关联的 TableStyles。

readonly tableStyles: Excel.TableStyleCollection;

属性值

Excel.TableStyleCollection

注解

tasks

注意

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

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

readonly tasks: Excel.DocumentTaskCollection;

属性值

Excel.DocumentTaskCollection

注解

timelineStyles

表示一组与工作簿相关联的 TimelineStyles。

readonly timelineStyles: Excel.TimelineStyleCollection;

属性值

Excel.TimelineStyleCollection

注解

use1904DateSystem

注意

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

如果工作簿使用 1904 日期系统，则为 True。

use1904DateSystem: boolean;

属性值

boolean

注解

usePrecisionAsDisplayed

如果此工作簿中的计算仅使用显示的数字精度来完成，则为 True。将此属性从 false 切换到 true时，数据将永久失去准确性。

usePrecisionAsDisplayed: boolean;

属性值

boolean

注解

worksheets

表示与工作簿关联的工作表的集合。

readonly worksheets: Excel.WorksheetCollection;

属性值

Excel.WorksheetCollection

注解

autorunEventCompleted(AutorunEventCompletedOptions)

注意

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

通知主机应用程序，该加载项的代码已在自动运行事件中完成运行。

autorunEventCompleted(AutorunEventCompletedOptions: Excel.AutorunEventCompletedOptions): void;

参数

AutorunEventCompletedOptions: Excel.AutorunEventCompletedOptions

必填。用于完成自动运行事件的选项。

返回

void

注解

close(closeBehavior)

关闭当前工作簿。

close(closeBehavior?: Excel.CloseBehavior): void;

参数

closeBehavior: Excel.CloseBehavior

工作簿关闭行为。

返回

void

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml

await Excel.run(async (context) => {
    context.workbook.close(Excel.CloseBehavior.save);
});

close(closeBehavior)

关闭当前工作簿。

close(closeBehavior?: "Save" | "SkipSave"): void;

参数

closeBehavior: "Save" | "SkipSave"

工作簿关闭行为。

返回

void

注解

API 集：ExcelApiDesktop 1.1

focus()

将焦点置于工作簿上。这会导致 Excel 网格或当前活动的对象接收键盘事件。

focus(): void;

返回

void

注解

getActiveCell()

获取工作簿中当前处于活动状态的单元格。

getActiveCell(): Excel.Range;

返回

Excel.Range

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-get-active-cell.yaml

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

    let myWorkbook = context.workbook;
    let activeCell = myWorkbook.getActiveCell();
    activeCell.load("address");

    await context.sync();
    
    console.log("The active cell is " + activeCell.address);
});

getActiveChart()

获取工作簿中的当前活动图表。如果没有活动图表， ItemNotFound 将引发异常。

getActiveChart(): Excel.Chart;

返回

Excel.Chart

注解

getActiveChartOrNullObject()

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

getActiveChartOrNullObject(): Excel.Chart;

返回

Excel.Chart

注解

getActiveShape()

获取工作簿中的活动形状。如果没有活动形状，则引发 ItemNotFound 错误。

getActiveShape(): Excel.Shape;

返回

Excel.Shape

注解

API 集：ExcelApi 1.19

getActiveShapeOrNullObject()

获取工作簿中的活动形状。如果没有活动形状，则此方法返回其 isNullObject 属性设置为 true的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。

getActiveShapeOrNullObject(): Excel.Shape;

返回

Excel.Shape

注解

API 集：ExcelApi 1.19

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-get-active.yaml

// This method gets the active shape and displays it as an image in the task pane.
await Excel.run(async (context) => {
  // Get the currently active shape, if any.
  const activeShape = context.workbook.getActiveShapeOrNullObject();
  
  if (activeShape) {
    // Convert the active shape to an image.
    const shapeImage = activeShape.getAsImage(Excel.PictureFormat.png);
    await context.sync();
    
    // Display the image in the task pane.
    const imageContainer = document.getElementById("image");
    imageContainer.innerHTML = ''; // Clear the container before adding a new image.
    const imageElement = document.createElement("img");
    imageElement.src = "data:image/png;base64," + shapeImage.value;
    imageContainer.appendChild(imageElement);              
  } else {
    console.log("No active shape");
  }
});

getActiveSlicer()

获取工作簿中当前处于活动状态的切片器。如果没有活动切片器， ItemNotFound 将引发异常。

getActiveSlicer(): Excel.Slicer;

返回

Excel.Slicer

注解

getActiveSlicerOrNullObject()

获取工作簿中当前处于活动状态的切片器。如果没有活动切片器，则此方法返回其 isNullObject 属性设置为 true的对象。有关详细信息，请参阅 *OrNullObject 方法和属性。

getActiveSlicerOrNullObject(): Excel.Slicer;

返回

Excel.Slicer

注解

getIsActiveCollabSession()

如果工作簿正由多个用户 (通过共同创作) 编辑，则返回 true 。请注意，在工作簿状态更改与更改反映在方法结果之间可能会有一些延迟。

getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;

返回

OfficeExtension.ClientResult<boolean>

注解

OfficeExtension.ClientResult<Excel.LinkedEntityCellValue>

getLinkedEntityCellValue(linkedEntityCellValueId)

LinkedEntityCellValue根据提供的LinkedEntityId返回 .

getLinkedEntityCellValue(linkedEntityCellValueId: LinkedEntityId): OfficeExtension.ClientResult<LinkedEntityCellValue>;

参数

linkedEntityCellValueId: Excel.LinkedEntityId

指定个人 LinkedEntityCellValue的标识符。

返回

注解

API 集：ExcelApi 1.16

getSelectedRange()

从工作簿中获取当前选择的单个范围。如果选择了多个区域，则此方法将抛出错误。

getSelectedRange(): Excel.Range;

返回

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const selectedRange = context.workbook.getSelectedRange();
    selectedRange.load('address');
    await context.sync();
    console.log(selectedRange.address);
});

getSelectedRanges()

从工作簿中获取当前选定的一个或多个区域。与不同， getSelectedRange()此方法返回表示 RangeAreas 所有选定范围的对象。

getSelectedRanges(): Excel.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 selectedRanges = context.workbook.getSelectedRanges();
    selectedRanges.format.fill.color = "lightblue";

    await context.sync();
})

inPreviewMode()

注意

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

返回工作簿当前是否处于预览模式。

inPreviewMode(): OfficeExtension.ClientResult<boolean>;

返回

OfficeExtension.ClientResult<boolean>

注解

insertWorksheetsFromBase64(base64File, options)

将源工作簿中的指定工作表插入到当前工作簿中。

extensionHardening Windows 注册表项会影响此 API。参数定义 base64File 的文件扩展名必须与插入文件的实际文件类型匹配。如果设置为拒绝不匹配且文件扩展名与实际文件类型不匹配，则 extensionHardening 此 API 将引发以下错误：“由于扩展强化策略，不允许此操作。”

insertWorksheetsFromBase64(base64File: string, options?: Excel.InsertWorksheetOptions): OfficeExtension.ClientResult<string[]>;

参数

base64File: string

必填。表示源工作簿文件的 Base64 编码字符串。

options: Excel.InsertWorksheetOptions

可选。用于定义要插入哪些工作表以及新工作表将在工作簿中的何处插入的选项。默认情况下，源工作簿中的所有工作表都插入到当前工作簿的末尾。

返回

OfficeExtension.ClientResult<string[]>

与每个新插入的工作表对应的 ID 数组。

注解

API 集：ExcelApi 1.13

此 API 目前仅支持 Windows 版、Mac 版和 Web 版。在 Excel web 版中，此 API 不支持插入图表、批注、数据透视表或切片器。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-insert-external-worksheets.yaml

// Retrieve the file and set up an HTML FileReader element. 
const myFile = document.getElementById("file") as HTMLInputElement;
const reader = new FileReader();

reader.onload = (event) => {
    // Remove the metadata before the Base64-encoded string.
    const startIndex = reader.result.toString().indexOf("base64,");
    externalWorkbook = reader.result.toString().substr(startIndex + 7);
};

// Read the file as a data URL so that we can parse the Base64-encoded string.
reader.readAsDataURL(myFile.files[0]);

...

await Excel.run(async (context) => {
    // Retrieve the source workbook.
    const workbook = context.workbook;
    
    // Set up the insert options.
    const options = {
        sheetNamesToInsert: [], // Insert all the worksheets from the source workbook.
        positionType: Excel.WorksheetPositionType.after, // Insert after the `relativeTo` sheet.
        relativeTo: "Sheet1" // The sheet relative to which the other worksheets will be inserted. Used with `positionType`.
    };
    
    // Insert the new worksheets.
    workbook.insertWorksheetsFromBase64(externalWorkbook, options);
    await context.sync();
});

load(options)

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

load(options?: Excel.Interfaces.WorkbookLoadOptions): Excel.Workbook;

参数

options: Excel.Interfaces.WorkbookLoadOptions

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

返回

Excel.Workbook

load(propertyNames)

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

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

参数

propertyNames: string | string[]

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

返回

Excel.Workbook

load(propertyNamesAndPaths)

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

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

参数

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

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

返回

Excel.Workbook

save(saveBehavior)

保存当前工作簿。

save(saveBehavior?: Excel.SaveBehavior): void;

参数

saveBehavior: Excel.SaveBehavior

保存行为必须为“保存”或“提示”。默认值为“保存”。

返回

void

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml

await Excel.run(async (context) => {
    context.workbook.save(Excel.SaveBehavior.save);
});

save(saveBehavior)

保存当前工作簿。

save(saveBehavior?: "Save" | "Prompt"): void;

参数

saveBehavior: "Save" | "Prompt"

保存行为必须为“保存”或“提示”。默认值为“保存”。

返回

void

注解

OfficeExtension.EventHandlers<Excel.WorkbookActivatedEventArgs>

set(properties, options)

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

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

参数

properties: Excel.Interfaces.WorkbookUpdateData

一个 JavaScript 对象，其属性与调用该方法的对象的属性同构结构。

options: OfficeExtension.UpdateOptions

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

返回

void

set(properties)

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

set(properties: Excel.Workbook): void;

参数

properties: Excel.Workbook

返回

void

toJSON()

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

toJSON(): Excel.Interfaces.WorkbookData;

返回

Excel.Interfaces.WorkbookData

onActivated

在激活工作簿时发生。注意：打开工作簿时不会触发此事件。

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

事件类型

注解

API 集：ExcelApi 1.13

示例

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

async function workbookActivated(event: Excel.WorkbookActivatedEventArgs) {
  await Excel.run(async (context) => {
    // Callback function for when the workbook is activated.
    console.log("The workbook was activated.");
  });
}

...

await Excel.run(async (context) => {
  const workbook = context.workbook;

  // Register the workbook activated event handler.
  workbook.onActivated.add(workbookActivated);

  await context.sync();
  console.log("Added event handler for workbook activated.");
});

onAutoSaveSettingChanged

当工作簿上的自动保存设置发生更改时发生。

readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;

事件类型

OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>

注解