Excel.Range class
Range representa un conjunto de una o varias 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 Rangos en la API de JavaScript de Excel.
- Extends
Comentarios
[ Conjunto de API: ExcelApi 1.1 ]
Propiedades
| address | Especifica la referencia de rango en estilo A1. El valor de dirección contiene la referencia de hoja (por ejemplo, "Sheet1! A1:B4"). |
| address |
Representa la referencia de intervalo para el intervalo especificado en el idioma del usuario. |
| cell |
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). |
| column |
Especifica el número total de columnas del intervalo. |
| column |
Representa si todas las columnas del intervalo actual están ocultas. El valor es |
| column |
Especifica el número de columna de la primera celda del intervalo. Indizado con cero. |
| context | Contexto de solicitud asociado al objeto . Esto conecta el proceso del complemento al 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 ninguna fórmula, su valor se devuelve en su lugar. |
| formulas |
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. |
| formulasR1C1 | Representa la fórmula en notación de estilo R1C1. Si una celda no tiene ninguna fórmula, su valor se devuelve en su lugar. |
| hidden | Representa si todas las celdas del rango actual están ocultas. El valor es |
| number |
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. |
| row |
Devuelve el número total de filas del intervalo. |
| row |
Representa si todas las filas del intervalo actual están ocultas. El valor es |
| row |
Devuelve el número de fila de la primera celda del intervalo. Indizado con cero. |
| sort | Representa la ordenación del intervalo del intervalo actual. |
| text | 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. |
| values | 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. |
| value |
Especifica el tipo de datos de cada celda. |
| worksheet | Hoja de cálculo que contiene el rango actual. |
Métodos
| clear(apply |
Borra valores de rango, formato, relleno, borde, etc. |
| clear(apply |
Borra valores de rango, formato, relleno, borde, etc. |
| delete(shift) | Elimina las celdas asociadas al rango. |
| delete(shift |
Elimina las celdas asociadas al rango. |
| get |
Obtiene el objeto de intervalo más pequeño que abarca los intervalos especificados. Por ejemplo, el |
| get |
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. |
| get |
Obtiene una columna contenida en el intervalo. |
| get |
Obtiene un determinado número de columnas a la derecha del objeto actual |
| get |
Obtiene un determinado número de columnas a la izquierda del objeto actual |
| get |
Obtiene un objeto que representa toda la columna del rango (por ejemplo, si el rango actual representa las celdas "B4:E11", es |
| get |
Obtiene un objeto que representa toda la fila del rango (por ejemplo, si el rango actual representa las celdas "B4:E11", es |
| get |
Obtiene el objeto de rango que representa la intersección rectangular de los rangos especificados. |
| get |
Obtiene el objeto de rango que representa la intersección rectangular de los rangos especificados. Si no se encuentra ninguna intersección, este método devuelve un objeto con su |
| get |
Obtiene la última celda del intervalo. Por ejemplo, la última celda de "B2:D5" es "D5". |
| get |
Obtiene la última columna del intervalo. Por ejemplo, la última columna de "B2:D5" es "D2:D5". |
| get |
Obtiene la última fila del intervalo. Por ejemplo, la última fila de "B2:D5" es "B5:D5". |
| get |
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. |
| get |
Obtiene un |
| get |
Obtiene una fila contenida en el intervalo. |
| get |
Obtiene un número determinado de filas por encima del objeto actual |
| get |
Obtiene un número determinado de filas por debajo del objeto actual |
| get |
Devuelve el intervalo usado del objeto de rango especificado. Si no hay celdas usadas dentro del rango, esta función producirá un |
| get |
Devuelve el intervalo usado del objeto de rango especificado. Si no hay celdas usadas dentro del rango, este método devuelve un objeto con su |
| get |
Representa las filas visibles del intervalo actual. |
| 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 |
| 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 |
| load(options) | Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a |
| load(property |
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a |
| load(property |
Pone en cola un comando para cargar las propiedades especificadas del objeto. Debe llamar a |
| merge(across) | Combina las celdas del intervalo en una región de la hoja de cálculo. |
| 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 de API del mismo tipo. |
| set(properties) | Establece varias propiedades en el objeto al mismo tiempo, en función de un objeto cargado existente. |
| toJSON() | Invalida el método JavaScript |
| track() | 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 |
| unmerge() | Separa las celdas del intervalo en celdas independientes. |
| untrack() | 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 |
Detalles de las propiedades
address
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
string
Comentarios
addressLocal
Representa la referencia de intervalo para el intervalo especificado en el idioma del usuario.
readonly addressLocal: string;Valor de propiedad
string
Comentarios
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
columnCount
Especifica el número total de columnas del intervalo.
readonly columnCount: number;Valor de propiedad
number
Comentarios
columnHidden
Representa si todas las columnas del intervalo actual están ocultas. El valor es true cuando todas las columnas de un intervalo están ocultas. El valor es false cuando no se oculta ninguna columna del intervalo. El valor es null cuando algunas columnas de un rango están ocultas y otras columnas del mismo rango no están ocultas.
columnHidden: boolean;Valor de propiedad
boolean
Comentarios
columnIndex
Especifica el número de columna de la primera celda del intervalo. Indizado con cero.
readonly columnIndex: number;Valor de propiedad
number
Comentarios
context
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
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
Comentarios
formulas
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
any[][]
Comentarios
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 ninguna fórmula, su valor se devuelve en su lugar.
formulasLocal: any[][];Valor de propiedad
any[][]
Comentarios
formulasR1C1
Representa la fórmula en notación de estilo R1C1. Si una celda no tiene ninguna fórmula, su valor se devuelve en su lugar.
formulasR1C1: any[][];Valor de propiedad
any[][]
Comentarios
hidden
Representa si todas las celdas del rango actual están ocultas. El valor es true cuando todas las celdas de un rango están ocultas. El valor es false cuando no se oculta ninguna celda del rango. El valor es null cuando algunas celdas de un rango están ocultas y otras celdas del mismo rango no están ocultas.
readonly hidden: boolean;Valor de propiedad
boolean
Comentarios
numberFormat
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
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
rowHidden
Representa si todas las filas del intervalo actual están ocultas. El valor es true cuando todas las filas de un intervalo están ocultas. El valor es false cuando no se oculta ninguna fila del intervalo. El valor es null cuando algunas filas de un rango están ocultas y otras filas del mismo rango no están ocultas.
rowHidden: boolean;Valor de propiedad
boolean
Comentarios
rowIndex
Devuelve el número de fila de la primera celda del intervalo. Indizado con cero.
readonly rowIndex: number;Valor de propiedad
number
Comentarios
sort
Representa la ordenación del intervalo del intervalo actual.
readonly sort: Excel.RangeSort;Valor de propiedad
Comentarios
[ Conjunto de API: ExcelApi 1.2 ]
Ejemplos
// 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();
});
}
text
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
string[][]
Comentarios
values
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
any[][]
Comentarios
valueTypes
Especifica el tipo de datos de cada celda.
readonly valueTypes: Excel.RangeValueType[][];Valor de propiedad
Comentarios
worksheet
Hoja de cálculo que contiene el rango actual.
readonly worksheet: Excel.Worksheet;Valor de propiedad
Comentarios
Detalles del método
clear(applyTo)
Borra valores de rango, formato, relleno, borde, etc.
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();
});
clear(applyToString)
Borra valores de rango, formato, relleno, borde, etc.
clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void;Parámetros
- applyToString
-
"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"
Opcional. Determina el tipo de acción de borrado. Vea Excel.ClearApplyTo para más información.
Devoluciones
void
Comentarios
delete(shift)
Elimina las celdas asociadas al rango.
delete(shift: Excel.DeleteShiftDirection): void;Parámetros
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();
});
delete(shiftString)
Elimina las celdas asociadas al rango.
delete(shiftString: "Up" | "Left"): void;Parámetros
- shiftString
-
"Up" | "Left"
Especifica hacia dónde se desplazarán las celdas. Vea Excel.DeleteShiftDirection para más información.
Devoluciones
void
Comentarios
getBoundingRect(anotherRange)
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
- anotherRange
-
Excel.Range | string
El objeto de rango, la dirección o el nombre del rango.
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
});
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 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
- 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
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
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
});
getColumnsAfter(count)
Obtiene un determinado número de columnas a la derecha del objeto actual Range .
getColumnsAfter(count?: number): Excel.Range;Parámetros
- count
-
number
Opcional. El número de columnas que se va a incluir en el rango resultante. En general, use un número positivo para crear un intervalo fuera del intervalo actual. También puede usar un número negativo para crear un intervalo dentro del intervalo actual. El valor predeterminado es 1.
Devoluciones
Comentarios
getColumnsBefore(count)
Obtiene un determinado número de columnas a la izquierda del objeto actual Range .
getColumnsBefore(count?: number): Excel.Range;Parámetros
- count
-
number
Opcional. El número de columnas que se va a incluir en el rango resultante. En general, use un número positivo para crear un intervalo fuera del intervalo actual. También puede usar un número negativo para crear un intervalo dentro del intervalo actual. El valor predeterminado es 1.
Devoluciones
Comentarios
getEntireColumn()
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);
});
getEntireRow()
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);
});
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
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
});
getIntersectionOrNullObject(anotherRange)
Obtiene el objeto de rango que representa la intersección rectangular de los rangos especificados. Si no se encuentra ninguna intersección, este método devuelve un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).
getIntersectionOrNullObject(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
Comentarios
[ Conjunto de API: ExcelApi 1.4 ]
Ejemplos
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const salesTable = sheet.tables.getItem("SalesTable");
const dataRange = salesTable.getDataBodyRange();
// We want the most recent quarter that has data, so
// exclude quarters without data and get the last of
// the remaining columns.
const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
const currentQuarterRange = usedDataRange.getLastColumn();
// Asian and European teams have separate contests.
const asianSalesRange = sheet.getRange("A2:E4");
const europeanSalesRange = sheet.getRange("A5:E7");
// The data for each chart is the intersection of the
// current quarter column and the rows for the continent.
const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);
// Must sync before you can test the output of *OrNullObject
// method/property.
await context.sync();
if (asianContestRange.isNullObject) {
// See the declaration of this function for how to
// test this code path.
reportMissingData("Asian");
} else {
createContinentChart(
sheet,
"Asian",
asianContestRange,
"A9",
"F24"
);
}
if (europeanContestRange.isNullObject) {
// See the declaration of this function for how to
// test this code path.
reportMissingData("European");
} else {
createContinentChart(
sheet,
"European",
europeanContestRange,
"A25",
"F40"
);
}
await context.sync();
});
getLastCell()
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
});
getLastColumn()
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
});
getLastRow()
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
});
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
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
});
getResizedRange(deltaRows, deltaColumns)
Obtiene un Range objeto similar al objeto actual Range , pero con su esquina inferior derecha expandida (o contratada) por algún número de filas y columnas.
getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;Parámetros
- deltaRows
-
number
El número de filas en el que se va a expandir la esquina inferior derecha, con respecto al intervalo actual. Use un número positivo para expandir el intervalo, o un número negativo para reducirlo.
- deltaColumns
-
number
Número de columnas por las que se va a expandir la esquina inferior derecha, en relación con el intervalo actual. Use un número positivo para expandir el intervalo, o un número negativo para reducirlo.
Devoluciones
Comentarios
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
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
});
getRowsAbove(count)
Obtiene un número determinado de filas por encima del objeto actual Range .
getRowsAbove(count?: number): Excel.Range;Parámetros
- count
-
number
Opcional. El número de filas que se va a incluir en el intervalo resultante. En general, use un número positivo para crear un intervalo fuera del intervalo actual. También puede usar un número negativo para crear un intervalo dentro del intervalo actual. El valor predeterminado es 1.
Devoluciones
Comentarios
getRowsBelow(count)
Obtiene un número determinado de filas por debajo del objeto actual Range .
getRowsBelow(count?: number): Excel.Range;Parámetros
- count
-
number
Opcional. El número de filas que se va a incluir en el intervalo resultante. En general, use un número positivo para crear un intervalo fuera del intervalo actual. También puede usar un número negativo para crear un intervalo dentro del intervalo actual. El valor predeterminado es 1.
Devoluciones
Comentarios
getUsedRange(valuesOnly)
Devuelve el intervalo usado del objeto de rango especificado. Si no hay celdas usadas dentro del rango, esta función producirá un ItemNotFound error.
getUsedRange(valuesOnly?: boolean): Excel.Range;Parámetros
- valuesOnly
-
boolean
Solo tiene en cuenta las celdas con valores como celdas usadas. [Conjunto de api: ExcelApi 1.2]
Devoluciones
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-relationships.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const salesTable = sheet.tables.getItem("SalesTable");
const dataRange = salesTable.getDataBodyRange();
// We want the most recent quarter that has data, so
// exclude quarters without data and get the last of
// the remaining columns.
const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
const currentQuarterRange = usedDataRange.getLastColumn();
// Asian and European teams have separate contests.
const asianSalesRange = sheet.getRange("A2:E4");
const europeanSalesRange = sheet.getRange("A5:E7");
// The data for each chart is the intersection of the
// current quarter column and the rows for the continent.
const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);
// Must sync before you can test the output of *OrNullObject
// method/property.
await context.sync();
if (asianContestRange.isNullObject) {
// See the declaration of this function for how to
// test this code path.
reportMissingData("Asian");
} else {
createContinentChart(
sheet,
"Asian",
asianContestRange,
"A9",
"F24"
);
}
if (europeanContestRange.isNullObject) {
// See the declaration of this function for how to
// test this code path.
reportMissingData("European");
} else {
createContinentChart(
sheet,
"European",
europeanContestRange,
"A25",
"F40"
);
}
await context.sync();
});
getUsedRangeOrNullObject(valuesOnly)
Devuelve el intervalo usado del objeto de rango especificado. Si no hay celdas usadas dentro del rango, este método devuelve un objeto con su isNullObject propiedad establecida en true. Para obtener más información, vea *OrNullObject methods and properties( Métodos y propiedades de *OrNullObject).
getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;Parámetros
- valuesOnly
-
boolean
Solo tiene en cuenta las celdas con valores como celdas usadas.
Devoluciones
Comentarios
[ Conjunto de API: ExcelApi 1.4 ]
Ejemplos
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/used-range.yaml
await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem("Sample");
const salesTable = sheet.tables.getItem("SalesTable");
const dataRange = salesTable.getDataBodyRange();
// Pass true so only cells with values count as used
const usedDataRange = dataRange.getUsedRangeOrNullObject(
true /* valuesOnly */
);
//Must sync before reading value returned from *OrNullObject method/property.
await context.sync();
if (usedDataRange.isNullObject) {
console.log("Need Data to Make Chart");
console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
} else {
const chart = sheet.charts.add(
Excel.ChartType.columnClustered,
dataRange,
"Columns"
);
chart.setPosition("A15", "F30");
chart.title.text = "Quarterly sales chart";
chart.legend.position = "Right";
chart.legend.format.fill.setSolidColor("white");
chart.dataLabels.format.font.size = 15;
chart.dataLabels.format.font.color = "black";
}
await context.sync();
});
getVisibleView()
Representa las filas visibles del intervalo actual.
getVisibleView(): Excel.RangeView;Devoluciones
Comentarios
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 ahora en blanco.
insert(shift: Excel.InsertShiftDirection): Excel.Range;Parámetros
Especifica hacia dónde se desplazarán las celdas. Vea Excel.InsertShiftDirection para más información.
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();
});
insert(shiftString)
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
- shiftString
-
"Down" | "Right"
Especifica hacia dónde se desplazarán las celdas. Vea Excel.InsertShiftDirection para más información.
Devoluciones
Comentarios
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
Proporciona opciones para las propiedades del objeto que se van a cargar.
Devoluciones
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
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
merge(across)
Combina las celdas del intervalo en una región de la hoja de cálculo.
merge(across?: boolean): void;Parámetros
- across
-
boolean
Opcional. Establézcalo true en celdas de combinación en cada fila del rango especificado como celdas combinadas independientes. El valor predeterminado es false.
Devoluciones
void
Comentarios
[ Conjunto de API: ExcelApi 1.2 ]
Ejemplos
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();
});
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 de API del mismo tipo.
set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;Parámetros
- properties
- Excel.Interfaces.RangeUpdateData
Objeto JavaScript con propiedades estructuradas isomórficamente con las propiedades del objeto al 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, en función de 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()
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 Excel.Range original 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
track()
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 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 de seguimiento cuando se creó el objeto por primera vez.
track(): Excel.Range;Devoluciones
unmerge()
Separa las celdas del intervalo en celdas independientes.
unmerge(): void;Devoluciones
void
Comentarios
[ Conjunto de API: ExcelApi 1.2 ]
Ejemplos
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();
});
untrack()
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();
});
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de