link之家
链接快照平台
- 输入网页链接，自动生成快照
- 标签化管理网页链接
相关文章推荐
|
留胡子的电影票 · org.springframework.jd ...· 2 年前 · |
|
|
爱喝酒的墨镜 · vss事件13错误频发 - ...· 2 年前 · |
|
|
没人理的豆芽 · Mockito ...· 2 年前 · |
|
|
完美的硬盘 · Angular：ERROR in ...· 2 年前 · |
link之家
›
Excel.Range class - Office Add-ins | Microsoft Learn
| async string 单元格 单元格引用 |
| https://learn.microsoft.com/zh-cn/javascript/api/excel/excel.range?view=excel-js-preview |
|
慷慨的圣诞树
3 月前 |
// Get a Range object by its address.
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);
true当一个区域中的所有列都隐藏时，值。
false当区域中没有列处于隐藏状态时，该值为 。
null当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。
column指定区域中第一个单元格的列号。 从零开始编制索引。
conditional与范围相交的 的 集合 ConditionalFormats 。
context
与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。
control
访问应用于此区域的单元格控件。 如果区域有多个单元格控件，则返回 EmptyCellControl。
data返回数据有效性对象。
format
返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。
formulas
表示采用 A1 表示法的公式。 如果单元格没有公式，则返回其值。
formulas表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。 例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。 如果单元格没有公式，则返回其值。
formulasR1C1
表示采用 R1C1 样式表示法的公式。 如果单元格没有公式，则返回其值。
has表示所有单元格是否都具有溢出边框。
true如果所有单元格都有溢出边框，或者false所有单元格都没有溢出边框，则返回 。
null如果区域中有和没有溢出边框的单元格，则返回 。
height
返回从范围上边缘到范围下边缘的 100% 缩放的距离（以磅为单位）。
hidden
表示当前区域中的所有单元格是否处于隐藏状态。 值是 true 隐藏区域中的所有单元格时。
false当区域中没有单元格被隐藏时，值。
null当某个区域中的某些单元格处于隐藏状态，而同一区域中的其他单元格未隐藏时，值表示。
hyperlink
表示当前范围的超链接。
is表示当前区域是否为整列。
is表示当前区域是否为整行。
返回从工作表左边缘到区域左边缘的 100% 缩放的距离（以磅为单位）。
linked表示每个单元格的数据类型状态。
number表示给定区域的 Excel 数字格式代码。 有关 Excel 数字格式的详细信息，请参阅 数字格式代码。
number表示每个单元格的数字格式的类别。
number表示基于用户语言设置的给定区域的 Excel 数字格式代码。 获取或设置 numberFormatLocal 属性时，Excel 不执行任何语言或格式强制。 任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。
row返回区域中的总行数。
row表示当前范围中的所有行是否处于隐藏状态。 值是 true 隐藏范围中的所有行时。
false当区域中没有隐藏行时，值。
null当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。
row返回区域中第一个单元格的行编号。 从零开始编制索引。
saved表示是否将所有单元格另存为数组公式。
true如果所有单元格都另存为数组公式，或者false所有单元格不另存为数组公式，则返回 。
null如果某些单元格将保存为数组公式，而有些单元格则不保存，则返回 。
表示当前 range 的区域排序。
style
表示当前区域的样式。 如果单元格的样式不一致， null 将返回 。 对于自定义样式，将返回样式名称。 对于内置样式，将返回表示枚举中的 BuiltInStyle 值的字符串。
指定区域的文本值。 文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。
返回从工作表上边缘到区域上边缘的 100% 缩放的距离（以磅为单位）。
values
表示指定区域的原始值。 返回的数据可以是字符串、数字或布尔值。 包含错误的单元格将返回错误字符串。 如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。
values此区域中单元格中值的 JSON 表示形式。 与 不同 Range.values， Range.valuesAsJson 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像，以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与 en-US 区域设置一致。 若要检索用户的显示区域设置中的数据，请使用 Range.valuesAsJsonLocal。
values此区域中单元格中值的 JSON 表示形式。 与 不同 Range.values， Range.valuesAsJsonLocal 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像，以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与用户的显示区域设置保持一致。 若要检索独立于区域设置的数据，请使用 Range.valuesAsJson。
value指定每个单元格中的数据类型。
width
返回从范围的左边缘到范围右边缘的 100% 缩放的距离（以磅为单位）。
worksheet
包含当前区域的工作表。
auto使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。
有关详细信息，请参阅 使用自动填充和快速填充。
auto使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。
有关详细信息，请参阅 使用自动填充和快速填充。
calculate()
计算工作表上的单元格区域。
clear(apply清除范围值和格式设置，例如填充和边框。
clear(apply清除范围值和格式设置，例如填充和边框。
clear清除区域中单元格的值，并特别考虑包含控件的单元格。 如果区域仅包含空白值和设置为默认值的控件，则会删除值和控件格式。 否则，这会将包含控件的单元格设置为默认值，并清除区域中其他单元格的值。
convert将数据类型为文本的区域单元格。
convert在工作表中将区域单元格转换为链接数据类型。
copy将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源，则会自动扩展。 注意：与 Excel UI 中的复制功能一样，如果目标范围正好大于行或列中源范围的倍数，则会多次复制源内容。 例如，将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。
copy将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源，则会自动扩展。 注意：与 Excel UI 中的复制功能一样，如果目标范围正好大于行或列中源范围的倍数，则会多次复制源内容。 例如，将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。
delete(shift)
删除与区域相关的单元格。
delete(shift删除与区域相关的单元格。
find(text, criteria)
根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。
find根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。 如果没有匹配项，则此方法返回对象的 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
flash对当前范围执行快速填充。 快速填充在感知模式时自动填充数据，因此范围必须是单个列范围，并且周围有数据才能找到模式。
get获取一个 Range 对象，该对象具有与当前 Range 对象相同的左上角单元格，但具有指定的行数和列数。
get获取包含指定区域的最小 range 对象。 例如， GetBoundingRect “B2：C5”和“D10：E15”的 为“B2：E15”。
get根据行和列编号获取包含单个单元格的 range 对象。 单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。 返回的单元格位于相对于区域左上角的单元格的位置。
get返回一个 2D 数组，其中封装了每个单元格的字体、填充、边框、对齐方式和其他属性数据。
get获取范围中包含的列。
get返回一个一维数组，其中封装了每个列的字体、填充、边框、对齐方式和其他属性数据。 对于给定列中每个单元格不一致的属性，将返回 null。
get获取当前 Range 对象右侧的一定数量的列。
get获取当前 Range 对象左侧的一定数量的列。
get返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或多个工作表中指定区域的所有依赖单元格的区域。 注意：如果未找到依赖项，此 API 将返回错误 ItemNotFound 。
get返回一个 对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有直接依赖单元格的区域。 注意：如果未找到依赖项，此 API 将返回错误 ItemNotFound 。
get返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。 注意：如果未找到任何先例，此 API 将返回错误 ItemNotFound 。
get返回一个 2D 数组，该数组封装每个单元格的字体、填充、边框、对齐方式和其他属性的显示数据。 与 （仅显示直接为单元格设置的属性）不同 getCellProperties，这会返回从间接源（例如条件格式或样式）显示的属性。
get获取一个 对象，该对象表示区域 (的整个列，例如，如果当前区域表示单元格“B4：E11”，则它是 getEntireColumn 表示列“B：E”) 的区域。
get获取一个对象，该对象表示区域 (的整行，例如，如果当前区域表示单元格“B4：E11”，则它是 GetEntireRow 表示行“4：11”) 的区域。
get返回一个 range 对象，该对象包括当前范围以及范围边缘，具体取决于提供的方向。 这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。
get返回一个 range 对象，该对象包括当前范围以及范围边缘，具体取决于提供的方向。 这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。
get将范围呈现为 Base64 编码的 PNG 图像。
get获取表示指定区域的矩形交集的 range 对象。
get获取表示指定区域的矩形交集的 range 对象。 如果未找到交集，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
get获取区域内的最后一个单元格。 例如，“B2:D5”的最后一个单元格是“D5”。
get获取区域内的最后一列。 例如，“B2:D5”的最后一列是“D2:D5”。
get获取区域内的最后一行。 例如，“B2:D5”的最后一行是“B5:D5”。
get返回一个 RangeAreas 对象，该对象代表此区域中的合并区域。 请注意，如果此范围内的合并区域计数超过 512，则此方法将无法返回结果。
RangeAreas如果该对象不存在，则此函数将返回一个对象，其isNullObject属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
get获取表示与指定区域偏移的区域的对象。 返回的区域的尺寸将与此区域一致。 如果强制在工作表网格的边界之外生成区域，将引发错误。
get获取与区域重叠的数据透视表的作用域集合。
get返回一个 对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有前置单元格的区域。 注意：如果未找到任何先例，此 API 将返回错误 ItemNotFound 。
get返回一个 range 对象，该对象是与提供的方向对应的数据区域边缘单元格。 这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。
get返回一个 range 对象，该对象是与提供的方向对应的数据区域边缘单元格。 这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。
get获取与 Range 当前 Range 对象类似的对象，但其右下角展开 (或按行和列数收缩) 。
get获取范围中包含的行。
get返回一个一维数组，其中封装了每个行的字体、填充、边框、对齐方式和其他属性数据。 对于在给定行内每个单元格中不一致的属性， null 将返回 。
get获取当前 Range 对象上方的一定行数。
get获取当前 Range 对象下面的特定行数。
getRangeAreas获取对象，该对象包含一个或多个矩形区域，该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格， ItemNotFound 则会引发错误。
getRangeAreas获取对象，该对象包含一个或多个矩形区域，该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格， ItemNotFound 则会引发错误。
getRangeAreas获取由一个或多个区域组成的 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getRangeAreas获取由一个或多个区域组成的 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
get获取 Range 对象，它在调用定位单元格时包含溢出区域。 如果应用于具有多个单元格的区域，则会失败。
get获取 Range 对象，它在调用定位单元格时包含溢出区域。 如果区域不是定位点单元格或找不到溢出区域，则此方法返回对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
get获取 Range 对象，它包含要将某个单元格溢出到的定位单元格。 如果应用于具有多个单元格的区域，则会失败。
get获取包含要溢出到的单元格的定位单元格的范围对象。 如果它不是溢出的单元格，或者提供了多个单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
get返回一个 Range 对象，该对象代表此区域中左上角单元格的周围区域。 周围区域是由相对于该区域的空白行和空白列的任何组合所限定的区域。
get获取与区域重叠的限定范围的表格集合。
get返回指定 range 对象的所用区域。 如果区域中没有使用的单元格，则此函数将引发错误 ItemNotFound 。
get返回指定 range 对象的所用区域。 如果区域中没有已用单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
get表示当前 range 对象的可见行。
group(group对大纲的列和行进行分组。
group(group对大纲的列和行进行分组。
hide隐藏行或列组的详细信息。
hide隐藏行或列组的详细信息。
insert(shift)
将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。 返回现在空白处的新 Range 对象。
insert(shift将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。 返回现在空白处的新 Range 对象。
load(options)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(property将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(property将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
merge(across)
将范围单元格合并到工作表的一个区域内。
move将单元格值、格式和公式从当前区域移动到目标区域，替换这些单元格中的旧信息。 如果目标范围小于当前范围，则会自动扩展。 不会更改目标区域中超出原始区域区域的任何单元格。
remove从列指定的区域中删除重复值。
replace根据当前区域内指定的条件查找并替换给定的字符串。
select()
在 Excel UI 中选择指定的区域。
set(properties, options)
同时设置对象的多个属性。 可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。
set(properties)
基于现有的已加载对象，同时对对象设置多个属性。
set基于单元格属性的 2D 数组汇报区域，封装字体、填充、边框和对齐等内容。
set基于列属性的单维数组汇报范围，并封装字体、填充、边框和对齐方式等内容。
set设置下一次重新计算发生时要重新计算的区域。
set基于行属性的一维数组汇报区域，并封装字体、填充、边框和对齐方式等内容。
show显示活动单元格的卡片（如果该单元格具有富值内容）。
show显示行或列组的详细信息。
show显示行或列组的详细信息。
toggle在 Excel 公式 =PY 中设置 Python 的封送模式。
toggle在 Excel 公式 =PY 中设置 Python 的封送模式。
toJSON()
重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。
JSON.stringify
(，依次调用toJSON传递给它的 对象的 方法。) 虽然原始Excel.Range对象是 API 对象，toJSON但该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.RangeData) ，其中包含从原始对象加载的任何子属性的浅表副本。
track()
根据文档中的相应更改来跟踪对象，以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。
ungroup(group取消对大纲的列和行的分组。
ungroup(group取消对大纲的列和行的分组。
unmerge()
将范围单元格取消合并为各个单元格。
untrack()
释放与此对象关联的内存（如果先前已跟踪过）。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。 在内存发布生效之前，需要调用 context.sync() 。
true当一个区域中的所有列都隐藏时，值。
false当区域中没有列处于隐藏状态时，该值为 。
null当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。
columnHidden: boolean;
boolean
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml
// Add checkboxes to the table.
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getActiveWorksheet();
// Get the second column in the table, without the header.
const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();
// Change the boolean values to checkboxes.
range.control = {
type: Excel.CellControlType.checkbox
await context.sync();
表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。 例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。 如果单元格没有公式，则返回其值。
formulasLocal: any[][];
any[][]
表示所有单元格是否都具有溢出边框。
true如果所有单元格都有溢出边框，或者false所有单元格都没有溢出边框，则返回 。
null如果区域中有和没有溢出边框的单元格，则返回 。
readonly hasSpill: boolean;
boolean
表示当前区域中的所有单元格是否处于隐藏状态。 值是 true 隐藏区域中的所有单元格时。
false当区域中没有单元格被隐藏时，值。
null当某个区域中的某些单元格处于隐藏状态，而同一区域中的其他单元格未隐藏时，值表示。
readonly hidden: boolean;
boolean
// 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();
// 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);
表示基于用户语言设置的给定区域的 Excel 数字格式代码。 获取或设置 numberFormatLocal 属性时，Excel 不执行任何语言或格式强制。 任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。
numberFormatLocal: any[][];
any[][]
表示当前范围中的所有行是否处于隐藏状态。 值是 true 隐藏范围中的所有行时。
false当区域中没有隐藏行时，值。
null当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。
rowHidden: boolean;
boolean
表示是否将所有单元格另存为数组公式。
true如果所有单元格都另存为数组公式，或者false所有单元格不另存为数组公式，则返回 。
null如果某些单元格将保存为数组公式，而有些单元格则不保存，则返回 。
readonly savedAsArray: boolean;
boolean
// 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();
// 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();
表示指定区域的原始值。 返回的数据可以是字符串、数字或布尔值。 包含错误的单元格将返回错误字符串。 如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。
values: any[][];
any[][]
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml
// Change the value of the checkbox in B3.
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getActiveWorksheet();
const range = sheet.getRange("B3");
range.values = [["TRUE"]];
await context.sync();
此区域中单元格中值的 JSON 表示形式。 与 不同 Range.values， Range.valuesAsJson 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像，以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与 en-US 区域设置一致。 若要检索用户的显示区域设置中的数据，请使用 Range.valuesAsJsonLocal。
valuesAsJson: CellValue[][];
Excel.CellValue[][]
// 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();
此区域中单元格中值的 JSON 表示形式。 与 不同 Range.values， Range.valuesAsJsonLocal 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像，以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与用户的显示区域设置保持一致。 若要检索独立于区域设置的数据，请使用 Range.valuesAsJson。
valuesAsJsonLocal: CellValue[][];
Excel.CellValue[][]
使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。
有关详细信息，请参阅 使用自动填充和快速填充。
autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;
destinationRange
Excel.Range | string
要自动填充的目标范围。 如果目标区域为 null，则会根据周围的单元格填充数据 (这是双击 UI 的区域填充句柄) 时的行为。
autoFillType
Excel.AutoFillType
自动填充的类型。 根据当前范围的内容指定如何填充目标范围。 默认值为“FillDefault”。
[ API set： ExcelApi 1.9， ExcelApi Preview for null destinationRange ]
// 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();
使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 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”。
// 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?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void;
applyToString
"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"
可选。 确定清除操作的类型。 有关详细信息，请参阅 Excel.ClearApplyTo。
清除区域中单元格的值，并特别考虑包含控件的单元格。 如果区域仅包含空白值和设置为默认值的控件，则会删除值和控件格式。 否则，这会将包含控件的单元格设置为默认值，并清除区域中其他单元格的值。
clearOrResetContents(): void;
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml
// Remove all content from the Analysis column.
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getActiveWorksheet();
// Get the second column in the table, without the header.
const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();
// Clear all the data from the second column.
range.clearOrResetContents();
await context.sync();
将单元格数据或格式从源区域或 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。
// 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();
将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源，则会自动扩展。 注意：与 Excel UI 中的复制功能一样，如果目标范围正好大于行或列中源范围的倍数，则会多次复制源内容。 例如，将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。
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。
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();
// 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 searchText = (document.getElementById("searchText") as HTMLTextAreaElement).value;
const foundRange = searchRange.find(searchText, {
completeMatch: isCompleteMatchToggle,
matchCase: isMatchCaseToggle,
searchDirection: searchDirectionToggle
foundRange.load("address");
await context.sync();
console.log(foundRange.address);
根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。 如果没有匹配项，则此方法返回对象的 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;
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 searchText = (document.getElementById("searchText") as HTMLTextAreaElement).value;
const foundRange = searchRange.findOrNullObject(searchText, {
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);
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
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: 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}`);
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: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;
columnPropertiesLoadOptions
Excel.ColumnPropertiesLoadOptions
一个 对象，表示要加载的列属性。
OfficeExtension.ClientResult<Excel.ColumnProperties[]>
一个数组，其中每个项表示相应列的请求属性。
返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或多个工作表中指定区域的所有依赖单元格的区域。 注意：如果未找到依赖项，此 API 将返回错误 ItemNotFound 。
getDependents(): Excel.WorkbookRangeAreas;
Excel.WorkbookRangeAreas
// 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();
返回一个 对象，该对象表示包含同一 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();
返回一个 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();
返回一个 2D 数组，该数组封装每个单元格的字体、填充、边框、对齐方式和其他属性的显示数据。 与 （仅显示直接为单元格设置的属性）不同 getCellProperties，这会返回从间接源（例如条件格式或样式）显示的属性。
getDisplayedCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;
cellPropertiesLoadOptions
Excel.CellPropertiesLoadOptions
一个 对象，表示要加载的单元格属性。
OfficeExtension.ClientResult<Excel.CellProperties[][]>
一个 2D 数组，其中每个项表示所请求的相应单元格的显示属性。
// 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);
// 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: 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: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;
directionString
"Left" | "Right" | "Up" | "Down"
活动单元格的方向。
activeCell
Excel.Range | string
此区域中的活动单元格。 默认情况下，活动单元格是区域的左上角单元格。 如果活动单元格不在此范围内，则会引发错误。
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
获取表示指定区域的矩形交集的 range 对象。 如果未找到交集，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getIntersectionOrNullObject(anotherRange: Range | string): Excel.Range;
anotherRange
Excel.Range | string
将用于确定区域交集的 range 对象或区域地址。
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();
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
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
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
返回一个 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();
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
// 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}`);
返回一个 对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有前置单元格的区域。 注意：如果未找到任何先例，此 API 将返回错误 ItemNotFound 。
getPrecedents(): 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.
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: 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: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;
directionString
"Left" | "Right" | "Up" | "Down"
活动单元格的方向。
activeCell
Excel.Range | string
此区域中的活动单元格。 默认情况下，活动单元格是区域的左上角单元格。 如果活动单元格不在此范围内，则会引发错误。
Excel.Range
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: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;
rowPropertiesLoadOptions
Excel.RowPropertiesLoadOptions
一个 对象，表示要加载的行属性。
OfficeExtension.ClientResult<Excel.RowProperties[]>
一个数组，其中每个项表示相应行的请求属性。
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: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", 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" | "DirtyFormulas"
要包含的单元格类型。
cellValueTypeString
"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
Excel.RangeAreas
RangeAreas获取由一个或多个区域组成的 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;
cellType
Excel.SpecialCellType
要包含的单元格类型。
cellValueType
Excel.SpecialCellValueType
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
Excel.RangeAreas
RangeAreas获取由一个或多个区域组成的 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpecialCellsOrNullObject(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", 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" | "DirtyFormulas"
要包含的单元格类型。
cellValueTypeString
"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
Excel.RangeAreas
// 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}.`);
获取 Range 对象，它在调用定位单元格时包含溢出区域。 如果区域不是定位点单元格或找不到溢出区域，则此方法返回对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpillingToRangeOrNullObject(): Excel.Range;
Excel.Range
获取包含要溢出到的单元格的定位单元格的范围对象。 如果它不是溢出的单元格，或者提供了多个单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpillParentOrNullObject(): Excel.Range;
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();
返回指定 range 对象的所用区域。 如果区域中没有已用单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;
valuesOnly
boolean
仅将有值的单元格视为已使用的单元格。
Excel.Range
// 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();
指定如何按行或列对区域进行分组。
InvalidArgument当组选项不同于范围isEntireRow或isEntireColumn属性 (即range.isEntireRow为 true 且groupOption为“ByColumns”或range.isEntireColumn为 true 且groupOption为“ByRows”) 时，将引发错误。
// 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();
指定如何按行或列对区域进行分组。
InvalidArgument当组选项不同于范围isEntireRow或isEntireColumn属性 (即range.isEntireRow为 true 且groupOption为“ByColumns”或range.isEntireColumn为 true 且groupOption为“ByRows”) 时，将引发错误。
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();
// 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);
propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。
Excel.Range
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();
// 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: 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: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;
string
要查找的字符串。
replacement
string
替换原始字符串的字符串。
criteria
Excel.ReplaceCriteria
其他替换条件。
OfficeExtension.ClientResult<number>
执行的替换次数。
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: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;
properties
Excel.Interfaces.RangeUpdateData
一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。
options
OfficeExtension.UpdateOptions
提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。
// 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();
// 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();
重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。
JSON.stringify
(，依次调用toJSON传递给它的 对象的 方法。) 虽然原始Excel.Range对象是 API 对象，toJSON但该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.RangeData) ，其中包含从原始对象加载的任何子属性的浅表副本。
toJSON(): Excel.Interfaces.RangeData;
Excel.Interfaces.RangeData
根据文档中的相应更改来跟踪对象，以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。
track(): Excel.Range;
Excel.Range
// 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();
await Excel.run(async (context) => {
const sheetName = "Sheet1";
const rangeAddress = "A1:C3";
const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
range.unmerge();
await context.sync();
释放与此对象关联的内存（如果先前已跟踪过）。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。 在内存发布生效之前，需要调用 context.sync() 。
untrack(): Excel.Range;
Excel.Range
await Excel.run(async (context) => {
const largeRange = context.workbook.getSelectedRange();
largeRange.load(["rowCount", "columnCount"]);
await context.sync();
for (let i = 0; i < largeRange.rowCount; i++) {
for (let j = 0; j < largeRange.columnCount; j++) {
const cell = largeRange.getCell(i, j);
cell.values = [[i *j]];
// Call untrack() to release the range from memory.
cell.untrack();
await context.sync();
推荐文章