Uso de objetos de JavaScript integrados en scripts de Office
JavaScript proporciona varios objetos integrados que puede usar en los scripts de Office, independientemente de si está creando scripts en JavaScript o TypeScript (un superconjunto de JavaScript). En este artículo se describe cómo usar algunos de los objetos de JavaScript integrados en scripts de Office para Excel.
Nota:
Para obtener una lista completa de todos los objetos JavaScript integrados, consulte el artículo Objetos integrados estándar de Mozilla.
Matriz
El objeto Array proporciona una manera estandarizada de trabajar con matrices en el script. Aunque las matrices son construcciones estándar de JavaScript, se relacionan con scripts de Office de dos maneras principales: intervalos y colecciones.
Trabajar con intervalos
Los rangos contienen varias matrices bidimensionales que se asignan directamente a las celdas de ese rango. Estas matrices contienen información específica sobre cada celda de ese rango. Por ejemplo, Range.getValues devuelve todos los valores de esas celdas (con las filas y columnas de la asignación de matriz bidimensional a las filas y columnas de esa subsección de hoja de cálculo). Range.getFormulas y Range.getNumberFormats son otros métodos usados con frecuencia que devuelven matrices como Range.getValues.
El siguiente script busca en el intervalo A1:D4 cualquier formato de número que contenga un "$". El script establece el color de relleno de esas celdas en "amarillo".
function main(workbook: ExcelScript.Workbook) {
// Get the range From A1 to D4.
let range = workbook.getActiveWorksheet().getRange("A1:D4");
// Get the number formats for each cell in the range.
let rangeNumberFormats = range.getNumberFormats();
// Iterate through the arrays of rows and columns corresponding to those in the range.
rangeNumberFormats.forEach((rowItem, rowIndex) => {
rangeNumberFormats[rowIndex].forEach((columnItem, columnIndex) => {
// Treat the numberFormat as a string so we can do text comparisons.
let columnItemText = columnItem as string;
if (columnItemText.indexOf("$") >= 0) {
// Set the cell's fill to yellow.
range.getCell(rowIndex, columnIndex).getFormat().getFill().setColor("yellow");
}
});
});
}
Trabajar con colecciones
Muchos objetos de Excel están contenidos en una colección. La colección se administra mediante la API de scripts de Office y se expone como una matriz. Por ejemplo, todas las formas de una hoja de cálculo están contenidas en un Shape[] objeto devuelto por el Worksheet.getShapes método . Puede usar esta matriz para leer valores de la colección o puede acceder a objetos específicos desde los métodos del get* objeto primario.
Nota:
No agregue ni quite manualmente objetos de estas matrices de colecciones. Use los add métodos de los objetos primarios y los delete métodos de los objetos de tipo colección. Por ejemplo, agregue una tabla a una hoja de cálculo con el Worksheet.addTable método y quite using TableTable.delete.
El siguiente script registra el tipo de cada forma de la hoja de cálculo actual.
function main(workbook: ExcelScript.Workbook) {
// Get the current worksheet.
let selectedSheet = workbook.getActiveWorksheet();
// Get the shapes in this worksheet.
let shapes = selectedSheet.getShapes();
// Log the type of every shape in the collection.
shapes.forEach((shape) => {
console.log(shape.getType());
});
}
El siguiente script elimina la forma más antigua de la hoja de cálculo actual.
function main(workbook: ExcelScript.Workbook) {
// Get the current worksheet.
let selectedSheet = workbook.getActiveWorksheet();
// Get the first (oldest) shape in the worksheet.
// Note that this script will thrown an error if there are no shapes.
let shape = selectedSheet.getShapes()[0];
// Remove the shape from the worksheet.
shape.delete();
}
Fecha
El objeto Date proporciona una manera estandarizada de trabajar con fechas en el script. Date.now() genera un objeto con la fecha y hora actuales, lo que resulta útil al agregar marcas de tiempo a la entrada de datos del script.
El siguiente script agrega la fecha actual a la hoja de cálculo. Tenga en cuenta que, mediante el toLocaleDateString método , Excel reconoce el valor como una fecha y cambia automáticamente el formato numérico de la celda.
function main(workbook: ExcelScript.Workbook) {
// Get the range for cell A1.
let range = workbook.getActiveWorksheet().getRange("A1");
// Get the current date and time.
let date = new Date(Date.now());
// Set the value at A1 to the current date, using a localized string.
range.setValue(date.toLocaleDateString());
}
La sección Trabajar con fechas de los ejemplos tiene más scripts relacionados con fechas.
Matemáticas
El objeto Math proporciona métodos y constantes para operaciones matemáticas comunes. Proporcionan muchas funciones también disponibles en Excel, sin necesidad de usar el motor de cálculo del libro. Esto evita que el script tenga que consultar el libro, lo que mejora el rendimiento.
El siguiente script usa Math.min para buscar y registrar el número más pequeño en el intervalo A1:D4 . Tenga en cuenta que en este ejemplo se supone que todo el intervalo contiene solo números, no cadenas.
function main(workbook: ExcelScript.Workbook) {
// Get the range from A1 to D4.
let comparisonRange = workbook.getActiveWorksheet().getRange("A1:D4");
// Load the range's values.
let comparisonRangeValues = comparisonRange.getValues();
// Set the minimum values as the first value.
let minimum = comparisonRangeValues[0][0];
// Iterate over each row looking for the smallest value.
comparisonRangeValues.forEach((rowItem, rowIndex) => {
// Iterate over each column looking for the smallest value.
comparisonRangeValues[rowIndex].forEach((columnItem) => {
// Use `Math.min` to set the smallest value as either the current cell's value or the previous minimum.
minimum = Math.min(minimum, columnItem);
});
});
console.log(minimum);
}
No se admite el uso de bibliotecas de JavaScript externas
Los scripts de Office no admiten el uso de bibliotecas externas de terceros. El script solo puede usar los objetos de JavaScript integrados y las API de scripts de Office.