Modelo de objetos de JavaScript en Excel para Complementos de Office

En este artículo se describe cómo usar la API de JavaScript para Excel para crear complementos de Excel 2016 o versiones posteriores. Introduce los conceptos básicos que son fundamentales para usar la API y proporciona instrucciones para realizar tareas específicas, como leer o escribir en un rango grande, actualizar todas las celdas de un rango, etc.

Importante

Consultar Usar el modelo de API específico de la aplicación para obtener información sobre la naturaleza asincrónica de las API de Excel y cómo funcionan con el libro.

API Office.js para Excel

Un complemento de Excel interactúa con objetos de Excel mediante la API de JavaScript de Office, que incluye dos modelos de objetos de JavaScript:

  • API de JavaScript de Excel: Introducida con Office 2016, la API de JavaScript de Excel proporciona objetos fuertemente tipados que se pueden usar para obtener acceso a hojas de cálculo, rangos, tablas, gráficos, etc.

  • API comunes: Introducida con Office 2013, la API común puede usarse para acceder a características como la interfaz de usuario, los cuadros de diálogo y la configuración del cliente, que son comunes a varios tipos de aplicaciones de Office.

Aunque probablemente usará la API de JavaScript de Excel para desarrollar la mayoría de la funcionalidad en los complementos destinados a Excel 2016 o versiones posteriores, también usará objetos en la API común. Por ejemplo:

  • Contexto: El objeto Context representa el entorno de tiempo de ejecución del complemento y ofrece acceso a objetos clave de la API. Se compone de datos de configuración del libro como contentLanguage y officeTheme, además de proporcionar información sobre el entorno de tiempo de ejecución del complemento como host y platform. Asimismo, proporciona el método requirements.isSetSupported(), que puede utilizar para comprobar si la aplicación Excel en la que se ejecuta el complemento admite o no admite el conjunto de requisitos especificado.
  • Documento: el objeto Document proporciona el método getFileAsync(), que puede usar para descargar el archivo de Excel donde se ejecuta el complemento.

La siguiente imagen ilustra cuándo puede utilizar la API de JavaScript de Excel o las API comunes.

Diferencias entre la API de JS para Excel y las API comunes.

Modelo de objetos específico de Excel

Para comprender las API de Excel, debe comprender cómo se relacionan entre sí los componentes de un libro.

  • Un Libro contiene una o varias Hojas de cálculo.
  • Una Hoja de cálculo contiene colecciones de aquellos objetos de datos presentes en la hoja individual y da acceso a las celdas en los objetos de Rango.
  • Un Rango representa un grupo de celdas adyacentes.
  • Los Rangos se usan para crear y colocar Tablas, Gráficos, Formas y otros objetos de visualización u organización de datos.
  • Los Libros contiene colecciones de algunos de esos objetos de datos (como Tablas) para todo el Libro.

Nota

La API de JavaScript para Excel no tiene un objeto o clase de "Celda". En su lugar, se definen todas las celdas de Excel como objetos Range. Una celda individual en la interfaz de usuario de Excel se traduce en un objeto Range con una celda en la API de JavaScript para Excel. Un solo objeto Range también puede contener varias celdas contiguas. Consulte Trabajar con celdas mediante la API de JavaScript para Excel para obtener más información.

Rangos

Un rango es un grupo de celdas adyacentes en el libro. Normalmente, los complementos usan la notación de estilo A1 (por ejemplo, B3 para la única celda de la columna B y la fila 3 o C2:F4 para las celdas de las columnas de C a F y las filas de 2 a 4) para definir rangos.

Los rangos tienen tres propiedades básicas: values, formulas y format. Estas propiedades obtienen o establecen los valores de celda, las fórmulas que se deben evaluar y el formato visual de las celdas.

Ejemplo de rango

En el siguiente ejemplo se muestra cómo crear registros de ventas. Esta función usa objetos Range para establecer los valores, fórmulas y formatos.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();

    // Create the headers and format them to stand out.
    var headers = [
      ["Product", "Quantity", "Unit Price", "Totals"]
    ];
    var headerRange = sheet.getRange("B2:E2");
    headerRange.values = headers;
    headerRange.format.fill.color = "#4472C4";
    headerRange.format.font.color = "white";

    // Create the product data rows.
    var productData = [
      ["Almonds", 6, 7.5],
      ["Coffee", 20, 34.5],
      ["Chocolate", 10, 9.56],
    ];
    var dataRange = sheet.getRange("B3:D5");
    dataRange.values = productData;

    // Create the formulas to total the amounts sold.
    var totalFormulas = [
      ["=C3 * D3"],
      ["=C4 * D4"],
      ["=C5 * D5"],
      ["=SUM(E3:E5)"]
    ];
    var totalRange = sheet.getRange("E3:E6");
    totalRange.formulas = totalFormulas;
    totalRange.format.font.bold = true;

    // Display the totals as US dollar amounts.
    totalRange.numberFormat = [["$0.00"]];

    return context.sync();
});

Este ejemplo crea los siguientes datos en la hoja de cálculo actual.

Un registro de ventas que muestra filas de valores, una columna de fórmulas y los encabezados con formato.

Para obtener más información, consulte Establecer y obtener valores de rango, texto o fórmulas con la API de JavaScript para Excel.

Gráficos, tablas y otros objetos de datos

Las API de JavaScript de Excel pueden crear y manipular las estructuras y visualizaciones de datos en Excel. Las tablas y los gráficos son dos de los objetos más usados, pero las API son compatibles con tablas dinámicas, formas, imágenes, etc.

Crear una tabla

Cree tablas mediante rangos rellenos de datos. El formato y los controles de tabla (como los filtros) se aplican automáticamente al rango.

El siguiente script crea una tabla con los rangos del ejemplo anterior.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.tables.add("B2:E5", true);
    return context.sync();
});

Al usar este código de ejemplo en la hoja de cálculo con los datos anteriores se crea la siguiente tabla.

Una tabla creada con el registro de ventas anterior.

Si desea obtener más información, vea Trabajar con tablas mediante la API de JavaScript para Excel.

Crear un gráfico

Cree gráficos para visualizar los datos de un rango. Las API permiten decenas de tipos de gráficos, cada uno de los cuales se puede personalizar según sus necesidades.

El siguiente ejemplo crea un gráfico de columnas simple para tres elementos y los coloca 100 píxeles por debajo de la parte superior de la hoja de cálculo.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    var chart = sheet.charts.add(Excel.ChartType.columnStacked, sheet.getRange("B3:C5"));
    chart.top = 100;
    return context.sync();
});

Ejecutar este ejemplo en la hoja de cálculo con la tabla anterior crea el gráfico siguiente.

Un gráfico de columnas que muestra cantidades de tres elementos del registro de ventas anterior.

Si desea obtener más información, vea Trabajar con gráficos mediante la API de JavaScript para Excel.

Vea también