Référence des ressources Excel

Au-delà des fonctions, un environnement peut porter dix types d'artefacts Excel — graphiques, tableaux, boîtes de dialogue, mise en forme, et plus — que l'agent applique en direct depuis la configuration. Cette page couvre les dix, en profondeur pour les trois inédits (graphiques, vues de grille, boîtes de dialogue) et de façon concise pour le reste.

L'onglet Resources de chaque environnement contient plus que des fonctions. Dix types de ressources — Charts, Tables & Pivots, Dialogs, Conditional formatting, Named ranges, Comments, Protections, Data validations, Image inserts et Worksheet events — vous permettent de façonner l'apparence et le comportement d'Excel sans écrire une seule ligne d'Office.js.

Configuration seule, appliquée en direct — pas de manifeste, pas de redéploiement

Les dix sont des ressources passthrough : le tableau de bord stocke la configuration, cette configuration circule sur le même canal de snapshot que vos fonctions, et l'connxl-agent l'applique directement (dessine le graphique, écrit le commentaire, enregistre le gestionnaire d'événement, etc.) plutôt que de l'exécuter comme une fonction. Aucune ne touche au manifeste Office, donc un changement est en direct la prochaine fois qu'un utilisateur ouvre le volet Office — sans redéploiement, sans nouveau sideload. Enregistrez une version en direct de l'environnement pour publier, exactement comme un changement de fonction.

Charts

Un graphique Excel dessiné sur la sortie déversée d'une fonction en forme de matrice (sortie Table, Row ou JSON — voir Référence des fonctions). Recourez à un graphique quand vous voulez la même visualisation qu'un utilisateur construirait à la main à partir d'un déversement, rafraîchie à chaque insertion.

Se configure depuis l'onglet Resources → Charts : choisissez la fonction source, un type de graphique (ColumnClustered, ColumnStacked, BarClustered, BarStacked, Line, LineMarkers, Pie, Doughnut, Area ou XYScatter), et éventuellement un titre, un interrupteur de légende, et des titres d'axe catégorie/valeur.

Field	Type	Description
`series`Optional	`répétable`	Laissez vide pour que l'agent dérive les séries automatiquement à partir de la plage déversée. Ou ajoutez des séries explicites, chacune nommant une colonne `valuesFrom` (et une couleur fixe optionnelle) — pour une source en mode tableau avec des colonnes déclarées, le générateur propose un sélecteur sur les en-têtes réels.

Séries conscientes de la forme

Si la fonction source déclare ses colonnes de sortie, le sélecteur de séries affiche les en-têtes réels (colonnes numériques en premier) et l'aperçu dessine les séries réellement résolues — une série nommant une colonne qui n'existe plus apparaît barrée dans l'aperçu et serait silencieusement écartée par l'agent, ce qui vous permet de repérer la dérive avant de publier.

Dans Excel : ouvrir la ressource depuis la carte intégrée du volet Office déverse la fonction source, puis dessine le graphique sur le résultat comme un véritable objet graphique Excel (pas une image) — l'utilisateur peut ensuite le déplacer, le redimensionner et le restyler comme n'importe quel autre graphique.

Grid views (Tables & PivotTables)

Transforme la sortie déversée d'une fonction matrice en un véritable Table ou PivotTable Excel, au lieu d'un simple déversement de tableau dynamique. C'est l'onglet « Tables & Pivots » de Resources.

Se configure : choisissez la fonction source (en forme de matrice uniquement), puis une liste ordonnée d'Arguments — les valeurs positionnelles passées à la fonction lors du déversement (p. ex. "West", 10) — suivie d'options spécifiques au type :

Field	Type	Description
`kind`Required	`table \| pivot`	Dans quel objet Excel le déversement est enveloppé.
`table.style / table.hasHeaders`Optional	`string / bool`	Type table uniquement — le nom du style de tableau Excel et si la première ligne déversée est une ligne d’en-tête.
`pivot.rows / pivot.columns`Optional	`string[]`	Type pivot uniquement — noms de champs pilotant les hiérarchies de lignes et de colonnes.
`pivot.values`Optional	`{ field, aggregation }[]`	Type pivot uniquement — un ou plusieurs champs de valeur, chacun avec une agrégation : sum, count, average, max, min, product, countNumbers, stdDev ou variance.
`pivot.refreshOnOpen`Optional	`bool`	Type pivot uniquement — retire les données sources à chaque ouverture du classeur.

Quand la fonction source déclare ses colonnes de sortie, les sélecteurs de lignes/colonnes/valeur s'affichent comme des puces sélectionnables sur les en-têtes réels (un champ enregistré devenu obsolète s'affiche comme une puce de danger supprimable) plutôt qu'en texte libre.

Un Table issu d'un déversement est un instantané statique

Envelopper un déversement dans un Table remplace la formule de tableau dynamique sous-jacente par ses valeurs — une contrainte dure d'Office.js, pas une limitation de ConnXL. Il ne se met pas à jour en direct si les données source changent d'elles-mêmes ; réinsérez-le (ou branchez un worksheet event, plus loin sur cette page, pour le réappliquer) pour le rafraîchir.

Dans Excel : cliquer sur la grid view dans le volet Office déverse la fonction source avec ses arguments configurés, puis enveloppe le résultat — un Table via worksheet.tables.add, ou un PivotTable via workbook.pivotTables.add avec la disposition lignes/colonnes/valeurs configurée.

Dialogs

Un lanceur basé sur formulaire pour une fonction qui prend plusieurs paramètres. Plutôt que de demander à un utilisateur de taper =NAMESPACE.MODULE.FN(v1, v2, v3) à la main, une boîte de dialogue ouvre un formulaire étiqueté et compose l'appel à sa place.

Se configure : choisissez une fonction source — seules les fonctions avec des paramètres sont proposées. En choisir une amorce automatiquement la liste des champs de la boîte de dialogue à partir des paramètres de cette fonction, dans l'ordre (clé, libellé, espace réservé optionnel) ; la clé de chaque champ est restreinte à l'un des noms de paramètre propres à la fonction, et seuls les paramètres optionnels en fin de liste peuvent être retirés de la liste des champs — tout le reste est rejeté, aussi bien dans le générateur que par l'API, si bien qu'une boîte de dialogue ne peut jamais dériver hors de la signature de sa fonction.

Une boîte de dialogue ouvre une fenêtre séparée, pas un formulaire en ligne

La boîte de dialogue ne fait pas partie du DOM propre du volet Office. L'ouvrir (depuis la carte Dialogs intégrée du volet Office, ou un bouton du ruban qui y est relié) lance une véritable fenêtre de boîte de dialogue Office séparée via Office.context.ui.displayDialogAsync. Elle affiche un <input> étiqueté par champ configuré. À la soumission, la fenêtre renvoie les valeurs collectées au volet Office (messageParent), qui compose et insère la formule — les arguments dans le même ordre que la liste des champs :

formule composéeexcel

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

Aucune entrée de manifeste n'est nécessaire pour une boîte de dialogue — la fenêtre est servie depuis la même origine que l'hôte de l'agent, ce qui satisfait déjà la règle de même origine de l'API Office Dialog, donc rien à ajouter à <AppDomains> et pas de redéploiement.

Conditional formatting

Des règles de valeur de cellule configurées dans le tableau de bord et appliquées sur la plage déversée d'une fonction matrice — pour mettre en évidence des seuils, des valeurs aberrantes ou des catégories sans qu'un utilisateur configure à la main la boîte de dialogue de mise en forme conditionnelle d'Excel.

Se configure : choisissez la fonction source, puis ajoutez une ou plusieurs règles, chacune un opérateur (greaterThan, lessThan, between, equalTo, notEqualTo, greaterThanOrEqual, lessThanOrEqual) comparé à une borne de formule (deux pour between), avec une couleur de remplissage et/ou de police optionnelle. Les règles s'appliquent dans l'ordre — la première correspondance l'emporte. L'aperçu du générateur est un débogueur de règles : il dérive des valeurs d'exemple à partir des propres bornes numériques de vos règles et teinte chaque cellule d'exemple selon la première règle qu'elle correspond (une borne de formule reste non évaluée, marquée d'un badge ƒ).

Dans Excel : appliqué sur la même plage où se déverse la fonction source, en utilisant les véritables règles de mise en forme conditionnelle par valeur de cellule d'Excel — elle se réévalue à mesure que les valeurs sous-jacentes changent, ce n'est pas une peinture ponctuelle.

Named ranges

Lie un nom défini Excel à la sortie déversée d'une fonction matrice, de sorte que la plage puisse être référencée par son nom — dans d'autres formules, ou via la zone Nom — plutôt que par coordonnées de cellule.

Se configure : choisissez la fonction source, une portée (workbook ou worksheet), et un commentaire optionnel sur le nom défini.

Dans Excel : la fonction source est déversée, puis la plage résultante est nommée comme un véritable nom défini Excel (workbook.names.add ou worksheet.names.add) — utilisable immédiatement dans toute autre formule du classeur.

Comments

Un commentaire de cellule statique (note), ancré à une cellule précise — contrairement aux ressources ci-dessus, un commentaire ne provient pas d'une fonction ; c'est simplement du texte sur une cellule.

Se configure : une adresse cible (éventuellement qualifiée par feuille, p. ex. Sheet1!B2) et le texte du commentaire.

Dans Excel : écrit sur la cellule cible via l'API de commentaires d'Office quand l'agent applique la ressource.

Protections

Verrouille une feuille de calcul tout en laissant disponible un ensemble choisi d'actions — utile pour une feuille de rapport publiée que vous ne voulez pas voir les utilisateurs finaux modifier, tout en leur permettant de la trier ou de la filtrer.

Se configure : une feuille cible (vide s'applique à la feuille active au moment où la ressource est appliquée), et neuf interrupteurs allow-* : mettre en forme les cellules, mettre en forme les colonnes, mettre en forme les lignes, insérer des colonnes, insérer des lignes, supprimer des colonnes, supprimer des lignes, trier, et AutoFilter.

Chaque permission circule explicitement

Les neuf indicateurs sont toujours envoyés à l'agent, pas seulement ceux que vous avez activés — donc une permission décochée est activement verrouillée plutôt que laissée à ce qu'Excel appliquerait par défaut.

Dans Excel : appliqué comme une protection de feuille (WorksheetProtectionOptions d'Excel) avec les permissions choisies laissées ouvertes.

Data validations

Une véritable règle de validation de données Excel, modifiable, sur une plage cible — pas une vérification ponctuelle, mais une contrainte continue sur ce qu'un utilisateur peut saisir dans ces cellules.

Se configure : une adresse cible (une cellule unique ou une plage, éventuellement qualifiée par feuille), et un genre :

Field	Type	Description
`list`Optional	`genre`	Une liste déroulante de valeurs explicites, avec un interrupteur pour la flèche déroulante dans la cellule.
`wholeNumber / decimal / date / textLength`Optional	`genre`	Une règle de comparaison : choisissez un opérateur (between, notBetween, equalTo, notEqualTo, greaterThan, lessThan, greaterThanOrEqualTo, lessThanOrEqualTo) et une ou deux bornes de formule (deux seulement pour les opérateurs de la famille between).
`custom`Optional	`genre`	Une formule de validation arbitraire.

Dans Excel : appliqué via range.dataValidation.rule — l'utilisateur voit la même validation dans la cellule (et la flèche déroulante, pour une list) que s'il l'avait configurée lui-même dans la boîte de dialogue de validation des données d'Excel.

Image inserts

Dépose une image de l'organisation déjà téléversée — depuis la même bibliothèque Assets → Images utilisée ailleurs dans le tableau de bord, partagée entre tous les compléments et environnements de l'organisation — dans la grille de la feuille de calcul, ancrée à une cellule.

Se configure : choisissez une image de l'organisation, une adresse de cellule d'ancrage (son coin supérieur gauche y tombe), et un facteur d'échelle relatif à la taille naturelle de l'image.

Dans Excel : l'agent récupère l'image via le proxy d'images du backend au moment de l'application, et l'insère à la cellule d'ancrage. Si l'image référencée est ensuite supprimée de la bibliothèque Assets, l'insertion est ignorée proprement plutôt que de faire échouer tout le snapshot.

Worksheet events

Enregistre un gestionnaire d'événement de feuille de calcul qui déclenche une action configurée automatiquement — sans qu'un utilisateur ait besoin de cliquer. C'est ce qui rend les autres ressources passthrough « vivantes ».

Se configure : un déclencheur (onChanged ou onSelectionChanged), puis une action :

Reapply resource — nomme un type de cible (chart ou gridView) et un id ; quand le déclencheur se déclenche, l'agent réapplique cette ressource — redessinant le graphique, ou redéversant et réenveloppant la grid view, sur ses données source les plus récentes.
Execute function — nomme un id de fonction ; quand le déclencheur se déclenche, l'agent exécute cette fonction pour ses effets de bord (p. ex. écrire quelque part), pas pour une valeur renvoyée dans une cellule.

Dans Excel : l'agent enregistre le gestionnaire avec worksheet.onChanged ou worksheet.onSelectionChanged d'Office.js à l'ouverture du volet Office. Associez ceci à une grid view (ci-dessus) qui n'a pas de voie de rafraîchissement en direct propre — un événement onChanged est la façon habituelle de garder un Table né d'un déversement synchronisé avec les changements en amont.

Promouvoir des ressources entre environnements

Chaque type de ressource ci-dessus suit la même règle structurelle que les fonctions : il ne peut être créé ou modifié que dans l'environnement source (Development). Tout autre environnement est une cible de promotion — vous amenez un chart, une grid view, un dialog ou n'importe lequel des autres dans un environnement en aval avec Promote, la même action que vous utiliseriez pour une fonction ou une connexion, depuis la page Versions de l'environnement.

Rien ici ne dépend du manifeste

Comme aucune de ces dix ressources ne touche au manifeste Office, les promouvoir ou les modifier est toujours un changement de configuration seule — l'agent de l'environnement récepteur le récupère via son canal de configuration existant, sans redéploiement et sans nouveau sideload, exactement comme une fonction.