Conceptos básicos del modelo de objetos de Excel para complementos de Office

En este artículo se explica cómo encajan los libros, las hojas de cálculo, los rangos, las tablas y los gráficos en el modelo de objetos de JavaScript de Excel.

En la mayoría de los complementos de Excel, comienza con un libro, se mueve a una hoja de cálculo, se trabaja con uno o varios rangos y, a continuación, se crean objetos de nivel superior, como tablas o gráficos. Comprender que el flujo le ayuda a desarrollar el complemento más rápido y a elegir la API adecuada para cada tarea.

Comience con los objetos de Excel que más usará.

Los complementos de Excel suelen empezar con el libro y trabajar con elementos más específicos de la hoja de cálculo. A continuación se muestra cómo conceptualizar algunos de los objetos de JavaScript.

• un Workbook objeto contiene uno o varios Worksheet objetos.
• contiene Worksheet celdas y objetos de nivel de hoja.
• representa Range una celda o un bloque de celdas contiguas.
• Range los objetos son el punto de partida para escribir valores, fórmulas y formatos.
• Table Los objetos y Chart suelen crearse a partir de datos que ya existen en un intervalo.

Si no está familiarizado con el modelo de objetos de Excel, comience con estas tareas comunes:

• Establecimiento o obtención de valores de rango, texto y fórmulas de Excel
• Creación, lectura y administración de tablas con la API de JavaScript de Excel
• Administración de hojas de cálculo de Excel con la API de JavaScript

Trabajar con intervalos

Un rango es un grupo de celdas contiguas en un libro. Los complementos suelen usar la notación de estilo A1 para definir rangos, como B3 para una sola celda o C2:F4 para un bloque rectangular de celdas.

Los intervalos exponen tres propiedades principales que la mayoría de los complementos usan de inmediato:

• values para leer o escribir valores de celda.
• formulas para leer o escribir fórmulas.
• format para cambiar el formato visual.

Compilación de una hoja de cálculo de ventas sencilla con rangos

En el ejemplo siguiente se crea un pequeño informe de ventas. Escribe una fila de encabezado y filas de producto, calcula los totales con fórmulas y da formato a los totales como moneda. Use este patrón cuando el complemento necesite rellenar y dar formato a un bloque de celdas en una sola operación.

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

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

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

    // Create the formulas to total the amounts sold.
    const totalFormulas = [
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    const 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();
});

En este ejemplo se crean los siguientes datos en la hoja de cálculo activa.

Para obtener más información, vea Establecer u obtener valores de rango de Excel, texto y fórmulas.

Convertir rangos en tablas y gráficos

Una vez que el complemento escribe datos en un intervalo, a menudo convierte esos datos en un objeto más enriquecido. Las tablas facilitan la ordenación y el filtrado de los datos. Los gráficos facilitan la comprensión de los patrones de un vistazo.

La API de JavaScript de Excel también admite otros objetos de libro, como tablas dinámicas, formas e imágenes. Sin embargo, las tablas y los gráficos son el paso siguiente más común después de crear un intervalo.

Creación de una tabla a partir de un intervalo

Cree una tabla cuando los usuarios necesiten filtrado integrado, referencias estructuradas y formato de tabla. En el ejemplo siguiente se convierten los datos de ventas del ejemplo anterior en una tabla.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.tables.add("B2:E5", true);
    await context.sync();
});

Al ejecutar este código en la hoja de cálculo con los datos anteriores, Excel crea la tabla siguiente.

Para obtener más información, consulte Creación, lectura y administración de tablas con la API de JavaScript de Excel.

Creación de un gráfico a partir de un intervalo

Cree un gráfico cuando desee que los usuarios interpreten visualmente los datos del libro. En el ejemplo siguiente se crea un gráfico de columnas apiladas a partir de los datos de elementos y cantidades y, a continuación, se coloca el gráfico 100 píxeles debajo de la parte superior de la hoja de cálculo.

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

Al ejecutar este código en la hoja de cálculo con la tabla anterior, Excel crea el siguiente gráfico.

Para obtener más información, consulte Creación y personalización de gráficos con la API de JavaScript de Excel.

Saber cuándo usar las API comunes

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.

Usará la API de JavaScript de Excel para la mayoría de las operaciones de libro, pero también usará objetos en Common API para la información en tiempo de ejecución del complemento y el acceso a archivos.

• Contexto: use el Context objeto para inspeccionar el tiempo de ejecución del complemento, incluidos contentLanguage, officeTheme, hosty platform. También puede llamar requirements.isSetSupported() a para comprobar si Excel admite un conjunto de requisitos específico.
• Documento: use el Document objeto y su getFileAsync() método cuando necesite descargar el archivo de libro en el que se ejecuta el complemento.

En la imagen siguiente se muestra cuándo puede usar la API de JavaScript de Excel en lugar de las API comunes.

Vea también

• Compilación de complementos de Excel para Excel
• Compilar el primer complemento de Excel
• Administración de hojas de cálculo de Excel con la API de JavaScript
• Establecimiento o obtención de valores de rango, texto y fórmulas de Excel
• Creación, lectura y administración de tablas con la API de JavaScript de Excel
• Ejemplos de código de complementos de Excel
• Optimización del rendimiento de la API de JavaScript de Excel
• Información general de la API de JavaScript de Excel