Excel. Range class

addressLocal

表示用户语言中指定范围的范围引用。

readonly addressLocal: string;

属性值

string

注解

cellCount

指定区域中的单元格数。如果单元格数超过 2^31-1 (2,147,483,647)，此 API 返回 -1。

readonly cellCount: number;

属性值

number

注解

columnCount

指定区域中的列总数。

readonly columnCount: number;

属性值

number

注解

columnHidden

表示当前范围中的所有列是否处于隐藏状态。 true当一个区域中的所有列都隐藏时，值。 false当区域中没有列处于隐藏状态时，该值为。 null当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。

columnHidden: boolean;

属性值

boolean

注解

columnIndex

指定区域中第一个单元格的列号。从零开始编制索引。

readonly columnIndex: number;

属性值

number

注解

[ API 集：ExcelApi BETA (仅预览版) ]

conditionalFormats

与范围相交的的集合 ConditionalFormats 。

readonly conditionalFormats: Excel.ConditionalFormatCollection;

属性值

Excel.ConditionalFormatCollection

注解

[ API 集：ExcelApi 1.6 ]

context

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

context: RequestContext;

属性值

Excel.RequestContext

control

注意

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

访问应用于此区域的单元格控件。如果区域有多个单元格控件，则返回 EmptyCellControl。

control: CellControl;

属性值

Excel.CellControl

注解

dataValidation

返回数据有效性对象。

readonly dataValidation: Excel.DataValidation;

属性值

Excel.DataValidation

注解

[ API 集：ExcelApi 1.8 ]

format

返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。

readonly format: Excel.RangeFormat;

属性值

Excel.RangeFormat

注解

formulas

表示采用 A1 表示法的公式。如果单元格没有公式，则返回其值。

formulas: any[][];

属性值

any[][]

注解

formulasLocal

表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果单元格没有公式，则返回其值。

formulasLocal: any[][];

属性值

any[][]

注解

formulasR1C1

表示采用 R1C1 样式表示法的公式。如果单元格没有公式，则返回其值。

formulasR1C1: any[][];

属性值

any[][]

注解

hasSpill

表示所有单元格是否都具有溢出边框。 true如果所有单元格都有溢出边框，或者false所有单元格都没有溢出边框，则返回。 null如果区域中有和没有溢出边框的单元格，则返回。

readonly hasSpill: boolean;

属性值

boolean

注解

height

返回从范围上边缘到范围下边缘的 100% 缩放的距离（以磅为单位）。

readonly height: number;

属性值

number

注解

hidden

表示当前区域中的所有单元格是否处于隐藏状态。值是 true 隐藏区域中的所有单元格时。 false当区域中没有单元格被隐藏时，值。 null当某个区域中的某些单元格处于隐藏状态，而同一区域中的其他单元格未隐藏时，值表示。

readonly hidden: boolean;

属性值

boolean

注解

hyperlink

表示当前范围的超链接。

hyperlink: Excel.RangeHyperlink;

属性值

Excel.RangeHyperlink

注解

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Orders");

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

isEntireColumn

表示当前区域是否为整列。

readonly isEntireColumn: boolean;

属性值

boolean

注解

isEntireRow

表示当前区域是否为整行。

readonly isEntireRow: boolean;

属性值

boolean

注解

left

返回从工作表左边缘到区域左边缘的 100% 缩放的距离（以磅为单位）。

readonly left: number;

属性值

number

注解

linkedDataTypeState

表示每个单元格的数据类型状态。

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

属性值

Excel.LinkedDataTypeState[][]

注解

numberFormat

表示给定区域的 Excel 数字格式代码。有关 Excel 数字格式的详细信息，请参阅数字格式代码。

numberFormat: any[][];

属性值

any[][]

注解

示例

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

numberFormatCategories

表示每个单元格的数字格式的类别。

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

属性值

Excel.NumberFormatCategory[][]

注解

numberFormatLocal

表示基于用户语言设置的给定区域的 Excel 数字格式代码。获取或设置 numberFormatLocal 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。

numberFormatLocal: any[][];

属性值

any[][]

注解

rowCount

返回区域中的总行数。

readonly rowCount: number;

属性值

number

注解

rowHidden

表示当前范围中的所有行是否处于隐藏状态。值是 true 隐藏范围中的所有行时。 false当区域中没有隐藏行时，值。 null当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。

rowHidden: boolean;

属性值

boolean

注解

rowIndex

返回区域中第一个单元格的行编号。从零开始编制索引。

readonly rowIndex: number;

属性值

number

注解

savedAsArray

表示是否将所有单元格另存为数组公式。 true如果所有单元格都另存为数组公式，或者false所有单元格不另存为数组公式，则返回。 null如果某些单元格将保存为数组公式，而有些单元格则不保存，则返回。

readonly savedAsArray: boolean;

属性值

boolean

注解

sort

表示当前 range 的区域排序。

readonly sort: Excel.RangeSort;

属性值

Excel.RangeSort

注解

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

style

表示当前区域的样式。如果单元格的样式不一致， null 将返回。对于自定义样式，将返回样式名称。对于内置样式，将返回表示枚举中的 BuiltInStyle 值的字符串。

style: string;

属性值

string

注解

示例

// 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 worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    await context.sync();
});

text

指定区域的文本值。文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。

readonly text: string[][];

属性值

string[][]

注解

top

返回从工作表上边缘到区域上边缘的 100% 缩放的距离（以磅为单位）。

readonly top: number;

属性值

number

注解

values

表示指定区域的原始值。返回的数据可以是字符串、数字或布尔值。包含错误的单元格将返回错误字符串。如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。

values: any[][];

属性值

any[][]

注解

valuesAsJson

此区域中单元格中值的 JSON 表示形式。与不同 Range.values， Range.valuesAsJson 支持可在单元格中的所有数据类型。示例包括格式化的数字值和 Web 图像，以及标准布尔值、数字值和字符串值。从此 API 返回的数据始终与 en-US 区域设置一致。若要检索用户的显示区域设置中的数据，请使用 Range.valuesAsJsonLocal。

valuesAsJson: CellValue[][];

属性值

Excel.CellValue[][]

注解

[ API 集：ExcelApi 1.16 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a formatted number data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.formattedNumber,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});

valuesAsJsonLocal

此区域中单元格中值的 JSON 表示形式。与不同 Range.values， Range.valuesAsJsonLocal 支持可在单元格中的所有数据类型。示例包括格式化的数字值和 Web 图像，以及标准布尔值、数字值和字符串值。从此 API 返回的数据始终与用户的显示区域设置保持一致。若要检索独立于区域设置的数据，请使用 Range.valuesAsJson。

valuesAsJsonLocal: CellValue[][];

属性值

Excel.CellValue[][]

注解

[ API 集：ExcelApi 1.16 ]

valueTypes

指定每个单元格中的数据类型。

readonly valueTypes: Excel.RangeValueType[][];

属性值

Excel.RangeValueType[][]

注解

width

返回从范围的左边缘到范围右边缘的 100% 缩放的距离（以磅为单位）。

readonly width: number;

属性值

number

注解

worksheet

包含当前区域的工作表。

readonly worksheet: Excel.Worksheet;

属性值

Excel.Worksheet

注解

[ API set： ExcelApi 1.9， ExcelApi Preview for null destinationRange ]

方法详细信息

autoFill(destinationRange, autoFillType)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。目标范围可以是 null 或可以水平或垂直扩展源范围。不支持不连续的范围。

有关详细信息，请参阅使用自动填充和快速填充。

autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;

参数

destinationRange: Excel.Range | string

要自动填充的目标范围。如果目标区域为 null，则会根据周围的单元格填充数据 (这是双击 UI 的区域填充句柄) 时的行为。

autoFillType: Excel.AutoFillType

自动填充的类型。根据当前范围的内容指定如何填充目标范围。默认值为“FillDefault”。

void

注解

示例

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

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const sumCell = sheet.getRange("P4");
  
  // Copy everything. The formulas will be contextually updated based on their new locations.
  sumCell.autoFill("P4:P7", Excel.AutoFillType.fillCopy);
  sumCell.format.autofitColumns();
  await context.sync();
});

autoFill(destinationRange, autoFillTypeString)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。目标范围可以是 null 或可以水平或垂直扩展源范围。不支持不连续的范围。

有关详细信息，请参阅使用自动填充和快速填充。

autoFill(destinationRange?: Range | string, autoFillTypeString?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;

参数

destinationRange: Excel.Range | string

要自动填充的目标范围。如果目标区域为 null，则会根据周围的单元格填充数据 (这是双击 UI 的区域填充句柄) 时的行为。

autoFillTypeString: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"

自动填充的类型。根据当前范围的内容指定如何填充目标范围。默认值为“FillDefault”。

void

注解

[ API set： ExcelApi 1.9， ExcelApi Preview for null destinationRange ]

calculate()

计算工作表上的单元格区域。

calculate(): void;

void

注解

[ API 集：ExcelApi 1.6 ]

clear(applyTo)

清除范围值和格式设置，例如填充和边框。

clear(applyTo?: Excel.ClearApplyTo): void;

参数

applyTo: Excel.ClearApplyTo

可选。确定清除操作的类型。有关详细信息，请参阅 Excel.ClearApplyTo。

void

注解

示例

// Clear the format and contents of the range.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    await context.sync(); 
});

clear(applyToString)

清除范围值和格式设置，例如填充和边框。

clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void;

参数

applyToString: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"

可选。确定清除操作的类型。有关详细信息，请参阅 Excel.ClearApplyTo。

void

注解

[ API 集：ExcelApi BETA (仅预览版) ]

clearOrResetContents()

注意

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

清除区域中单元格的值，并特别考虑包含控件的单元格。如果区域仅包含空白值和设置为默认值的控件，则会删除值和控件格式。否则，这会将包含控件的单元格设置为默认值，并清除区域中其他单元格的值。

clearOrResetContents(): void;

void

注解

convertDataTypeToText()

将数据类型为文本的区域单元格。

convertDataTypeToText(): void;

void

注解

convertToLinkedDataType(serviceID, languageCulture)

在工作表中将区域单元格转换为链接数据类型。

convertToLinkedDataType(serviceID: number, languageCulture: string): void;

参数

serviceID: number

用于查询数据的服务 ID。

languageCulture: string

要查询服务的语言区域性。

void

注解

copyFrom(sourceRange, copyType, skipBlanks, transpose)

将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。目标范围的大小可以不同于源范围或 RangeAreas。如果目标小于源，则会自动扩展。注意：与 Excel UI 中的复制功能一样，如果目标范围正好大于行或列中源范围的倍数，则会多次复制源内容。例如，将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

参数

sourceRange: Excel.Range | Excel.RangeAreas | string

要从中复制的源范围或 RangeAreas 。当源 RangeAreas 具有多个区域时，必须能够通过从矩形区域中删除完整的行或列来创建其窗体。

copyType: Excel.RangeCopyType

要复制的单元格数据或格式的类型。默认值为“All”。

skipBlanks: boolean

如果跳过源区域中的空白单元格，则为 True。默认为 false。

transpose: boolean

如此如果转置目标区域中的单元格。默认为 false。

void

注解

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the copied data.
    sheet.getRange("F2").values = [["Copied Formula"]];

    // Copy a range preserving the formulas.
    // Note: non-formula values are copied over as is.
    sheet.getRange("G2").copyFrom("A1:E1", Excel.RangeCopyType.formulas);
    await context.sync();
});

copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)

copyFrom(sourceRange: Range | RangeAreas | string, copyTypeString?: "All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths", skipBlanks?: boolean, transpose?: boolean): void;

参数

sourceRange: Excel.Range | Excel.RangeAreas | string

要从中复制的源范围或 RangeAreas 。当源 RangeAreas 具有多个区域时，必须能够通过从矩形区域中删除完整的行或列来创建其窗体。

copyTypeString: "All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths"

要复制的单元格数据或格式的类型。默认值为“All”。

skipBlanks: boolean

如果跳过源区域中的空白单元格，则为 True。默认为 false。

transpose: boolean

如此如果转置目标区域中的单元格。默认为 false。

void

注解

delete(shift)

删除与区域相关的单元格。

delete(shift: Excel.DeleteShiftDirection): void;

参数

shift: Excel.DeleteShiftDirection

指定移动单元格的方式。有关详细信息，请参阅 Excel.DeleteShiftDirection。

void

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete("Left");
    await context.sync(); 
});

delete(shiftString)

删除与区域相关的单元格。

delete(shiftString: "Up" | "Left"): void;

参数

shiftString: "Up" | "Left"

指定移动单元格的方式。有关详细信息，请参阅 Excel.DeleteShiftDirection。

void

注解

find(text, criteria)

根据指定的条件查找给定的字符串。如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。

find(text: string, criteria: Excel.SearchCriteria): Excel.Range;

参数

text: string

要查找的字符串。

criteria: Excel.SearchCriteria

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

Excel.Range

表示 Range 包含与搜索文本和条件匹配的值的第一个单元格的对象。

注解

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();

    // NOTE: If no match is found, an ItemNotFound error
    // is thrown when Range.find is evaluated.
    const foundRange = searchRange.find($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();


    console.log(foundRange.address);
});

findOrNullObject(text, criteria)

根据指定的条件查找给定的字符串。如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。如果没有匹配项，则此方法返回对象的 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;

参数

text: string

要查找的字符串。

criteria: Excel.SearchCriteria

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

Excel.Range

Range与搜索条件匹配的。

注解

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();
    const foundRange = searchRange.findOrNullObject($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    if (foundRange.isNullObject) {
        console.log("Text not found");
    } else {
        console.log(foundRange.address);
    }
});

flashFill()

对当前范围执行快速填充。快速填充在感知模式时自动填充数据，因此范围必须是单个列范围，并且周围有数据才能找到模式。

flashFill(): void;

void

注解

getAbsoluteResizedRange(numRows, numColumns)

获取一个 Range 对象，该对象具有与当前 Range 对象相同的左上角单元格，但具有指定的行数和列数。

getAbsoluteResizedRange(numRows: number, numColumns: number): Excel.Range;

参数

numRows: number

新范围大小的行数。

numColumns: number

新范围大小的列数。

Excel.Range

注解

getBoundingRect(anotherRange)

获取包含指定区域的最小 range 对象。例如， GetBoundingRect “B2：C5”和“D10：E15”的为“B2：E15”。

getBoundingRect(anotherRange: Range | string): Excel.Range;

参数

anotherRange: Excel.Range | string

范围对象、地址或范围名称。

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:G6";
    let range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range = range.getBoundingRect("G4:H8");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // Prints Sheet1!D4:H8
});

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 range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

getCellProperties(cellPropertiesLoadOptions)

返回一个 2D 数组，其中封装了每个单元格的字体、填充、边框、对齐方式和其他属性数据。

getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

参数

cellPropertiesLoadOptions: Excel.CellPropertiesLoadOptions

一个对象，表示要加载的单元格属性。

OfficeExtension.ClientResult<Excel.CellProperties[][]>

一个 2D 数组，其中每个项表示相应单元格的请求属性。

注解

示例

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

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

    // Define the cell properties to get by setting the matching LoadOptions to true.
    const propertiesToGet = cell.getCellProperties({
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                color: true
            }
        },
        style: true
    });

    // Sync to get the data from the workbook.
    await context.sync();
    const cellProperties = propertiesToGet.value[0][0];
    console.log(
        `Address: ${cellProperties.address}\nStyle: ${cellProperties.style}\nFill Color: ${cellProperties.format.fill.color}\nFont Color: ${cellProperties.format.font.color}`);
});

getColumn(column)

获取范围中包含的列。

getColumn(column: number): Excel.Range;

参数

column: number

要检索的区域的列号。从零开始编制索引。

Excel.Range

注解

OfficeExtension.ClientResult<Excel.ColumnProperties[]>

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet19";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    await context.sync();

    console.log(range.address); // prints Sheet1!B1:B8
});

getColumnProperties(columnPropertiesLoadOptions)

返回一个一维数组，其中封装了每个列的字体、填充、边框、对齐方式和其他属性数据。对于给定列中每个单元格不一致的属性，将返回 null。

getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;

参数

columnPropertiesLoadOptions: Excel.ColumnPropertiesLoadOptions

一个对象，表示要加载的列属性。

一个数组，其中每个项表示相应列的请求属性。

注解

getColumnsAfter(count)

获取当前 Range 对象右侧的一定数量的列。

getColumnsAfter(count?: number): Excel.Range;

参数

count: number

可选。生成的范围中要包含的列数。一般来说，使用正数可以在当前范围之外创建一个范围。也可以使用负数在当前范围之内创建一个范围。默认值为 1。

Excel.Range

注解

getColumnsBefore(count)

获取当前 Range 对象左侧的一定数量的列。

getColumnsBefore(count?: number): Excel.Range;

参数

count: number

Excel.Range

注解

getDependents()

返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或多个工作表中指定区域的所有依赖单元格的区域。注意：如果未找到依赖项，此 API 将返回错误 ItemNotFound 。

getDependents(): Excel.WorkbookRangeAreas;

Excel.WorkbookRangeAreas

注解

[ API 集：ExcelApi 1.15 ]

示例

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

// This function highlights all the dependent cells of the active cell.
// Dependent cells contain formulas that refer to other cells.
await Excel.run(async (context) => {
  // Get addresses of the active cell's dependent cells.
  const range = context.workbook.getActiveCell();
  const dependents = range.getDependents();
  range.load("address");
  dependents.areas.load("address");
  await context.sync();

  console.log(`All dependent cells of ${range.address}:`);

  // Use the dependents API to loop through dependents of the active cell.
  for (let i = 0; i < dependents.areas.items.length; i++) {
    // Highlight and print out the address of each dependent cell.
    dependents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${dependents.areas.items[i].address}`);
  }
  await context.sync();
});

getDirectDependents()

返回一个对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有直接依赖单元格的区域。注意：如果未找到依赖项，此 API 将返回错误 ItemNotFound 。

getDirectDependents(): Excel.WorkbookRangeAreas;

Excel.WorkbookRangeAreas

注解

示例

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

await Excel.run(async (context) => {
  // Direct dependents are cells that contain formulas that refer to other cells.
  let range = context.workbook.getActiveCell();
  let directDependents = range.getDirectDependents();
  range.load("address");
  directDependents.areas.load("address");
  await context.sync();
  
  console.log(`Direct dependent cells of ${range.address}:`);
  
  // Use the direct dependents API to loop through direct dependents of the active cell.
  for (let i = 0; i < directDependents.areas.items.length; i++) {
    // Highlight and print the address of each dependent cell.
    directDependents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directDependents.areas.items[i].address}`);
  }
  await context.sync();
});

getDirectPrecedents()

返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。注意：如果未找到任何先例，此 API 将返回错误 ItemNotFound 。

getDirectPrecedents(): Excel.WorkbookRangeAreas;

Excel.WorkbookRangeAreas

注解

示例

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

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  // A "direct precedent" is a cell directly referenced by the selected formula.
  let range = context.workbook.getActiveCell();
  let directPrecedents = range.getDirectPrecedents();
  range.load("address");
  directPrecedents.areas.load("address");
  await context.sync();

  console.log(`Direct precedent cells of ${range.address}:`);

  // Use the direct precedents API to loop through precedents of the active cell.
  for (let i = 0; i < directPrecedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    directPrecedents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directPrecedents.areas.items[i].address}`);
  }
  await context.sync();
});

getEntireColumn()

获取一个对象，该对象表示区域 (的整个列，例如，如果当前区域表示单元格“B4：E11”，则它是 getEntireColumn 表示列“B：E”) 的区域。

getEntireColumn(): Excel.Range;

Excel.Range

注解

示例

// Note: the grid properties of the Range (values, numberFormat, formulas) 
// contains null since the Range in question is unbounded.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    await context.sync();
    
    console.log(rangeEC.address);
});

getEntireRow()

获取一个对象，该对象表示区域 (的整行，例如，如果当前区域表示单元格“B4：E11”，则它是 GetEntireRow 表示行“4：11”) 的区域。

getEntireRow(): Excel.Range;

Excel.Range

注解

示例

// Gets an object that represents the entire row of the range 
// (for example, if the current range represents cells "B4:E11", 
// its GetEntireRow is a range that represents rows "4:11").
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "D:F"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeER = range.getEntireRow();
    rangeER.load('address');
    await context.sync();
    
    console.log(rangeER.address);
});

getExtendedRange(direction, activeCell)

返回一个 range 对象，该对象包括当前范围以及范围边缘，具体取决于提供的方向。这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

getExtendedRange(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

参数

direction: Excel.KeyboardDirection

活动单元格的方向。

activeCell: Excel.Range | string

此区域中的活动单元格。默认情况下，活动单元格是区域的左上角单元格。如果活动单元格不在此范围内，则会引发错误。

Excel.Range

注解

示例

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

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.down;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get all the cells from the currently selected range to the bottom-most edge of the used range.
  // This method acts like the Ctrl+Shift+Arrow key keyboard shortcut while a range is selected.
  const extendedRange = range.getExtendedRange(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  extendedRange.select();

  await context.sync();
});

getExtendedRange(directionString, activeCell)

返回一个 range 对象，该对象包括当前范围以及范围边缘，具体取决于提供的方向。这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

getExtendedRange(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

参数

directionString: "Left" | "Right" | "Up" | "Down"

活动单元格的方向。

activeCell: Excel.Range | string

此区域中的活动单元格。默认情况下，活动单元格是区域的左上角单元格。如果活动单元格不在此范围内，则会引发错误。

Excel.Range

注解

getImage()

将范围呈现为 Base64 编码的 png 图像。 重要说明*：Excel for Mac目前不支持此 API。有关当前状态，请访问 OfficeDev/office-js 问题 #235 。

getImage(): OfficeExtension.ClientResult<string>;

OfficeExtension.ClientResult<string>

注解

getIntersection(anotherRange)

获取表示指定区域的矩形交集的 range 对象。

getIntersection(anotherRange: Range | string): Excel.Range;

参数

anotherRange: Excel.Range | string

将用于确定区域交集的 range 对象或区域地址。

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!D4:F6
});

getIntersectionOrNullObject(anotherRange)

获取表示指定区域的矩形交集的 range 对象。如果未找到交集，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getIntersectionOrNullObject(anotherRange: Range | string): Excel.Range;

参数

anotherRange: Excel.Range | string

将用于确定区域交集的 range 对象或区域地址。

Excel.Range

注解

[ API 集：ExcelApi 1.4 ]

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

getLastCell()

获取区域内的最后一个单元格。例如，“B2:D5”的最后一个单元格是“D5”。

getLastCell(): Excel.Range;

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F8
});

getLastColumn()

获取区域内的最后一列。例如，“B2:D5”的最后一列是“D2:D5”。

getLastColumn(): Excel.Range;

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F1:F8
});

getLastRow()

获取区域内的最后一行。例如，“B2:D5”的最后一行是“B5:D5”。

getLastRow(): Excel.Range;

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A8:F8
});

getMergedAreasOrNullObject()

返回一个 RangeAreas 对象，该对象代表此区域中的合并区域。请注意，如果此范围内的合并区域计数超过 512，则此方法将无法返回结果。 RangeAreas如果该对象不存在，则此函数将返回一个对象，其isNullObject属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getMergedAreasOrNullObject(): Excel.RangeAreas;

Excel.RangeAreas

注解

示例

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

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Retrieve the merged range within the table and load its details.
  const mergedAreas = tableRange.getMergedAreasOrNullObject();
  mergedAreas.load("address");
  mergedAreas.load("cellCount");

  // Select the merged range.
  const range = mergedAreas.areas.getItemAt(0);
  range.select();
  await context.sync();

  // Print out the details of the `mergedAreas` range object.
  console.log(`Address of the merged range: ${mergedAreas.address}`);
  console.log(`Number of cells in the merged range: ${mergedAreas.cellCount}`);

  await context.sync();
});

getOffsetRange(rowOffset, columnOffset)

获取表示与指定区域偏移的区域的对象。返回的区域的尺寸将与此区域一致。如果强制在工作表网格的边界之外生成区域，将引发错误。

getOffsetRange(rowOffset: number, columnOffset: number): Excel.Range;

参数

rowOffset: number

区域偏移的行数（正数、负数或 0）。正值表示向下偏移，负值表示向上偏移。

columnOffset: number

区域偏移的列数（正数、负数或 0）。正值表示向右偏移，负值表示向左偏移。

Excel.Range

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:F6";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!H3:J5
});

getPivotTables(fullyContained)

获取与区域重叠的数据透视表的作用域集合。

getPivotTables(fullyContained?: boolean): Excel.PivotTableScopedCollection;

参数

fullyContained: boolean

如果 true为，则仅返回完全包含在范围边界中的数据透视表。默认值 false为。

Excel.PivotTableScopedCollection

注解

示例

// 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) => {
  const activeRange = context.workbook.getSelectedRange();

  // Get all the PivotTables that intersect with this range.
  const partiallyContainedPivotTables = activeRange.getPivotTables();
  // Get all the PivotTables that are completely contained within this range.
  const fullyContainedPivotTables = activeRange.getPivotTables(true);

  partiallyContainedPivotTables.load("name");
  fullyContainedPivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current range:")
  partiallyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
  console.log("PivotTables completely contained in the current range:")
  fullyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

getPrecedents()

返回一个对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有前置单元格的区域。注意：如果未找到任何先例，此 API 将返回错误 ItemNotFound 。

getPrecedents(): Excel.WorkbookRangeAreas;

Excel.WorkbookRangeAreas

注解

[ API 集：ExcelApi 1.14 ]

示例

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

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  let range = context.workbook.getActiveCell();
  let precedents = range.getPrecedents();
  range.load("address");
  precedents.areas.load("address");
  await context.sync();

  console.log(`All precedent cells of ${range.address}:`);

  // Use the precedents API to loop through precedents of the active cell.
  for (let i = 0; i < precedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    precedents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${precedents.areas.items[i].address}`);
  }
  await context.sync();
});

getRangeEdge(direction, activeCell)

返回一个 range 对象，该对象是与提供的方向对应的数据区域边缘单元格。这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

getRangeEdge(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

参数

direction: Excel.KeyboardDirection

活动单元格的方向。

activeCell: Excel.Range | string

此区域中的活动单元格。默认情况下，活动单元格是区域的左上角单元格。如果活动单元格不在此范围内，则会引发错误。

Excel.Range

注解

示例

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

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.up;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get the top-most cell of the current used range.
  // This method acts like the Ctrl+Arrow key keyboard shortcut while a range is selected.
  const rangeEdge = range.getRangeEdge(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  rangeEdge.select();

  await context.sync();
});

getRangeEdge(directionString, activeCell)

返回一个 range 对象，该对象是与提供的方向对应的数据区域边缘单元格。这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

getRangeEdge(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

参数

directionString: "Left" | "Right" | "Up" | "Down"

活动单元格的方向。

activeCell: Excel.Range | string

此区域中的活动单元格。默认情况下，活动单元格是区域的左上角单元格。如果活动单元格不在此范围内，则会引发错误。

Excel.Range

注解

getResizedRange(deltaRows, deltaColumns)

获取与 Range 当前 Range 对象类似的对象，但其右下角展开 (或按行和列数收缩) 。

getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;

参数

deltaRows: number

相对于当前范围，展开右下角的行数。使用正数可展开范围，使用负数可合拢范围。

deltaColumns: number

相对于当前范围展开右下角的列数。使用正数可展开范围，使用负数可合拢范围。

Excel.Range

注解

getRow(row)

获取范围中包含的行。

getRow(row: number): Excel.Range;

参数

row: number

要检索的区域的行号。从零开始编制索引。

Excel.Range

注解

OfficeExtension.ClientResult<Excel.RowProperties[]>

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A2:F2
});

getRowProperties(rowPropertiesLoadOptions)

返回一个一维数组，其中封装了每个行的字体、填充、边框、对齐方式和其他属性数据。对于在给定行内每个单元格中不一致的属性， null 将返回。

getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;

参数

rowPropertiesLoadOptions: Excel.RowPropertiesLoadOptions

一个对象，表示要加载的行属性。

一个数组，其中每个项表示相应行的请求属性。

注解

getRowsAbove(count)

获取当前 Range 对象上方的一定行数。

getRowsAbove(count?: number): Excel.Range;

参数

count: number

可选。生成的范围中要包含的行数。一般来说，使用正数可以在当前范围之外创建一个范围。也可以使用负数在当前范围之内创建一个范围。默认值为 1。

Excel.Range

注解

getRowsBelow(count)

获取当前 Range 对象下面的特定行数。

getRowsBelow(count?: number): Excel.Range;

参数

count: number

Excel.Range

注解

getSpecialCells(cellType, cellValueType)

RangeAreas获取对象，该对象包含一个或多个矩形区域，该对象表示与指定类型和值匹配的所有单元格。如果未找到任何特殊单元格， ItemNotFound 则会引发错误。

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

参数

cellType: Excel.SpecialCellType

要包含的单元格类型。

cellValueType: Excel.SpecialCellValueType

如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。这些值可以组合在一起以返回多个类型。默认情况下，将选择所有常量或公式，无论类型如何。

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 usedRange = sheet.getUsedRange();

    // Find the ranges with either text or logical (boolean) values.
    const formulaRanges = usedRange.getSpecialCells("Constants", "LogicalText");
    formulaRanges.format.fill.color = "orange";

    return context.sync();
});

getSpecialCells(cellTypeString, cellValueTypeString)

getSpecialCells(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

参数

cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"

要包含的单元格类型。

cellValueTypeString: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"

Excel.RangeAreas

注解

getSpecialCellsOrNullObject(cellType, cellValueType)

RangeAreas获取由一个或多个区域组成的对象，该对象表示与指定类型和值匹配的所有单元格。如果未找到任何特殊单元格，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

参数

cellType: Excel.SpecialCellType

要包含的单元格类型。

cellValueType: Excel.SpecialCellValueType

Excel.RangeAreas

注解

getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)

getSpecialCellsOrNullObject(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

参数

cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"

要包含的单元格类型。

cellValueTypeString: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"

Excel.RangeAreas

注解

getSpillingToRange()

获取 Range 对象，它在调用定位单元格时包含溢出区域。如果应用于具有多个单元格的区域，则会失败。

getSpillingToRange(): Excel.Range;

Excel.Range

注解

示例

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

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sample");

  // Set G4 to a formula that returns a dynamic array.
  const targetCell = sheet.getRange("G4");
  targetCell.formulas = [["=A4:D4"]];

  // Get the address of the cells that the dynamic array spilled into.
  const spillRange = targetCell.getSpillingToRange();
  spillRange.load("address");

  // Fit the columns for readability.
  sheet.getUsedRange().format.autofitColumns();
  await context.sync();

  console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});

getSpillingToRangeOrNullObject()

获取 Range 对象，它在调用定位单元格时包含溢出区域。如果区域不是定位点单元格或找不到溢出区域，则此方法返回对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getSpillingToRangeOrNullObject(): Excel.Range;

Excel.Range

注解

getSpillParent()

获取 Range 对象，它包含要将某个单元格溢出到的定位单元格。如果应用于具有多个单元格的区域，则会失败。

getSpillParent(): Excel.Range;

Excel.Range

注解

getSpillParentOrNullObject()

获取包含要溢出到的单元格的定位单元格的范围对象。如果它不是溢出的单元格，或者提供了多个单元格，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

getSpillParentOrNullObject(): Excel.Range;

Excel.Range

注解

getSurroundingRegion()

返回一个 Range 对象，该对象代表此区域中左上角单元格的周围区域。周围区域是由相对于该区域的空白行和空白列的任何组合所限定的区域。

getSurroundingRegion(): Excel.Range;

Excel.Range

注解

getTables(fullyContained)

获取与区域重叠的限定范围的表格集合。

getTables(fullyContained?: boolean): Excel.TableScopedCollection;

参数

fullyContained: boolean

如果 true为，则仅返回完全包含在范围边界内的表。默认值 false为。

Excel.TableScopedCollection

注解

getUsedRange(valuesOnly)

返回指定 range 对象的所用区域。如果区域中没有使用的单元格，则此函数将引发错误 ItemNotFound 。

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

参数

valuesOnly: boolean

仅将有值的单元格视为已使用的单元格。 [Api 集：ExcelApi 1.2]

Excel.Range

注解

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

getUsedRangeOrNullObject(valuesOnly)

返回指定 range 对象的所用区域。如果区域中没有已用单元格，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

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

参数

valuesOnly: boolean

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

Excel.Range

注解

[ API 集：ExcelApi 1.4 ]

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // Pass true so only cells with values count as used
    const usedDataRange = dataRange.getUsedRangeOrNullObject(
        true /* valuesOnly */
    );

    //Must sync before reading value returned from *OrNullObject method/property.
    await context.sync();

    if (usedDataRange.isNullObject) {
        console.log("Need Data to Make Chart");
        console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
    } else {
        const chart = sheet.charts.add(
            Excel.ChartType.columnClustered,
            dataRange,
            "Columns"
        );
        chart.setPosition("A15", "F30");
        chart.title.text = "Quarterly sales chart";
        chart.legend.position = "Right";
        chart.legend.format.fill.setSolidColor("white");
        chart.dataLabels.format.font.size = 15;
        chart.dataLabels.format.font.color = "black";
    }

    await context.sync();
});

getVisibleView()

表示当前 range 对象的可见行。

getVisibleView(): Excel.RangeView;

Excel.RangeView

注解

[ API 集：ExcelApi 1.3 ]

group(groupOption)

组大纲的列和行。

group(groupOption: Excel.GroupOption): void;

参数

groupOption: Excel.GroupOption

指定如何按行或列对区域进行分组。 InvalidArgument当组选项不同于范围isEntireRow或isEntireColumn属性 (即range.isEntireRow为 true 且groupOption为“ByColumns”或range.isEntireColumn为 true 且groupOption为“ByRows”) 时，将引发错误。

void

注解

示例

// 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();
    
    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);
    await context.sync();
});

group(groupOptionString)

组大纲的列和行。

group(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString: "ByRows" | "ByColumns"

void

注解

hideGroupDetails(groupOption)

隐藏行或列组的详细信息。

hideGroupDetails(groupOption: Excel.GroupOption): void;

参数

groupOption: Excel.GroupOption

指定是隐藏分组行的详细信息还是分组列的详细信息。

void

注解

hideGroupDetails(groupOptionString)

隐藏行或列组的详细信息。

hideGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString: "ByRows" | "ByColumns"

指定是隐藏分组行的详细信息还是分组列的详细信息。

void

注解

insert(shift)

将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 Range 对象。

insert(shift: Excel.InsertShiftDirection): Excel.Range;

参数

shift: Excel.InsertShiftDirection

指定移动单元格的方式。有关详细信息，请参阅 Excel.InsertShiftDirection。

Excel.Range

注解

示例

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert(Excel.InsertShiftDirection.down);
    await context.sync();
});

insert(shiftString)

将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 Range 对象。

insert(shiftString: "Down" | "Right"): Excel.Range;

参数

shiftString: "Down" | "Right"

指定移动单元格的方式。有关详细信息，请参阅 Excel.InsertShiftDirection。

Excel.Range

注解

load(options)

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

load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;

参数

options: Excel.Interfaces.RangeLoadOptions

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

Excel.Range

load(propertyNames)

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

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

参数

propertyNames: string | string[]

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

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

load(propertyNamesAndPaths)

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

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

参数

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

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

Excel.Range

merge(across)

将范围单元格合并到工作表的一个区域内。

merge(across?: boolean): void;

参数

across: boolean

可选。设置为 true 将指定区域的每一行中的单元格合并为单独的合并单元格。默认值 false为。

void

注解

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.merge(true);
    await context.sync(); 
});

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

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Create a merged range in the first row of the table.
  const chartTitle = tableRange.getRow(0);
  chartTitle.merge(true);

  // Format the merged range.
  chartTitle.format.horizontalAlignment = "Center";

  await context.sync();
});

moveTo(destinationRange)

将单元格值、格式和公式从当前区域移动到目标区域，替换这些单元格中的旧信息。如果目标范围小于当前范围，则会自动扩展。不会更改目标区域中超出原始区域区域的任何单元格。

moveTo(destinationRange: Range | string): void;

参数

destinationRange: Excel.Range | string

destinationRange 指定将移动此区域中的信息的区域。

void

注解

[ API 集：ExcelApi 1.11 ]

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the moved data.
    sheet.getRange("F12").values = [["Moved Range:"]];

    // Move the range from A1:E1 to G12:K12.
    sheet.getRange("A1:E1").moveTo("G12");
    await context.sync();
});

removeDuplicates(columns, includesHeader)

从列指定的区域中删除重复值。

removeDuplicates(columns: number[], includesHeader: boolean): Excel.RemoveDuplicatesResult;

参数

columns: number[]

范围内可能包含重复项的列。至少需要指定一列。从零开始编制索引。

includesHeader: boolean

如果输入数据包含标头，则为 True。默认为 false。

Excel.RemoveDuplicatesResult

生成的对象，该对象包含删除的行数和剩余唯一行数。

注解

示例

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

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:D11");

    const deleteResult = range.removeDuplicates([0],true);    
    deleteResult.load();    
    await context.sync();

    console.log(deleteResult.removed + " entries with duplicate names removed.");
    console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
});

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>

执行的替换次数。

注解

select()

在 Excel UI 中选择指定的区域。

select(): void;

void

注解

示例

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    await context.sync(); 
});

set(properties, options)

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

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

参数

properties: Excel.Interfaces.RangeUpdateData

一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。

options: OfficeExtension.UpdateOptions

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

void

set(properties)

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

set(properties: Excel.Range): void;

参数

properties: Excel.Range

void

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/multiple-property-set.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    const sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");
    await context.sync();

    // Set properties based on the loaded and synced 
    // source range.
    const targetRange = sheet.getRange("B7:E7");
    targetRange.set(sourceRange); 
    targetRange.format.autofitColumns();
    await context.sync();
});

setCellProperties(cellPropertiesData)

基于单元格属性的 2D 数组汇报区域，封装字体、填充、边框和对齐等内容。

setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;

参数

cellPropertiesData: Excel.SettableCellProperties[][]

表示在每个单元格中设置的属性的 2D 数组。

void

注解

示例

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

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

    // Creating the SettableCellProperties objects to use for the range.
    // In your add-in, these should be created once, outside the function.
    const topHeaderProps: Excel.SettableCellProperties = {
        // The style property takes a string matching the name of an Excel style.
        // Built-in style names are listed in the `BuiltInStyle` enum.
        // Note that a style will overwrite any formatting,
        // so do not use the format property with the style property.
        style: "Heading1"
    };

    const headerProps: Excel.SettableCellProperties = {
        // Any subproperties of format that are not set will not be changed when these cell properties are set.
        format: {
            fill: {
                color: "Blue"
            },
            font: {
                color: "White",
                bold: true
            }
        }
    };

    const nonApplicableProps: Excel.SettableCellProperties = {
        format: {
            fill: {
                pattern: Excel.FillPattern.gray25
            },
            font: {
                color: "Gray",
                italic: true
            }
        }
    };

    const matchupScoreProps: Excel.SettableCellProperties = {
        format: {
            borders: {
                bottom: {
                    style: Excel.BorderLineStyle.continuous
                },
                left: {
                    style: Excel.BorderLineStyle.continuous
                },
                right: {
                    style: Excel.BorderLineStyle.continuous
                },
                top: {
                    style: Excel.BorderLineStyle.continuous
                }
            }
        }
    };

    const range = sheet.getRange("A1:E5");

    // You can use empty JSON objects to avoid changing a cell's properties.
    range.setCellProperties([
        [topHeaderProps, {}, {}, {}, {}],
        [{}, {}, headerProps, headerProps, headerProps],
        [{}, headerProps, nonApplicableProps, matchupScoreProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, nonApplicableProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, matchupScoreProps, nonApplicableProps]
    ]);

    sheet.getUsedRange().format.autofitColumns();
    await context.sync();
});

setColumnProperties(columnPropertiesData)

基于列属性的单维数组汇报范围，并封装字体、填充、边框和对齐方式等内容。

setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;

参数

columnPropertiesData: Excel.SettableColumnProperties[]

一个数组，表示要在每个列中设置的属性。

void

注解

setDirty()

设置下一次重新计算发生时要重新计算的区域。

setDirty(): void;

void

注解

setRowProperties(rowPropertiesData)

基于行属性的一维数组汇报区域，并封装字体、填充、边框和对齐方式等内容。

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

参数

rowPropertiesData: Excel.SettableRowProperties[]

一个数组，表示每行中要设置的属性。

void

注解

showCard()

显示活动单元格的卡片（如果该单元格具有富值内容）。

showCard(): void;

void

注解

showGroupDetails(groupOption)

显示行或列组的详细信息。

showGroupDetails(groupOption: Excel.GroupOption): void;

参数

groupOption: Excel.GroupOption

指定是显示分组行的详细信息还是分组列的详细信息。

void

注解

showGroupDetails(groupOptionString)

显示行或列组的详细信息。

showGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString: "ByRows" | "ByColumns"

指定是显示分组行的详细信息还是分组列的详细信息。

void

注解

toJSON()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来又调用toJSON传递给它的对象的方法。) 而原始Excel.Range对象是 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.RangeData) ，其中包含原始对象中任何已加载子属性的浅表副本。

toJSON(): Excel.Interfaces.RangeData;

Excel.Interfaces.RangeData

track()

根据文档中的相应更改来跟踪对象，以便进行自动调整。此调用是 context.trackedObjects.add (thisObject) 的简写。如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。

track(): Excel.Range;

Excel.Range

ungroup(groupOption)

取消对大纲的列和行的分组。

ungroup(groupOption: Excel.GroupOption): void;

参数

groupOption: Excel.GroupOption

指定如何按行或列取消组合区域。

void

注解

示例

// 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 removes two levels of groups from the "A1-R10" range.
    // Any groups at the same level on the same dimension will be removed by a single call.
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    await context.sync();
});

ungroup(groupOptionString)

取消对大纲的列和行的分组。

ungroup(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString: "ByRows" | "ByColumns"

指定如何按行或列取消组合区域。

void

注解

unmerge()

将范围单元格取消合并为各个单元格。

unmerge(): void;

void

注解