Excel.Range class

El rango representa un conjunto de una o más celdas contiguas, como una celda, una fila, una columna o un bloque de celdas. Para obtener más información sobre cómo se usan los intervalos en toda la API, comience con Intervalos en la API de JavaScript de Excel.

Comentarios

Conjunto de API: ExcelApi 1.1

Usada por

Ejemplos

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

Propiedades

address	Especifica el rango de referencia en estilo A1. El valor de dirección contiene la referencia de hoja (por ejemplo, "Hoja1! A1:B4").
addressLocal	Representa la referencia de rango para el rango especificado en el idioma del usuario.
cellCount	Especifica el número de celdas del rango. Esta API devolverá -1 si el recuento de celdas supera 2^31-1 (2 147 483 647).
columnCount	Especifica el número total de columnas del rango.
columnIndex	Especifica el número de columna de la primera celda del rango. Indizado con cero.
context	El contexto de solicitud asociado al objeto. De esta forma, se conecta el proceso del complemento con el proceso de la aplicación host de Office.
format	Devuelve un objeto de formato que encapsula la fuente, el relleno, los bordes, la alineación y otras propiedades del rango.
formulas	Representa la fórmula en notación de estilo A1. Si una celda no tiene fórmula, se devuelve su valor en su lugar.
formulasLocal	Representa la fórmula en notación de estilo A1, en el idioma del usuario y en la configuración regional del formato numérico. Por ejemplo, la fórmula "=SUM(A1, 1.5)" en inglés se convertiría en "=SUMME(A1; 1,5)" en alemán. Si una celda no tiene fórmula, se devuelve su valor en su lugar.
numberFormat	Representa el código de formato de número de Excel para un rango determinado. Para obtener más información sobre el formato de número de Excel, vea códigos de formato de número.
rowCount	Devuelve el número total de filas del intervalo.
rowIndex	Devuelve el número de fila de la primera celda del intervalo. Indizado con cero.
text	Valores de texto del intervalo especificado. El valor Text no dependerá del ancho de la celda. La sustitución de signos de número (#) que se produce en la interfaz de usuario de Excel no afectará al valor de texto devuelto por la API.
values	Representa los valores sin formato del rango especificado. Los datos devueltos pueden ser una cadena, un número o un valor booleano. Las celdas que contienen un error devolverán la cadena de error. Si el valor devuelto comienza con un signo más ("+"), menos ("-") o igual ("="), Excel interpretará este valor como una fórmula. Las cadenas con forma de configuración regional (como la fecha "19-8-2025" en nl-NL o fr-FR, formato DD-MM-AAAA) se almacenan como texto en lugar de como fechas. Para asegurarse de que las fechas se almacenan como fechas, use una API compatible con la configuración regional, como `formulasLocal` o use un formato independiente de la configuración regional, como ISO (AAAAA-MM-DD) o una serie de fechas numéricas.
valueTypes	Especifica el tipo de datos de cada celda.
worksheet	Hoja de cálculo que contiene el rango actual.

Métodos

clear(applyTo)	Borrar valores de rango y formato, como relleno y borde.
clear(applyTo)	Borrar valores de rango y formato, como relleno y borde.
delete(shift)	Elimina las celdas asociadas al rango.
delete(shift)	Elimina las celdas asociadas al rango.
getBoundingRect(anotherRange)	Obtiene el objeto de intervalo más pequeño que abarca los intervalos especificados. Por ejemplo, el `GetBoundingRect` valor de "B2:C5" y "D10:E15" es "B2:E15".
getCell(row, column)	Obtiene el objeto de intervalo que contiene la celda en función de los números de fila y columna. La celda puede estar fuera de los límites de su rango primario siempre que se mantenga dentro de la cuadrícula de la hoja de cálculo. La celda devuelta se ubica con respecto a la celda superior izquierda del intervalo.
getColumn(column)	Obtiene una columna contenida en el intervalo.
getEntireColumn()	Obtiene un objeto que representa toda la columna del rango (por ejemplo, si el rango actual representa las celdas "B4:E11", este `getEntireColumn` es un rango que representa las columnas "B:E").
getEntireRow()	Obtiene un objeto que representa toda la fila del rango (por ejemplo, si el rango actual representa las celdas "B4:E11", este `GetEntireRow` es un rango que representa las filas "4:11").
getIntersection(anotherRange)	Obtiene el objeto de rango que representa la intersección rectangular de los rangos especificados.
getLastCell()	Obtiene la última celda del intervalo. Por ejemplo, la última celda de "B2:D5" es "D5".
getLastColumn()	Obtiene la última columna del intervalo. Por ejemplo, la última columna de "B2:D5" es "D2:D5".
getLastRow()	Obtiene la última fila del intervalo. Por ejemplo, la última fila de "B2:D5" es "B5:D5".
getOffsetRange(rowOffset, columnOffset)	Obtiene un objeto que representa un intervalo desplazado con respecto al intervalo especificado. La dimensión del rango devuelto coincidirá con este rango. Si el rango resultante se fuerza más allá de los límites de la cuadrícula de la hoja de cálculo, se producirá un error.
getRow(row)	Obtiene una fila contenida en el intervalo.
insert(shift)	Inserta una celda o un intervalo de celdas en la hoja de cálculo en lugar de este intervalo y desplaza las demás celdas para crear espacio. Devuelve un nuevo `Range` objeto en el espacio en blanco.
insert(shift)	Inserta una celda o un intervalo de celdas en la hoja de cálculo en lugar de este intervalo y desplaza las demás celdas para crear espacio. Devuelve un nuevo `Range` objeto en el espacio en blanco.
load(options)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
load(propertyNames)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
load(propertyNamesAndPaths)	Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a `context.sync()` antes de leer las propiedades.
select()	Selecciona el intervalo especificado en la interfaz de usuario de Excel.
set(properties, options)	Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto API del mismo tipo.
set(properties)	Establece varias propiedades en el objeto al mismo tiempo, basadas en un objeto cargado existente.
toJSON()	Reemplaza el método JavaScript `toJSON()` para proporcionar una salida más útil cuando se pasa un objeto API a `JSON.stringify()`. (`JSON.stringify`, a su vez, llama al `toJSON` método del objeto que se le pasa). Mientras que el objeto original `Excel.Range` es un objeto API, el `toJSON` método devuelve un objeto JavaScript simple (escrito como `Excel.Interfaces.RangeData`) que contiene copias superficiales de cualquier propiedad secundaria cargada del objeto original.
track()	Realiza un seguimiento del objeto de ajuste automático según cambios adyacentes en el documento. Esta llamada es una abreviatura de context.trackedObjects.add(thisObject). Si usa este objeto entre `.sync` llamadas y fuera de la ejecución secuencial de un lote ".run" y recibe un error "InvalidObjectPath" al establecer una propiedad o invocar un método en el objeto, debe agregar el objeto a la colección de objetos objeto de seguimiento cuando se creó el objeto por primera vez.
untrack()	Libere la memoria asociada a este objeto, si se ha realizado un seguimiento de él anteriormente. Esta llamada es la abreviatura de context.trackedObjects.remove(thisObject). Tener muchos objetos marcados ralentiza la aplicación host, así que debe recordar liberar los objetos que agregue cuando haya terminado con ellos. Deberá llamar `context.sync()` antes de que la liberación de memoria surta efecto.

address

Especifica el rango de referencia en estilo A1. El valor de dirección contiene la referencia de hoja (por ejemplo, "Hoja1! A1:B4").

readonly address: string;

Valor de propiedad

string

Comentarios

Conjunto de API: ExcelApi 1.1

addressLocal

Representa la referencia de rango para el rango especificado en el idioma del usuario.

readonly addressLocal: string;

Valor de propiedad

string

Comentarios

Conjunto de API: ExcelApi 1.1

cellCount

Especifica el número de celdas del rango. Esta API devolverá -1 si el recuento de celdas supera 2^31-1 (2 147 483 647).

readonly cellCount: number;

Valor de propiedad

number

Comentarios

Conjunto de API: ExcelApi 1.1

columnCount

Especifica el número total de columnas del rango.

readonly columnCount: number;

Valor de propiedad

number

Comentarios

Conjunto de API: ExcelApi 1.1

columnIndex

Especifica el número de columna de la primera celda del rango. Indizado con cero.

readonly columnIndex: number;

Valor de propiedad

number

Comentarios

Conjunto de API: ExcelApi 1.1

context

El contexto de solicitud asociado al objeto. De esta forma, se conecta el proceso del complemento con el proceso de la aplicación host de Office.

context: RequestContext;

Valor de propiedad

Excel.RequestContext

format

Devuelve un objeto de formato que encapsula la fuente, el relleno, los bordes, la alineación y otras propiedades del rango.

readonly format: Excel.RangeFormat;

Valor de propiedad

Excel.RangeFormat

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/46-table/formatting.yaml

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

    expensesTable.getHeaderRowRange().format.fill.color = "#C70039";
    expensesTable.getDataBodyRange().format.fill.color = "#DAF7A6";
    expensesTable.rows.getItemAt(1).getRange().format.fill.color = "#FFC300";
    expensesTable.columns.getItemAt(0).getDataBodyRange().format.fill.color = "#FFA07A";
    
  await context.sync();
});

formulas

Representa la fórmula en notación de estilo A1. Si una celda no tiene fórmula, se devuelve su valor en su lugar.

formulas: any[][];

Valor de propiedad

any[][]

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

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

    const data = [
        ["Total Price"],
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    
    const range = sheet.getRange("E2:E6");
    range.formulas = data;
    range.format.autofitColumns();

    await context.sync();
});

formulasLocal

Representa la fórmula en notación de estilo A1, en el idioma del usuario y en la configuración regional del formato numérico. Por ejemplo, la fórmula "=SUM(A1, 1.5)" en inglés se convertiría en "=SUMME(A1; 1,5)" en alemán. Si una celda no tiene fórmula, se devuelve su valor en su lugar.

formulasLocal: any[][];

Valor de propiedad

any[][]

Comentarios

Conjunto de API: ExcelApi 1.1

numberFormat

Representa el código de formato de número de Excel para un rango determinado. Para obtener más información sobre el formato de número de Excel, vea códigos de formato de número.

numberFormat: any[][];

Valor de propiedad

any[][]

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

rowCount

Devuelve el número total de filas del intervalo.

readonly rowCount: number;

Valor de propiedad

number

Comentarios

Conjunto de API: ExcelApi 1.1

rowIndex

Devuelve el número de fila de la primera celda del intervalo. Indizado con cero.

readonly rowIndex: number;

Valor de propiedad

number

Comentarios

Conjunto de API: ExcelApi 1.1

text

Valores de texto del intervalo especificado. El valor Text no dependerá del ancho de la celda. La sustitución de signos de número (#) que se produce en la interfaz de usuario de Excel no afectará al valor de texto devuelto por la API.

readonly text: string[][];

Valor de propiedad

string[][]

Comentarios

Conjunto de API: ExcelApi 1.1

values

Representa los valores sin formato del rango especificado. Los datos devueltos pueden ser una cadena, un número o un valor booleano. Las celdas que contienen un error devolverán la cadena de error. Si el valor devuelto comienza con un signo más ("+"), menos ("-") o igual ("="), Excel interpretará este valor como una fórmula. Las cadenas con forma de configuración regional (como la fecha "19-8-2025" en nl-NL o fr-FR, formato DD-MM-AAAA) se almacenan como texto en lugar de como fechas. Para asegurarse de que las fechas se almacenan como fechas, use una API compatible con la configuración regional, como formulasLocal o use un formato independiente de la configuración regional, como ISO (AAAAA-MM-DD) o una serie de fechas numéricas.

values: any[][];

Valor de propiedad

any[][]

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

valueTypes

Especifica el tipo de datos de cada celda.

readonly valueTypes: Excel.RangeValueType[][];

Valor de propiedad

Excel.RangeValueType[][]

Comentarios

Conjunto de API: ExcelApi 1.1

worksheet

Hoja de cálculo que contiene el rango actual.

readonly worksheet: Excel.Worksheet;

Valor de propiedad

Excel.Worksheet

Comentarios

Conjunto de API: ExcelApi 1.1

clear(applyTo)

Borrar valores de rango y formato, como relleno y borde.

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

Parámetros

applyTo: Excel.ClearApplyTo

Opcional. Determina el tipo de acción de borrado. Vea Excel.ClearApplyTo para más información.

Devoluciones

void

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

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

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

    range.clear();

    await context.sync();
});

clear(applyTo)

Borrar valores de rango y formato, como relleno y borde.

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

Parámetros

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

Opcional. Determina el tipo de acción de borrado. Vea Excel.ClearApplyTo para más información.

Devoluciones

void

Comentarios

Conjunto de API: ExcelApi 1.1

delete(shift)

Elimina las celdas asociadas al rango.

delete(shift: Excel.DeleteShiftDirection): void;

Parámetros

shift: Excel.DeleteShiftDirection

Especifica hacia dónde se desplazarán las celdas. Vea Excel.DeleteShiftDirection para más información.

Devoluciones

void

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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/30-events/events-worksheet.yaml

// This function deletes data from a range and sets the delete shift direction to "up".
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range: Excel.Range = sheet.getRange("A5:F5");
    range.delete(Excel.DeleteShiftDirection.up);
});

delete(shift)

Elimina las celdas asociadas al rango.

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

Parámetros

shift: "Up" | "Left"

Especifica hacia dónde se desplazarán las celdas. Vea Excel.DeleteShiftDirection para más información.

Devoluciones

void

Comentarios

Conjunto de API: ExcelApi 1.1

getBoundingRect(anotherRange)

Obtiene el objeto de intervalo más pequeño que abarca los intervalos especificados. Por ejemplo, el GetBoundingRect valor de "B2:C5" y "D10:E15" es "B2:E15".

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

Parámetros

anotherRange: Excel.Range | string

El objeto de rango, la dirección o el nombre del rango.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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)

Obtiene el objeto de intervalo que contiene la celda en función de los números de fila y columna. La celda puede estar fuera de los límites de su rango primario siempre que se mantenga dentro de la cuadrícula de la hoja de cálculo. La celda devuelta se ubica con respecto a la celda superior izquierda del intervalo.

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

Parámetros

row: number

Número de fila de la celda que se va a recuperar. Indizado con cero.

column: number

Número de columna de la celda que se va a recuperar. Indizado con cero.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

getColumn(column)

Obtiene una columna contenida en el intervalo.

getColumn(column: number): Excel.Range;

Parámetros

column: number

Número de columna del intervalo que se va a recuperar. Indizado con cero.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

getEntireColumn()

Obtiene un objeto que representa toda la columna del rango (por ejemplo, si el rango actual representa las celdas "B4:E11", este getEntireColumn es un rango que representa las columnas "B:E").

getEntireColumn(): Excel.Range;

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

// 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()

Obtiene un objeto que representa toda la fila del rango (por ejemplo, si el rango actual representa las celdas "B4:E11", este GetEntireRow es un rango que representa las filas "4:11").

getEntireRow(): Excel.Range;

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

getIntersection(anotherRange)

Obtiene el objeto de rango que representa la intersección rectangular de los rangos especificados.

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

Parámetros

anotherRange: Excel.Range | string

Objeto de intervalo o dirección de intervalo que se usará para determinar la intersección de los intervalos.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

getLastCell()

Obtiene la última celda del intervalo. Por ejemplo, la última celda de "B2:D5" es "D5".

getLastCell(): Excel.Range;

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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()

Obtiene la última columna del intervalo. Por ejemplo, la última columna de "B2:D5" es "D2:D5".

getLastColumn(): Excel.Range;

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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()

Obtiene la última fila del intervalo. Por ejemplo, la última fila de "B2:D5" es "B5:D5".

getLastRow(): Excel.Range;

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

getOffsetRange(rowOffset, columnOffset)

Obtiene un objeto que representa un intervalo desplazado con respecto al intervalo especificado. La dimensión del rango devuelto coincidirá con este rango. Si el rango resultante se fuerza más allá de los límites de la cuadrícula de la hoja de cálculo, se producirá un error.

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

Parámetros

rowOffset: number

Número de filas (número positivo, negativo o 0) que debe desplazarse el intervalo. Los valores positivos desplazan hacia abajo, mientras que los negativos lo hacen hacia arriba.

columnOffset: number

Número de columnas (número positivo, negativo o 0) que debe desplazarse el intervalo. Los valores positivos desplazan hacia la derecha, mientras que los negativos lo hacen hacia la izquierda.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

getRow(row)

Obtiene una fila contenida en el intervalo.

getRow(row: number): Excel.Range;

Parámetros

row: number

Número de fila del intervalo que se va a recuperar. Indizado con cero.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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

insert(shift)

Inserta una celda o un intervalo de celdas en la hoja de cálculo en lugar de este intervalo y desplaza las demás celdas para crear espacio. Devuelve un nuevo Range objeto en el espacio en blanco.

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

Parámetros

shift: Excel.InsertShiftDirection

Especifica hacia dónde se desplazarán las celdas. Vea Excel.InsertShiftDirection para más información.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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(shift)

Inserta una celda o un intervalo de celdas en la hoja de cálculo en lugar de este intervalo y desplaza las demás celdas para crear espacio. Devuelve un nuevo Range objeto en el espacio en blanco.

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

Parámetros

shift: "Down" | "Right"

Especifica hacia dónde se desplazarán las celdas. Vea Excel.InsertShiftDirection para más información.

Devoluciones

Excel.Range

Comentarios

Conjunto de API: ExcelApi 1.1

load(options)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

options: Excel.Interfaces.RangeLoadOptions

Proporciona opciones para las propiedades del objeto que se van a cargar.

Devoluciones

Excel.Range

load(propertyNames)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

propertyNames: string | string[]

Una cadena delimitada por comas o una matriz de cadenas que especifican las propiedades que se van a cargar.

Devoluciones

Excel.Range

Ejemplos

// 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)

Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a context.sync() antes de leer las propiedades.

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

Parámetros

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

propertyNamesAndPaths.select es una cadena delimitada por comas que especifica las propiedades que se van a cargar y propertyNamesAndPaths.expand es una cadena delimitada por comas que especifica las propiedades de navegación que se van a cargar.

Devoluciones

Excel.Range

select()

Selecciona el intervalo especificado en la interfaz de usuario de Excel.

select(): void;

Devoluciones

void

Comentarios

Conjunto de API: ExcelApi 1.1

Ejemplos

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)

Establece varias propiedades de un objeto al mismo tiempo. Puede pasar un objeto sin formato con las propiedades adecuadas u otro objeto API del mismo tipo.

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

Parámetros

properties: Excel.Interfaces.RangeUpdateData

Un objeto JavaScript con propiedades que están estructuradas isomorfamente a las propiedades del objeto en el que se llama al método.

options: OfficeExtension.UpdateOptions

Proporciona una opción para suprimir errores si el objeto properties intenta establecer propiedades de solo lectura.

Devoluciones

void

set(properties)

Establece varias propiedades en el objeto al mismo tiempo, basadas en un objeto cargado existente.

set(properties: Excel.Range): void;

Parámetros

properties: Excel.Range

Devoluciones

void

Ejemplos

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

toJSON()

Reemplaza el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto API a JSON.stringify(). (JSON.stringify, a su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto original Excel.Range es un objeto API, el toJSON método devuelve un objeto JavaScript simple (escrito como Excel.Interfaces.RangeData) que contiene copias superficiales de cualquier propiedad secundaria cargada del objeto original.

toJSON(): Excel.Interfaces.RangeData;

Devoluciones

Excel.Interfaces.RangeData

track()

Realiza un seguimiento del objeto de ajuste automático según cambios adyacentes en el documento. Esta llamada es una abreviatura de context.trackedObjects.add(thisObject). Si usa este objeto entre .sync llamadas y fuera de la ejecución secuencial de un lote ".run" y recibe un error "InvalidObjectPath" al establecer una propiedad o invocar un método en el objeto, debe agregar el objeto a la colección de objetos objeto de seguimiento cuando se creó el objeto por primera vez.

track(): Excel.Range;

Devoluciones

Excel.Range

untrack()

Libere la memoria asociada a este objeto, si se ha realizado un seguimiento de él anteriormente. Esta llamada es la abreviatura de context.trackedObjects.remove(thisObject). Tener muchos objetos marcados ralentiza la aplicación host, así que debe recordar liberar los objetos que agregue cuando haya terminado con ellos. Deberá llamar context.sync() antes de que la liberación de memoria surta efecto.

untrack(): Excel.Range;

Devoluciones

Excel.Range

Ejemplos

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

Comentarios

Usada por

Ejemplos

Propiedades

Métodos

Detalles de las propiedades

address

Valor de propiedad

Comentarios

addressLocal

Valor de propiedad

Comentarios

cellCount

Valor de propiedad

Comentarios

columnCount

Valor de propiedad

Comentarios

columnIndex

Valor de propiedad

Comentarios

context

Valor de propiedad

format

Valor de propiedad

Comentarios

Ejemplos

formulas

Valor de propiedad

Comentarios

Ejemplos

formulasLocal

Valor de propiedad

Comentarios

numberFormat

Valor de propiedad

Comentarios

Ejemplos

rowCount

Valor de propiedad

Comentarios

rowIndex

Valor de propiedad

Comentarios

text

Valor de propiedad

Comentarios

values

Valor de propiedad

Comentarios

Ejemplos

valueTypes

Valor de propiedad

Comentarios

worksheet

Valor de propiedad

Comentarios

Detalles del método

clear(applyTo)

Parámetros

Devoluciones

Comentarios

Ejemplos

clear(applyTo)

Parámetros

Devoluciones

Comentarios

delete(shift)

Parámetros

Devoluciones

Comentarios

Ejemplos

delete(shift)

Parámetros

Devoluciones

Comentarios

getBoundingRect(anotherRange)

Parámetros

Devoluciones