ExcelScript.Worksheet interface

包:

ExcelScript

Excel 工作表是由单元格组成的网格。 它可以包含数据、表、图表等。

注解

示例

/**
 * This script creates a new worksheet named "Plum" and sets its tab color to purple.
 */
function main(workbook: ExcelScript.Workbook) {
  const newSheet = workbook.addWorksheet("Plum")
  newSheet.setTabColor("purple");
}

方法

activate()	在 Excel UI 中激活工作表。
addChart(type, sourceData, seriesBy)	创建新图表。
addComment(cellAddress, content, contentType)	使用给定单元格上的给定内容创建新批注。 InvalidArgument如果提供的范围大于一个单元格，则会引发错误。
addGeometricShape(geometricShapeType)	将几何形状添加到工作表。 返回表示 Shape 新形状的 对象。
addGroup(values)	在此集合的工作表中对形状的子集进行分组。 返回一个 Shape 对象，该对象代表新的形状组。
addHorizontalPageBreak(pageBreakRange)	在指定区域的左上角单元格之前添加分页符。
addImage(base64ImageString)	从 base64 编码的字符串创建图像并将其添加到工作表。 返回 Shape 表示新图像的 对象。
addLine(startLeft, startTop, endLeft, endTop, connectorType)	将线条添加到工作表。 返回表示 Shape 新行的 对象。
addNamedItem(name, reference, comment)	将新名称添加到给定范围的集合。
addNamedItemFormulaLocal(name, formula, comment)	使用用户的公式区域设置，将新名称添加到给定范围的集合。
addNamedSheetView(name)	创建具有给定名称的新工作表视图。
addPivotTable(name, source, destination)	根据指定的源数据添加数据透视表，并将其插入目标区域的左上角单元格。
addSlicer(slicerSource, sourceField, slicerDestination)	将新切片器添加到工作簿。
addTable(address, hasHeaders)	创建一个新表。 范围对象或源地址决定了在哪个工作表下添加表。 如果无法添加表（例如，由于地址无效，或者表与另一个表重叠），则会引发错误。
addTextBox(text)	使用提供的文本作为内容，将文本框添加到工作表。 返回表示 Shape 新文本框的 对象。
addVerticalPageBreak(pageBreakRange)	在指定区域的左上角单元格之前添加分页符。
addWorksheetCustomProperty(key, value)	添加映射到提供的键的新自定义属性。 这将使用该键覆盖现有自定义属性。
calculate(markAllDirty)	计算工作表上的所有单元格。
copy(positionType, relativeTo)	复制工作表并将其放置在指定位置。
delete()	从工作簿中删除工作表。 请注意，如果工作表的可见性设置为“VeryHidden”，则删除操作将失败并出现 InvalidOperation 异常。 删除之前，应首先将其可见性更改为隐藏或可见。
enterTemporaryNamedSheetView()	创建并激活新的临时工作表视图。 关闭应用程序、使用 exit 方法退出临时视图或切换到另一个工作表视图时，将删除临时视图。 如果临时视图存在，也可以使用空字符串 (“”) 访问临时工作表视图。
exitActiveNamedSheetView()	退出当前活动的工作表视图。
findAll(text, criteria)	根据指定的条件查找给定字符串的所有匹配项，并将其作为 RangeAreas 对象返回，包括一个或多个矩形区域。
getActiveNamedSheetView()	获取工作表的当前活动工作表视图。
getAutoFilter()	表示 AutoFilter 工作表的 对象。
getCell(row, column)	Range获取包含基于行号和列号的单个单元格的对象。 单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。
getChart(name)	使用图表名称获取图表。 如果存在多个名称相同的图表，将返回第一个图表。 如果图表不存在，则此方法返回 undefined。
getCharts()	返回属于工作表的图表集合。
getComment(commentId)	根据其 ID 从集合中获取批注。 如果注释对象不存在，则此方法返回 undefined。
getCommentByCell(cellAddress)	从指定单元格获取的批注。 如果单元格中没有注释，则会引发错误。
getCommentByReplyId(replyId)	获取给定答复所连接到的注释。
getComments()	返回工作表上的所有 Comments 对象的集合。
getCustomProperties()	获取工作表级自定义属性的集合。
getEnableCalculation()	确定 Excel 是否应在必要时重新计算工作表。 如此 如果 Excel 在必要时重新计算工作表。 如果 Excel 不重新计算工作表，则该值为 False。
getFreezePanes()	获取一个对象，该对象可用于操作工作表上的冻结窗格。
getHorizontalPageBreaks()	获取工作表的水平分页符集合。 此集合仅包含手动分页符。
getId()	返回用于唯一标识指定工作簿中工作表的值。 即使工作表被重命名或移动，标识符的值仍然相同。
getName()	工作表的显示名称。
getNamedItem(name)	NamedItem使用其名称获取对象。 如果该对象不存在，则此方法返回 undefined。
getNamedSheetView(key)	使用其名称获取工作表视图。 如果工作表视图对象不存在，则此方法返回 undefined。
getNamedSheetViews()	返回工作表中存在的工作表视图的集合。
getNames()	一组范围限定到当前工作表的名称。
getNext(visibleOnly)	获取此工作表后面的工作表。 如果此工作表之后没有工作表，则此方法返回 undefined。
getPageLayout()	获取 PageLayout 工作表的 对象。
getPivotTable(name)	按名称获取 PivotTable 对象。 如果数据透视表不存在，则此方法返回 undefined。
getPivotTables()	一组属于工作表的数据透视表对象。
getPosition()	工作表在工作簿中的位置，从零开始。
getPrevious(visibleOnly)	获取此工作表之前的工作表。 如果没有以前的工作表，则此方法返回 undefined。
getProtection()	返回工作表的工作表保护对象。
getRange(address)	Range获取 对象，该对象表示由地址或名称指定的单个矩形单元格块。
getRangeByIndexes(startRow, startColumn, rowCount, columnCount)	获取对象， Range 从特定的行索引和列索引开始，并跨越一定数量的行和列。
getRanges(address)	RangeAreas获取 对象，该对象表示由地址或名称指定的一个或多个矩形区域块。
getShape(key)	使用形状的名称或 ID 获取形状。 如果形状对象不存在，则此方法返回 undefined。
getShapes()	返回工作表上的所有 Shape 对象的集合。
getShowGridlines()	指定网格线是否对用户可见。
getShowHeadings()	指定标题是否对用户可见。
getSlicer(key)	使用切片器的名称或 ID 获取切片器。 如果切片器不存在，则此方法返回 undefined。
getSlicers()	返回属于工作表的切片器的集合。
getStandardHeight()	返回工作表中所有行的标准（默认）行高，以磅为单位。
getStandardWidth()	指定工作表中所有列的标准 (默认) 宽度。 一个列宽单位等于“常规”样式中一个字符的宽度。 对于比例字体，则使用字符 0（零）的宽度。
getTabColor()	工作表的选项卡颜色。 检索选项卡颜色时，如果工作表不可见，则值为 null。 如果工作表可见，但选项卡颜色设置为 auto，将返回空字符串。 否则，属性将设置为颜色，格式 #RRGGBB (例如“FFA500”) 。 设置颜色时，请使用空字符串设置“自动”颜色，否则使用实色。
getTabId()	返回一个值，该值表示可由 Open Office XML 读取的此工作表。 这是一个整数值，它不同于 worksheet.id (返回全局唯一标识符) 和 worksheet.name 返回值（如“Sheet1”) ）的 (。
getTable(key)	按名称或 ID 获取表。 如果该表不存在，则此方法返回 undefined。
getTables()	属于工作表的表的集合。
getUsedRange(valuesOnly)
getVerticalPageBreaks()	获取工作表的垂直分页符集合。 此集合仅包含手动分页符。
getVisibility()	工作表的可见性。
getWorksheetCustomProperty(key)	按键获取自定义属性对象（不区分大小写）。 如果自定义属性不存在，则此方法返回 undefined。
refreshAllPivotTables()	刷新集合中的所有数据透视表。
removeAllHorizontalPageBreaks()	重置集合中的所有手动分页符。
removeAllVerticalPageBreaks()	重置集合中的所有手动分页符。
replaceAll(text, replacement, criteria)	根据当前工作表中指定的条件查找并替换给定的字符串。
setEnableCalculation(enableCalculation)	确定 Excel 是否应在必要时重新计算工作表。 如此 如果 Excel 在必要时重新计算工作表。 如果 Excel 不重新计算工作表，则该值为 False。
setName(name)	工作表的显示名称。
setPosition(position)	工作表在工作簿中的位置，从零开始。
setShowGridlines(showGridlines)	指定网格线是否对用户可见。
setShowHeadings(showHeadings)	指定标题是否对用户可见。
setStandardWidth(standardWidth)	指定工作表中所有列的标准 (默认) 宽度。 一个列宽单位等于“常规”样式中一个字符的宽度。 对于比例字体，则使用字符 0（零）的宽度。
setTabColor(tabColor)	工作表的选项卡颜色。 检索选项卡颜色时，如果工作表不可见，则值为 null。 如果工作表可见，但选项卡颜色设置为 auto，将返回空字符串。 否则，属性将设置为颜色，格式 #RRGGBB (例如“FFA500”) 。 设置颜色时，请使用空字符串设置“自动”颜色，否则使用实色。
setVisibility(visibility)	工作表的可见性。
showOutlineLevels(rowLevels, columnLevels)	按大纲级别显示行或列组。 在工作表中概述组和汇总数据列表。 rowLevels和 columnLevels 参数指定显示大纲的级别。 可接受的参数范围介于 0 和 8 之间。 值为 0 不会更改当前显示。 大于当前级别数的值将显示所有级别。

方法详细信息

activate()

在 Excel UI 中激活工作表。

activate(): void;

返回

void

示例

/**
 * This script switches the active view to a worksheet named "Data", if it exists.
 */
function main(workbook: ExcelScript.Workbook) {
  // Check if the "Data" worksheet exists.
  let dataWorksheet = workbook.getWorksheet("Data");
  if (dataWorksheet) {
    // Switch to the "Data" worksheet.
    dataWorksheet.activate();
  } else {
    console.log(`No worksheet named "Data" in this workbook.`);
  }
}

addChart(type, sourceData, seriesBy)

创建新图表。

addChart(
            type: ChartType,
            sourceData: Range,
            seriesBy?: ChartSeriesBy
        ): Chart;

参数

type

ExcelScript.ChartType

表示图表的类型。 有关详细信息，请参阅 ExcelScript.ChartType。

sourceData

ExcelScript.Range

对应于 Range 源数据的对象。

seriesBy

ExcelScript.ChartSeriesBy

可选。 指定列或行在图表上用作数据系列的方式。 有关详细信息，请参阅 ExcelScript.ChartSeriesBy。

返回

ExcelScript.Chart

示例

/**
 * This sample creates a column-clustered chart based on the current worksheet's data.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the data range.
  let range = selectedSheet.getUsedRange();

  // Insert a chart using the data on the current worksheet.
  let chart = selectedSheet.addChart(ExcelScript.ChartType.columnClustered, range);

  // Name the chart for easy access in other scripts.
  chart.setName("ColumnChart");
}

addComment(cellAddress, content, contentType)

使用给定单元格上的给定内容创建新批注。 InvalidArgument如果提供的范围大于一个单元格，则会引发错误。

addComment(
            cellAddress: Range | string,
            content: CommentRichContent | string,
            contentType?: ContentType
        ): Comment;

参数

cellAddress

ExcelScript.Range | string

要向其添加注释的单元格。 这可以是 Range 对象或字符串。 如果是字符串，则必须包含完整地址，包括工作表名称。 InvalidArgument如果提供的范围大于一个单元格，则会引发错误。

content

ExcelScript.CommentRichContent | string

批注的内容。 这可以是字符串或 CommentRichContent 对象。 字符串用于纯文本。 CommentRichContent 对象允许使用其他注释功能，例如提及。

contentType

ExcelScript.ContentType

可选。 批注中包含的内容类型。 默认值为 enum ContentType.Plain。

返回

ExcelScript.Comment

addGeometricShape(geometricShapeType)

将几何形状添加到工作表。 返回表示 Shape 新形状的 对象。

addGeometricShape(geometricShapeType: GeometricShapeType): Shape;

参数

geometricShapeType

ExcelScript.GeometricShapeType

表示几何形状的类型。 有关详细信息，请参阅 ExcelScript.GeometricShapeType。

返回

ExcelScript.Shape

示例

/**
 * This script creates a hexagon shape on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const hexagon: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the hexagon size to 40x40 pixels.
  hexagon.setHeight(40);
  hexagon.setWidth(40);

  // Position the hexagon at [100,100] pixels.
  hexagon.setLeft(100);
  hexagon.setTop(100);
}

addGroup(values)

在此集合的工作表中对形状的子集进行分组。 返回一个 Shape 对象，该对象代表新的形状组。

addGroup(values: Array<string | Shape>): Shape;

参数

values

Array<string | ExcelScript.Shape>

形状 ID 或形状对象的数组。

返回

ExcelScript.Shape

addHorizontalPageBreak(pageBreakRange)

在指定区域的左上角单元格之前添加分页符。

addHorizontalPageBreak(pageBreakRange: Range | string): PageBreak;

参数

pageBreakRange

ExcelScript.Range | string

要添加的分页符后面的区域。

返回

ExcelScript.PageBreak

addImage(base64ImageString)

从 base64 编码的字符串创建图像并将其添加到工作表。 返回 Shape 表示新图像的 对象。

addImage(base64ImageString: string): Shape;

参数

base64ImageString

string

一个 base64 编码的字符串，表示 JPEG 或 PNG 格式的图像。

返回

ExcelScript.Shape

示例

/**
 * This sample copies an image from a URL. 
 * This could be used to copy photos that a colleague stored in a shared folder to a related workbook.
 */
async function main(workbook: ExcelScript.Workbook) {
  // Fetch the image from a URL.
  const link = "https://raw.githubusercontent.com/OfficeDev/office-scripts-docs/master/docs/images/git-octocat.png";
  const response = await fetch(link);

  // Store the response as an ArrayBuffer, since it is a raw image file.
  const data = await response.arrayBuffer();

  // Convert the image data into a base64-encoded string.
  const image = convertToBase64(data);

  // Add the image to the current worksheet.
  workbook.getActiveWorksheet().addImage(image);
}

/**
 * Converts an ArrayBuffer containing a .png image into a base64-encoded string.
 */
function convertToBase64(input: ArrayBuffer) {
  const uInt8Array = new Uint8Array(input);
  const count = uInt8Array.length;

  // Allocate the necessary space up front.
  const charCodeArray = new Array<string>(count) 
  
  // Convert every entry in the array to a character.
  for (let i = count; i >= 0; i--) { 
    charCodeArray[i] = String.fromCharCode(uInt8Array[i]);
  }

  // Convert the characters to base64.
  const base64 = btoa(charCodeArray.join(''));
  return base64;
}

addLine(startLeft, startTop, endLeft, endTop, connectorType)

将线条添加到工作表。 返回表示 Shape 新行的 对象。

addLine(
            startLeft: number,
            startTop: number,
            endLeft: number,
            endTop: number,
            connectorType?: ConnectorType
        ): Shape;

参数

startLeft

number

从行开始到工作表左侧的距离（以磅为单位）。

startTop

number

从行开始到工作表顶部的距离（以磅为单位）。

endLeft

number

从行尾到工作表左侧的距离（以磅为单位）。

endTop

number

从行尾到工作表顶部的距离（以磅为单位）。

connectorType

ExcelScript.ConnectorType

表示连接器类型。 有关详细信息，请参阅 ExcelScript.ConnectorType。

返回

ExcelScript.Shape

addNamedItem(name, reference, comment)

将新名称添加到给定范围的集合。

addNamedItem(
            name: string,
            reference: Range | string,
            comment?: string
        ): NamedItem;

参数

name

string

已命名项目的名称。

reference

ExcelScript.Range | string

名称将引用的公式或区域。

comment

string

可选。 与命名项关联的注释。

返回

ExcelScript.NamedItem

addNamedItemFormulaLocal(name, formula, comment)

使用用户的公式区域设置，将新名称添加到给定范围的集合。

addNamedItemFormulaLocal(
            name: string,
            formula: string,
            comment?: string
        ): NamedItem;

参数

name

string

已命名项目的名称。

formula

string

名称将引用的采用用户区域设置的公式。

comment

string

可选。 与命名项关联的注释。

返回

ExcelScript.NamedItem

addNamedSheetView(name)

创建具有给定名称的新工作表视图。

addNamedSheetView(name: string): NamedSheetView;

参数

name

string

要创建的工作表视图的名称。 如果提供的名称已存在、为空或是工作表保留的名称，则引发错误。

返回

ExcelScript.NamedSheetView

addPivotTable(name, source, destination)

根据指定的源数据添加数据透视表，并将其插入目标区域的左上角单元格。

addPivotTable(
            name: string,
            source: Range | string | Table,
            destination: Range | string
        ): PivotTable;

参数

name

string

新数据透视表的名称。

source

ExcelScript.Range | string | ExcelScript.Table

新数据透视表的源数据可以是区域 (，也可以是字符串地址，包括工作表名称) 或表格。

destination

ExcelScript.Range | string

数据透视表目标区域（工作表中用于放置所生成的报表的区域）左上角的单元格。

返回

ExcelScript.PivotTable

示例

/**
 * This script creates a PivotTable from an existing table and adds it to a new worksheet.
 * This script assumes there is a table in the current worksheet with columns named "Type" and "Sales".
 */
function main(workbook: ExcelScript.Workbook) {
  // Create a PivotTable based on a table in the current worksheet.
  let sheet = workbook.getActiveWorksheet();
  let table = sheet.getTables()[0];

  // Add the PivotTable to a new worksheet.
  let newSheet = workbook.addWorksheet("Pivot");
  let pivotTable = newSheet.addPivotTable("My Pivot", table, "A1");

  // Add fields to the PivotTable to show "Sales" per "Type".
  pivotTable.addRowHierarchy(pivotTable.getHierarchy("Type"));
  pivotTable.addDataHierarchy(pivotTable.getHierarchy("Sales"));

  // Switch to the new worksheet.
  newSheet.activate();
}

addSlicer(slicerSource, sourceField, slicerDestination)

将新切片器添加到工作簿。

addSlicer(
            slicerSource: string | PivotTable | Table,
            sourceField: string | PivotField | number | TableColumn,
            slicerDestination?: string | Worksheet
        ): Slicer;

参数

slicerSource

string | ExcelScript.PivotTable | ExcelScript.Table

新切片器将基于的数据源。 它可以是 PivotTable 对象、 Table 对象或字符串。 传递数据透视表对象时，数据源是该 PivotTable 对象的源。 Table传递对象时，数据源为 Table 对象。 传递字符串时，它将解释为数据透视表或表的名称或 ID。

sourceField

string | ExcelScript.PivotField | number | ExcelScript.TableColumn

数据源中要筛选的字段。 它可以是 对象、TableColumn对象、的 PivotField ID 或 的名称或 IDTableColumn。PivotField

slicerDestination

string | ExcelScript.Worksheet

可选。 将在其中创建新切片器的工作表。 它可以是 Worksheet 对象，也可以是工作表的名称或 ID。 如果从工作表检索切片器集合，则可以省略此参数。

返回

ExcelScript.Slicer

示例

/**
 * This script adds a slicer for an existing PivotTable on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first PivotTable from the current worksheet.
  const currentSheet = workbook.getActiveWorksheet();
  const pivot = currentSheet.getPivotTables()[0];

  // Create the slicer. 
  // Note that this assumes "Type" is already added as a hierarchy to the PivotTable.
  const slicer = currentSheet.addSlicer(
    pivot, /* The table or PivotTale to be sliced. */
    pivot.getHierarchy("Type").getFields()[0] /* What source field to use as the slicer options. */
  );

  // Select the items to display.
  slicer.selectItems(["Lemon", "Lime"]);

  // Set the left margin of the slicer.
  slicer.setLeft(400);
}

addTable(address, hasHeaders)

创建一个新表。 范围对象或源地址决定了在哪个工作表下添加表。 如果无法添加表（例如，由于地址无效，或者表与另一个表重叠），则会引发错误。

addTable(address: Range | string, hasHeaders: boolean): Table;

参数

address

ExcelScript.Range | string

对象 Range ，或表示数据源的区域的字符串地址或名称。 如果地址不包含工作表名称，将使用当前活动的工作表。

hasHeaders

boolean

一个布尔值，指示导入的数据是否具有列标签。 如果源不包含标头 (即当此属性设置为 false) 时，Excel 将自动生成一个标题，并将数据向下移动一行。

返回

ExcelScript.Table

示例

/**
 * This sample creates a table from the current worksheet's used range, then sorts it based on the first column.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Create a table with the used cells.
  let usedRange = selectedSheet.getUsedRange();
  let newTable = selectedSheet.addTable(usedRange, true);

  // Sort the table using the first column.
  newTable.getSort().apply([{ key: 0, ascending: true }]);
}

addTextBox(text)

使用提供的文本作为内容，将文本框添加到工作表。 返回表示 Shape 新文本框的 对象。

addTextBox(text?: string): Shape;

参数

text

string

表示将在创建的文本框中显示的文本。

返回

ExcelScript.Shape

addVerticalPageBreak(pageBreakRange)

在指定区域的左上角单元格之前添加分页符。

addVerticalPageBreak(pageBreakRange: Range | string): PageBreak;

参数

pageBreakRange

ExcelScript.Range | string

要添加的分页符后面的区域。

返回

ExcelScript.PageBreak

addWorksheetCustomProperty(key, value)

添加映射到提供的键的新自定义属性。 这将使用该键覆盖现有自定义属性。

addWorksheetCustomProperty(
            key: string,
            value: string
        ): WorksheetCustomProperty;

参数

key

string

标识自定义属性对象的键。 它不区分大小写。键限制为 255 个字符， (较大的值将导致 InvalidArgument 引发错误。)

value

string

此自定义属性的值。

返回

ExcelScript.WorksheetCustomProperty

calculate(markAllDirty)

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

calculate(markAllDirty: boolean): void;

参数

markAllDirty

boolean

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

返回

void

copy(positionType, relativeTo)

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

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

参数

positionType

ExcelScript.WorksheetPositionType

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

relativeTo

ExcelScript.Worksheet

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

返回

ExcelScript.Worksheet

示例

/**
 * This script duplicates a worksheet named "Template". 
 * The new worksheet is added after the template.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the worksheet named "Template".
  let template = workbook.getWorksheet("Template");

  // Copy the worksheet.
  let newSheet = template.copy(
    ExcelScript.WorksheetPositionType.after,
    template
  );

  // Name the worksheet using the current date.
  let date = new Date(Date.now());
  newSheet.setName(`${date.toDateString()}`);
}

delete()

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

delete(): void;

返回

void

示例

/**
 * The following scripts removes the first worksheet in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first worksheet.
  let sheet = workbook.getWorksheets()[0];

  // Remove that worksheet from the workbook.
  sheet.delete();
}

enterTemporaryNamedSheetView()

创建并激活新的临时工作表视图。 关闭应用程序、使用 exit 方法退出临时视图或切换到另一个工作表视图时，将删除临时视图。 如果临时视图存在，也可以使用空字符串 (“”) 访问临时工作表视图。

enterTemporaryNamedSheetView(): NamedSheetView;

返回

ExcelScript.NamedSheetView

exitActiveNamedSheetView()

退出当前活动的工作表视图。

exitActiveNamedSheetView(): void;

返回

void

findAll(text, criteria)

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

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

参数

text

string

要查找的字符串。

criteria

ExcelScript.WorksheetSearchCriteria

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

返回

ExcelScript.RangeAreas

示例

/**
 * This script searches through a worksheet and finds cells containing "No". 
 * Those cells are filled red.
 * Use Range.find instead of Worksheet.findAll when you want to limit the search to a specific range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let worksheet = workbook.getActiveWorksheet();
  let noCells = worksheet.findAll("No", { completeMatch: true });

  // Set the fill color to red.
  noCells.getFormat().getFill().setColor("red");
}

getActiveNamedSheetView()

获取工作表的当前活动工作表视图。

getActiveNamedSheetView(): NamedSheetView;

返回

ExcelScript.NamedSheetView

getAutoFilter()

表示 AutoFilter 工作表的 对象。

getAutoFilter(): AutoFilter;

返回

ExcelScript.AutoFilter

示例

/**
 * This script creates an autoFilter on the worksheet that filters out rows based on column values. 
 * The autoFilter filters to only include rows that have a value in column D in the top 10 percentile 
 * (of column D values).
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const dataRange = currentSheet.getUsedRange();

  // Add a filter that will only show the rows with the top 10% of values in column D
  // (index 3, assuming the used range spans from at least A:D).
  currentSheet.getAutoFilter().apply(dataRange, 3, {
    criterion1: "10",
    filterOn: ExcelScript.FilterOn.topPercent
  });
}

getCell(row, column)

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

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

参数

row

number

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

column

number

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

返回

ExcelScript.Range

getChart(name)

使用图表名称获取图表。 如果存在多个名称相同的图表，将返回第一个图表。 如果图表不存在，则此方法返回 undefined。

getChart(name: string): Chart | undefined;

参数

name

string

要检索的图表的名称。

返回

ExcelScript.Chart | undefined

示例

/**
 * This sample moves an existing chart to a specific place on the worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();
  
  // Get an existing chart named "ColumnChart".
  let chart = selectedSheet.getChart("ColumnChart");

  // Place the chart over the range "F1:L13".
  chart.setPosition("F1", "L13");
}

getCharts()

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

getCharts(): Chart[];

返回

ExcelScript.Chart[]

getComment(commentId)

根据其 ID 从集合中获取批注。 如果注释对象不存在，则此方法返回 undefined。

getComment(commentId: string): Comment | undefined;

参数

commentId

string

注释的标识符。

返回

ExcelScript.Comment | undefined

getCommentByCell(cellAddress)

从指定单元格获取的批注。 如果单元格中没有注释，则会引发错误。

getCommentByCell(cellAddress: Range | string): Comment;

参数

cellAddress

ExcelScript.Range | string

注释所在的单元格。 这可以是 Range 对象或字符串。 如果是字符串，则必须包含完整地址，包括工作表名称。 InvalidArgument如果提供的范围大于一个单元格，则会引发错误。

返回

ExcelScript.Comment

getCommentByReplyId(replyId)

获取给定答复所连接到的注释。

getCommentByReplyId(replyId: string): Comment;

参数

replyId

string

批注回复的标识符。

返回

ExcelScript.Comment

getComments()

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

getComments(): Comment[];

返回

ExcelScript.Comment[]

getCustomProperties()

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

getCustomProperties(): WorksheetCustomProperty[];

返回

ExcelScript.WorksheetCustomProperty[]

getEnableCalculation()

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

getEnableCalculation(): boolean;

返回

boolean

getFreezePanes()

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

getFreezePanes(): WorksheetFreezePanes;

返回

ExcelScript.WorksheetFreezePanes

getHorizontalPageBreaks()

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

getHorizontalPageBreaks(): PageBreak[];

返回

ExcelScript.PageBreak[]

getId()

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

getId(): string;

返回

string

getName()

工作表的显示名称。

getName(): string;

返回

string

示例

/**
 * This sample gets all the worksheet names in the workbook.
 * It then logs those names to the console.
 */
function main(workbook: ExcelScript.Workbook) {
    // Create an array to hold the worksheet names.
    let worksheetNames = [];

    // Iterate over the worksheet collection in the workbook.
    for (let worksheet of workbook.getWorksheets()) {
        worksheetNames.push(worksheet.getName());
    }

    // Log the array of worksheet names.
    console.log(worksheetNames);
}

getNamedItem(name)

NamedItem使用其名称获取对象。 如果该对象不存在，则此方法返回 undefined。

getNamedItem(name: string): NamedItem | undefined;

参数

name

string

Nameditem name。

返回

ExcelScript.NamedItem | undefined

getNamedSheetView(key)

使用其名称获取工作表视图。 如果工作表视图对象不存在，则此方法返回 undefined。

getNamedSheetView(key: string): NamedSheetView | undefined;

参数

key

string

工作表视图的区分大小写的名称。 如果临时视图存在，请使用空字符串 (“”) 获取临时工作表视图。

返回

ExcelScript.NamedSheetView | undefined

getNamedSheetViews()

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

getNamedSheetViews(): NamedSheetView[];

返回

ExcelScript.NamedSheetView[]

getNames()

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

getNames(): NamedItem[];

返回

ExcelScript.NamedItem[]

getNext(visibleOnly)

获取此工作表后面的工作表。 如果此工作表之后没有工作表，则此方法返回 undefined。

getNext(visibleOnly?: boolean): Worksheet;

参数

visibleOnly

boolean

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

返回

ExcelScript.Worksheet

getPageLayout()

获取 PageLayout 工作表的 对象。

getPageLayout(): PageLayout;

返回

ExcelScript.PageLayout

示例

/**
 * This script sets the printing orientation for the entire workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Go to each worksheet so the print settings are consistent.
  workbook.getWorksheets().forEach((sheet) => {
    const pageLayout = sheet.getPageLayout();

    // Print every page with a landscape orientation.
    pageLayout.setOrientation(ExcelScript.PageOrientation.landscape);
  });
}

getPivotTable(name)

按名称获取 PivotTable 对象。 如果数据透视表不存在，则此方法返回 undefined。

getPivotTable(name: string): PivotTable | undefined;

参数

name

string

要检索的数据透视表的名称。

返回

ExcelScript.PivotTable | undefined

getPivotTables()

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

getPivotTables(): PivotTable[];

返回

ExcelScript.PivotTable[]

getPosition()

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

getPosition(): number;

返回

number

getPrevious(visibleOnly)

获取此工作表之前的工作表。 如果没有以前的工作表，则此方法返回 undefined。

getPrevious(visibleOnly?: boolean): Worksheet;

参数

visibleOnly

boolean

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

返回

ExcelScript.Worksheet

getProtection()

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

getProtection(): WorksheetProtection;

返回

ExcelScript.WorksheetProtection

示例

/**
 * This script protects cells from being selected on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the protection settings for the current worksheet.
  const currentSheet = workbook.getActiveWorksheet();
  const sheetProtection = currentSheet.getProtection();

  // Create a new WorksheetProtectionOptions object with the selectionMode property set to `none`.
  let protectionOptions : ExcelScript.WorksheetProtectionOptions = {
    selectionMode: ExcelScript.ProtectionSelectionMode.none
  }

  // Apply the given protection options.
  sheetProtection.protect(protectionOptions);
}

getRange(address)

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

getRange(address?: string): Range;

参数

address

string

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

返回

ExcelScript.Range

示例

/**
 * This sample reads the value of A1 and prints it to the console.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the value of cell A1.
  let range = selectedSheet.getRange("A1");
  
  // Print the value of A1.
  console.log(range.getValue());
}

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

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

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

参数

startRow

number

零索引) (起始行。

startColumn

number

零索引) (启动列。

rowCount

number

要包括在区域中的行数。

columnCount

number

要包括在区域中的列数。

返回

ExcelScript.Range

getRanges(address)

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

getRanges(address?: string): RangeAreas;

参数

address

string

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

返回

ExcelScript.RangeAreas

getShape(key)

使用形状的名称或 ID 获取形状。 如果形状对象不存在，则此方法返回 undefined。

getShape(key: string): Shape | undefined;

参数

key

string

要检索的形状的名称或 ID。

返回

ExcelScript.Shape | undefined

getShapes()

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

getShapes(): Shape[];

返回

ExcelScript.Shape[]

getShowGridlines()

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

getShowGridlines(): boolean;

返回

boolean

getShowHeadings()

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

getShowHeadings(): boolean;

返回

boolean

getSlicer(key)

使用切片器的名称或 ID 获取切片器。 如果切片器不存在，则此方法返回 undefined。

getSlicer(key: string): Slicer | undefined;

参数

key

string

要检索的切片器的名称或 ID。

返回

ExcelScript.Slicer | undefined

getSlicers()

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

getSlicers(): Slicer[];

返回

ExcelScript.Slicer[]

getStandardHeight()

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

getStandardHeight(): number;

返回

number

getStandardWidth()

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

getStandardWidth(): number;

返回

number

getTabColor()

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

getTabColor(): string;

返回

string

getTabId()

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

getTabId(): number;

返回

number

getTable(key)

按名称或 ID 获取表。 如果该表不存在，则此方法返回 undefined。

getTable(key: string): Table | undefined;

参数

key

string

要检索的表的名称或 ID。

返回

ExcelScript.Table | undefined

getTables()

属于工作表的表的集合。

getTables(): Table[];

返回

ExcelScript.Table[]

getUsedRange(valuesOnly)

getUsedRange(valuesOnly?: boolean): Range;

参数

valuesOnly

boolean

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

返回

ExcelScript.Range

getVerticalPageBreaks()

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

getVerticalPageBreaks(): PageBreak[];

返回

ExcelScript.PageBreak[]

getVisibility()

工作表的可见性。

getVisibility(): SheetVisibility;

返回

ExcelScript.SheetVisibility

getWorksheetCustomProperty(key)

按键获取自定义属性对象（不区分大小写）。 如果自定义属性不存在，则此方法返回 undefined。

getWorksheetCustomProperty(
            key: string
        ): WorksheetCustomProperty | undefined;

参数

key

string

标识自定义属性对象的键。 它不区分大小写。

返回

ExcelScript.WorksheetCustomProperty | undefined

refreshAllPivotTables()

刷新集合中的所有数据透视表。

refreshAllPivotTables(): void;

返回

void

removeAllHorizontalPageBreaks()

重置集合中的所有手动分页符。

removeAllHorizontalPageBreaks(): void;

返回

void

removeAllVerticalPageBreaks()

重置集合中的所有手动分页符。

removeAllVerticalPageBreaks(): void;

返回

void

replaceAll(text, replacement, criteria)

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

replaceAll(
            text: string,
            replacement: string,
            criteria: ReplaceCriteria
        ): number;

参数

text

string

要查找的字符串。

replacement

string

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

criteria

ExcelScript.ReplaceCriteria

其他替换条件。

返回

number

setEnableCalculation(enableCalculation)

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

setEnableCalculation(enableCalculation: boolean): void;

参数

enableCalculation

boolean

返回

void

setName(name)

工作表的显示名称。

setName(name: string): void;

参数

name

string

返回

void

示例

/**
 * This sample renames a worksheet from "Sheet1" to "SALES".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get a worksheet named "Sheet1".
  const sheet = workbook.getWorksheet('Sheet1'); 

  // Set its name to SALES.
  sheet.setName('SALES');
}

setPosition(position)

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

setPosition(position: number): void;

参数

position

number

返回

void

示例

/**
 * This sample sets the worksheet named "SALES" as the first sheet in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get a worksheet named "SALES".
  const sheet = workbook.getWorksheet('SALES'); 
  // Position the worksheet at the beginning of the workbook.
  sheet.setPosition(0);
}

setShowGridlines(showGridlines)

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

setShowGridlines(showGridlines: boolean): void;

参数

showGridlines

boolean

返回

void

setShowHeadings(showHeadings)

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

setShowHeadings(showHeadings: boolean): void;

参数

showHeadings

boolean

返回

void

setStandardWidth(standardWidth)

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

setStandardWidth(standardWidth: number): void;

参数

standardWidth

number

返回

void

setTabColor(tabColor)

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

setTabColor(tabColor: string): void;

参数

tabColor

string

返回

void

示例

/**
 * This script sets the tab color of every worksheet in the workbook to red.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get all the worksheets in the workbook. 
  let sheets = workbook.getWorksheets();
  
  // Set the tab color of each worksheet to a random color.
  for (let sheet of sheets) {    
    // Set the color of the current worksheet's tab to red.
    sheet.setTabColor("red");
  }
}

setVisibility(visibility)

工作表的可见性。

setVisibility(visibility: SheetVisibility): void;

参数

visibility

ExcelScript.SheetVisibility

返回

void

示例

/**
 * This script unhides all the worksheets in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Iterate over each worksheet.
  workbook.getWorksheets().forEach((worksheet) => {
    // Set the worksheet visibility to visible.
    worksheet.setVisibility(ExcelScript.SheetVisibility.visible);
  });
}

showOutlineLevels(rowLevels, columnLevels)

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

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

参数

rowLevels

number

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

columnLevels

number

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

返回

void