Referencia de recursos de Excel

Además de las funciones, un entorno puede llevar diez tipos de artefacto de Excel — gráficos, tablas, diálogos, formato y más — que el agent aplica en vivo desde la configuración. Esta página cubre los diez, en profundidad para los tres novedosos (gráficos, vistas de cuadrícula, diálogos) y de forma concisa para el resto.

La pestaña Resources de cada entorno guarda más que funciones. Diez tipos de recurso — Charts, Tables & Pivots, Dialogs, Conditional formatting, Named ranges, Comments, Protections, Data validations, Image inserts y Worksheet events — te dejan dar forma a cómo se ve y se comporta Excel sin escribir una sola línea de Office.js.

Solo configuración, aplicado en vivo — sin manifiesto, sin redeploy

Los diez son recursos passthrough: el panel almacena la configuración, esa configuración viaja por el mismo canal de snapshot que tus funciones, y el connxl-agent la aplica directamente (dibuja el gráfico, escribe el comentario, registra el manejador del evento, etc.) en vez de ejecutarla como una función. Ninguno toca el manifiesto de Office, así que un cambio queda en vivo la próxima vez que un usuario abre el panel de tareas — sin redeploy, sin volver a hacer sideload. Guarda una versión en vivo del entorno para publicar, igual que un cambio de función.

Charts

Un gráfico de Excel dibujado sobre la salida derramada de una función con forma de matriz (salida Table, Row o JSON — ver Referencia de funciones). Recurre a un gráfico cuando quieras la misma visualización que un usuario construiría a mano a partir de un derrame, refrescada en cada inserción.

Se configura desde la pestaña Resources → Charts: elige la función de origen, un tipo de gráfico (ColumnClustered, ColumnStacked, BarClustered, BarStacked, Line, LineMarkers, Pie, Doughnut, Area o XYScatter), y opcionalmente un título, un interruptor de leyenda y títulos de eje de categoría/valor.

Field	Type	Description
`series`Optional	`repetible`	Déjalo vacío para que el agent derive las series automáticamente a partir del rango derramado. O añade series explícitas, cada una nombrando una columna `valuesFrom` (y un color fijo opcional) — para una fuente en modo tabla con columnas declaradas, el constructor ofrece un selector sobre los encabezados reales.

Series conscientes de la forma

Si la función de origen declara sus columnas de salida, el selector de series muestra los encabezados reales (columnas numéricas primero) y la vista previa dibuja las series realmente resueltas — una serie que nombra una columna que ya no existe aparece tachada en la vista previa y el agent la descartaría silenciosamente, así que detectas el desajuste antes de publicar.

En Excel: al abrir el recurso desde el panel integrado del panel de tareas se derrama la función de origen y luego se dibuja el gráfico sobre el resultado como un objeto de gráfico real de Excel (no una imagen) — el usuario puede moverlo, redimensionarlo y restilizarlo después como cualquier otro gráfico.

Grid views (Tables & PivotTables)

Convierte la salida derramada de una función matriz en una Table o PivotTable real de Excel, en lugar de un simple derrame de matriz dinámica. Es la pestaña "Tables & Pivots" de Resources.

Se configura: elige la función de origen (solo con forma de matriz), luego una lista ordenada de Arguments — los valores posicionales que se pasan a la función al derramarla (p. ej. "West", 10) — seguida de opciones específicas del tipo:

Field	Type	Description
`kind`Required	`table \| pivot`	En qué objeto de Excel se envuelve el derrame.
`table.style / table.hasHeaders`Optional	`string / bool`	Solo tipo table — el nombre del estilo de tabla de Excel y si la primera fila derramada es una fila de encabezado.
`pivot.rows / pivot.columns`Optional	`string[]`	Solo tipo pivot — nombres de campo que impulsan las jerarquías de filas y columnas.
`pivot.values`Optional	`{ field, aggregation }[]`	Solo tipo pivot — uno o más campos de valor, cada uno con una agregación: sum, count, average, max, min, product, countNumbers, stdDev o variance.
`pivot.refreshOnOpen`Optional	`bool`	Solo tipo pivot — vuelve a extraer los datos de origen cada vez que se abre el libro.

Cuando la función de origen declara sus columnas de salida, los selectores de filas/columnas/valor se renderizan como chips seleccionables sobre los encabezados reales (un campo guardado y ya obsoleto se muestra como un chip de peligro eliminable) en vez de texto libre.

Una Table a partir de un derrame es una instantánea estática

Envolver un derrame en una Table sustituye la fórmula de matriz dinámica subyacente por sus valores — una restricción dura de Office.js, no una limitación de ConnXL. No se actualiza en vivo si los datos de origen cambian por sí solos; vuelve a insertarla (o conecta un worksheet event, más adelante en esta página, para reaplicarla) para refrescarla.

En Excel: al hacer clic en la vista de cuadrícula en el panel de tareas se derrama la función de origen con sus argumentos configurados y luego se envuelve el resultado — una Table vía worksheet.tables.add, o una PivotTable vía workbook.pivotTables.add con la disposición de filas/columnas/valores configurada.

Dialogs

Un lanzador basado en formulario para una función que recibe varios parámetros. En vez de pedirle a un usuario que escriba =NAMESPACE.MODULE.FN(v1, v2, v3) a mano, un diálogo abre un formulario con etiquetas y compone la llamada por él.

Se configura: elige una función de origen — solo se ofrecen funciones con parámetros. Elegir una autogenera la lista de campos del diálogo a partir de los parámetros de esa función, en orden (clave, etiqueta, marcador de posición opcional); la clave de cada campo está restringida a uno de los propios nombres de parámetro de la función, y solo los parámetros opcionales al final pueden eliminarse de la lista de campos — cualquier otra cosa se rechaza, tanto en el constructor como en la API, así que un diálogo nunca puede desincronizarse de la firma de su función.

Un diálogo abre una ventana separada, no un formulario en línea

El diálogo no forma parte del DOM propio del panel de tareas. Al abrirlo (desde la tarjeta integrada de Dialogs del panel de tareas, o un botón de la cinta conectado a él) se lanza una ventana de diálogo de Office genuinamente separada vía Office.context.ui.displayDialogAsync. Renderiza un <input> con etiqueta por cada campo configurado. Al enviar, la ventana devuelve los valores recogidos al panel de tareas (messageParent), que compone e inserta la fórmula — argumentos en el mismo orden que la lista de campos:

fórmula compuestaexcel

=NAMESPACE.MODULE.FN(v1, v2, v3)

Un diálogo no necesita ninguna entrada en el manifiesto — la ventana se sirve desde el mismo origen que el host del agent, lo que ya satisface la regla de mismo origen de la Office Dialog API, así que no hay nada que añadir a <AppDomains> ni redeploy.

Conditional formatting

Reglas de valor de celda configuradas en el panel y aplicadas sobre el rango derramado de una función matriz — resalta umbrales, valores atípicos o categorías sin que un usuario configure a mano el diálogo de formato condicional de Excel.

Se configura: elige la función de origen, luego añade una o más reglas, cada una un operador (greaterThan, lessThan, between, equalTo, notEqualTo, greaterThanOrEqual, lessThanOrEqual) contra un límite de fórmula (dos para between), con un color de relleno y/o de fuente opcionales. Las reglas se aplican en orden — gana la primera coincidencia. La vista previa del constructor es un depurador de reglas: deriva valores de muestra a partir de los propios límites numéricos de tus reglas y tiñe cada celda de muestra según la primera regla que coincide (un límite de fórmula queda sin evaluar, marcado con una insignia ƒ).

En Excel: se aplica sobre el mismo rango en el que se derrama la función de origen, usando las reglas de formato condicional por valor de celda reales de Excel — se reevalúa según cambian los valores subyacentes, no es un pintado de una sola vez.

Named ranges

Vincula un nombre definido de Excel a la salida derramada de una función matriz, de modo que el rango pueda referenciarse por nombre — en otras fórmulas, o vía el Cuadro de nombres — en lugar de por coordenadas de celda.

Se configura: elige la función de origen, un ámbito (workbook o worksheet), y un comentario opcional sobre el nombre definido.

En Excel: se derrama la función de origen y luego el rango resultante se nombra como un nombre definido real de Excel (workbook.names.add o worksheet.names.add) — utilizable de inmediato en cualquier otra fórmula del libro.

Comments

Un comentario de celda estático (nota), anclado a una celda concreta — a diferencia de los recursos anteriores, un comentario no proviene de una función; es solo texto sobre una celda.

Se configura: una dirección de destino (opcionalmente calificada por hoja, p. ej. Sheet1!B2) y el texto del comentario.

En Excel: se escribe sobre la celda de destino a través de la API de comentarios de Office cuando el agent aplica el recurso.

Protections

Bloquea una hoja de cálculo dejando disponible un conjunto elegido de acciones — útil para una hoja de informe publicada que no quieres que los usuarios finales editen, mientras aún les permites ordenarla o filtrarla.

Se configura: una hoja de destino (en blanco se aplica a la hoja que esté activa cuando se aplique el recurso), y nueve interruptores allow-*: formatear celdas, formatear columnas, formatear filas, insertar columnas, insertar filas, eliminar columnas, eliminar filas, ordenar y AutoFilter.

Cada permiso viaja explícitamente

Los nueve indicadores se envían siempre al agent, no solo los que activaste — así que un permiso desmarcado queda activamente bloqueado en vez de dejarse en lo que Excel pondría por defecto.

En Excel: se aplica como una protección de hoja (WorksheetProtectionOptions de Excel) con los permisos que elegiste dejados abiertos.

Data validations

Una regla de validación de datos de Excel real y editable sobre un rango de destino — no una comprobación de una sola vez, sino una restricción continua sobre lo que un usuario puede escribir en esas celdas.

Se configura: una dirección de destino (una sola celda o un rango, opcionalmente calificada por hoja), y un tipo:

Field	Type	Description
`list`Optional	`kind`	Una lista desplegable de valores explícitos, con un interruptor para la flecha desplegable en la celda.
`wholeNumber / decimal / date / textLength`Optional	`kind`	Una regla de comparación: elige un operador (between, notBetween, equalTo, notEqualTo, greaterThan, lessThan, greaterThanOrEqualTo, lessThanOrEqualTo) y uno o dos límites de fórmula (dos solo para los operadores de la familia between).
`custom`Optional	`kind`	Una fórmula de validación arbitraria.

En Excel: se aplica vía range.dataValidation.rule — el usuario ve la misma validación en celda (y la flecha desplegable, para una list) que si la hubiera configurado él mismo en el diálogo de validación de datos de Excel.

Image inserts

Coloca una imagen de la organización previamente subida — de la misma biblioteca Assets → Images que se usa en el resto del panel, compartida entre todos los add-ins y entornos de la organización — en la hoja de cálculo, anclada a una celda.

Se configura: elige una imagen de la organización, una dirección de celda de anclaje (su esquina superior izquierda cae ahí), y un factor de escala relativo al tamaño natural de la imagen.

En Excel: el agent obtiene la imagen a través del proxy de imágenes del backend en el momento de aplicar, y la inserta en la celda de anclaje. Si la imagen referenciada se elimina después de la biblioteca Assets, la inserción se omite con elegancia en vez de hacer fallar todo el snapshot.

Worksheet events

Registra un manejador de evento de hoja que dispara una acción configurada automáticamente — sin necesidad de que el usuario haga clic. Esto es lo que hace que los demás recursos passthrough se sientan "en vivo".

Se configura: un disparador (onChanged u onSelectionChanged), luego una acción:

Reapply resource — nombra un tipo de destino (chart o gridView) y un id; cuando se dispara el trigger, el agent reaplica ese recurso — redibujando el gráfico, o volviendo a derramar y envolver la vista de cuadrícula, sobre sus datos de origen más recientes.
Execute function — nombra un id de función; cuando se dispara el trigger, el agent ejecuta esa función por sus efectos secundarios (p. ej. escribir en algún sitio), no por un valor devuelto a una celda.

En Excel: el agent registra el manejador con worksheet.onChanged o worksheet.onSelectionChanged de Office.js cuando se abre el panel de tareas. Combina esto con una grid view (más arriba) que no tenga su propia vía de refresco en vivo — un evento onChanged es la forma habitual de mantener una Table nacida de un derrame sincronizada con los cambios de origen.

Promover recursos entre entornos

Cada tipo de recurso anterior sigue la misma regla estructural que las funciones: solo puede crearse o editarse en el entorno de origen (Development). Cualquier otro entorno es un destino de promoción — llevas un chart, una grid view, un dialog o cualquiera de los demás a un entorno descendiente con Promote, la misma acción que usarías para una función o una conexión, desde la página Versions del entorno.

Nada aquí depende del manifiesto

Como ninguno de estos diez recursos toca el manifiesto de Office, promoverlos o editarlos siempre es un cambio de solo configuración — el agent del entorno receptor lo recoge por su canal de configuración existente, sin redeploy y sin volver a hacer sideload, igual que una función.