Excel.Range class

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

readonly address: string;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly addressLocal: string;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Especifica el número total de columnas del intervalo.

readonly columnCount: number;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly columnIndex: number;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al proceso de la aplicación host de Office.

context: RequestContext;

Valor de propiedad

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

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

formulas: any[][];

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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 ninguna fórmula, su valor se devuelve en su lugar.

formulasLocal: any[][];

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Representa el código de formato de número de Excel para el intervalo especificado. Para obtener más información sobre el formato de números de Excel, vea Códigos de formato de número.

numberFormat: any[][];

Valor de propiedad

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

Devuelve el número total de filas del intervalo.

readonly rowCount: number;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

readonly rowIndex: number;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Valores de texto del intervalo especificado. El valor Text no dependerá del ancho de la celda. La sustitución del signo 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

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Representa los valores sin formato del rango especificado. Los datos devueltos podrían 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 un signo igual ("="), Excel interpreta este valor como una fórmula.

values: any[][];

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Especifica el tipo de datos de cada celda.

readonly valueTypes: Excel.RangeValueType[][];

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Hoja de cálculo que contiene el rango actual.

readonly worksheet: Excel.Worksheet;

Valor de propiedad

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Borre los valores de intervalo y el formato, como el relleno y el borde.

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

Parámetros

Devoluciones

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

Borre los valores de intervalo y el formato, como el relleno y el borde.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

Elimina las celdas asociadas al rango.

delete(shift: Excel.DeleteShiftDirection): void;

Parámetros

Devoluciones

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

Elimina las celdas asociadas al rango.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

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

Parámetros

Devoluciones

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

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 y cuando permanezca 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

Devoluciones

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

Obtiene una columna contenida en el intervalo.

getColumn(column: number): Excel.Range;

Parámetros

Devoluciones

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

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

getEntireColumn(): Excel.Range;

Devoluciones

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

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

getEntireRow(): Excel.Range;

Devoluciones

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

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

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

Parámetros

Devoluciones

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

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

getLastCell(): Excel.Range;

Devoluciones

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

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

getLastColumn(): Excel.Range;

Devoluciones

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

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

getLastRow(): Excel.Range;

Devoluciones

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

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

Devoluciones

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

Obtiene una fila contenida en el intervalo.

getRow(row: number): Excel.Range;

Parámetros

Devoluciones

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

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 ahora en blanco.

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

Parámetros

Devoluciones

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

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 ahora en blanco.

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

Parámetros

Devoluciones

Comentarios

[ Conjunto de API: ExcelApi 1.1 ]

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

Devoluciones

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

Devoluciones

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

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

Devoluciones

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

select(): void;

Devoluciones

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

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

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

Parámetros

Devoluciones

Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente.

set(properties: Excel.Range): void;

Parámetros

Devoluciones

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

Invalida el método JavaScript toJSON() para proporcionar una salida más útil cuando se pasa un objeto de API a JSON.stringify(). (JSON.stringifya su vez, llama al toJSON método del objeto que se le pasa). Mientras que el objeto original Excel.Range es un objeto de API, el toJSON método devuelve un objeto JavaScript sin formato (escrito como Excel.Interfaces.RangeData) que contiene copias superficiales de las propiedades secundarias cargadas del objeto original.

toJSON(): Excel.Interfaces.RangeData;

Devoluciones

Realiza un seguimiento del objeto de ajuste automático según cambios adyacentes en el documento. Esta llamada es una abreviatura para context.trackedObjects.add(thisObject). Si usa este objeto entre .sync llamadas y fuera de la ejecución secuencial de un lote ".run" y obtiene 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 de seguimiento cuando se creó el objeto por primera vez.

track(): Excel.Range;

Devoluciones

Libere la memoria asociada a este objeto, si se ha realizado un seguimiento de él anteriormente. Esta llamada es abreviada para 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. Tendrá que llamar context.sync() a antes de que la versión de memoria surta efecto.

untrack(): Excel.Range;

Devoluciones

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