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 de Excel 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 lo habilita 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 través de varios tipos de aplicaciones de Office. La funcionalidad limitada para la interacción de Excel en Common API se ha reemplazado por la API de JavaScript de Excel.

Aunque es probable que use la API de JavaScript de Excel para desarrollar la mayor parte de la funcionalidad, también usará objetos en Common API. Por ejemplo:

  • Contexto: El objeto Context representa el entorno de runtime del complemento y proporciona acceso a los objetos clave de la API. Consta de los detalles de configuración del libro como contentLanguage y officeTheme, y también proporciona información sobre el entorno de tiempo de ejecución del complemento, como host y platform. Además, proporciona el método requirements.isSetSupported(), que puede usar para comprobar si el conjunto de un requisito especificado es compatible con la aplicación de Excel donde se ejecuta el complemento.
  • 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.

Ranges

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.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

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

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

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

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

    await 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 con rangos con datos. El formato y los controles de tabla (como filtros) se aplican automáticamente al rango.

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

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.tables.add("B2:E5", true);
    await 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.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let chart = sheet.charts.add(Excel.ChartType.columnStacked, sheet.getRange("B3:C5"));
    chart.top = 100;
    await 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