使用 Excel JavaScript API 设置和获取所选区域

本文提供了使用 Excel JavaScript API 设置和获取所选范围的代码示例。 有关对象支持的属性和方法 Range 的完整列表，请参阅 Excel.Range 类。

设置所选区域

下面的代码示例选择活动工作表中的区域 B2:E6。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let range = sheet.getRange("B2:E6");

    range.select();

    await context.sync();
});

选定的区域 B2:E6

获取所选区域

下面的代码示例获取所选区域，加载其 address 属性，并将消息写入控制台。

await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    range.load("address");

    await context.sync();
    
    console.log(`The address of the selected range is "${range.address}"`);
});

选择已用范围的边缘

Range.getRangeEdge 和 Range.getExtendedRange 方法可让你的外接程序复制键盘选择快捷方式的行为，基于当前所选区域选择已用范围的边缘。 若要详细了解已用范围，请参阅 获取使用范围。

在以下屏幕截图中，使用的范围为每个单元格中具有值的表 C5：F12。 此表外的空单元格超出了使用的范围。

选择当前使用区域边缘的单元格

下面的代码示例演示如何使用 Range.getRangeEdge 方法在当前使用的范围的最远边缘选择向上方向的单元格。 此操作与选择范围时使用 Ctrl+向上键键盘快捷方式的结果匹配。

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

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

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

    // Get the top-most cell of the current used range.
    // This method acts like the Ctrl+Up arrow key keyboard shortcut while a range is selected.
    let rangeEdge = range.getRangeEdge(
      direction,
      activeCell
    );
    rangeEdge.select();

    await context.sync();
});

在选择所用区域边缘的单元格之前

以下屏幕截图显示了已用范围和已用范围内的选定范围。 所用范围是数据位于 C5：F12 的表。 在此表中，已选择 范围 D8：E9 。 此 选择是在运行Range.getRangeEdge 方法之前的状态。

选择所用区域边缘的单元格后

以下屏幕截图显示了与上一张屏幕截图相同的表，其数据在 C5：F12 范围内。 在此表中，已选择范围 D5 。 此 选择是在运行Range.getRangeEdge 方法以在已用区域边缘的向上方向选择单元格之后的状态之后。

选择当前区域到已用区域最远边缘的所有单元格

下面的代码示例演示如何使用 Range.getExtendedRange 方法从当前所选区域到已用区域最远边缘（向下方向）选择所有单元格。 此操作与选择区域时使用 Ctrl+Shift+向下键键盘快捷方式的结果匹配。

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

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

    // Get the active cell in the workbook.
    let 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+Down arrow key keyboard shortcut while a range is selected.
    let extendedRange = range.getExtendedRange(
      direction,
      activeCell
    );
    extendedRange.select();

    await context.sync();
});

在选择当前区域到所用区域边缘的所有单元格之前

以下屏幕截图显示了已用范围和已用范围内的选定范围。 所用范围是数据位于 C5：F12 的表。 在此表中，已选择 范围 D8：E9 。 此 选择是在运行Range.getExtendedRange 方法之前的状态。

选择当前区域到所用区域边缘的所有单元格后

以下屏幕截图显示了与上一张屏幕截图相同的表，其数据在 C5：F12 范围内。 在此表中，已选择 范围 D8：E12 。 此 选择是在运行Range.getExtendedRange 方法以从当前区域到已用区域边缘沿向下方向选择所有单元格之后的状态之后。

另请参阅

• Excel 加载项中的 Word JavaScript 对象模型
• 使用 Excel JavaScript API 处理单元格
• 使用 Excel JavaScript API 设置和获取范围值、文本或公式
• 使用 Excel JavaScript API 设置范围格式