Creare un componente aggiuntivo per Office È diventato uno strumento molto potente per estendere Word, Excel, Outlook, PowerPoint e altre applicazioni. Microsoft 365 senza dover sviluppare i tradizionali componenti aggiuntivi desktop. Questi nuovi componenti aggiuntivi si basano su tecnologie web standard e sull'API JavaScript per Office, consentendo la creazione di esperienze moderne, sicure e facili da implementare in tutta l'organizzazione.
Nelle righe che seguono troverete una guida molto completa su strumenti di sviluppo, tipi di manifest, API disponibili e opzioni di distribuzioneIntegrando la documentazione ufficiale Microsoft. L'idea è che si possa partire da zero per avere un componente aggiuntivo funzionante, comprendendo a cosa serve ogni componente e quali decisioni tecniche bisogna prendere a ogni passaggio.
Che cos'è un componente aggiuntivo moderno di Office e come è strutturato?
Componenti aggiuntivi di Modern Office Si basano sulla piattaforma dei componenti aggiuntivi di Office, comune a Word, Excel, PowerPoint, OneNote, Outlook e Project, su desktop, web e, in alcuni casi, dispositivi mobili. Condividono tutti la stessa architettura di base, composta da due parti chiaramente differenziate.
Il primo pezzo è il manifesto del complementoQuesto file funge da "carta d'identità " del componente aggiuntivo. Dichiara i metadati (ID, nome, versione, lingue), con quali applicazioni di Office può essere utilizzato, quali autorizzazioni necessita, quali comandi aggiunge alla barra multifunzione, quali icone utilizza, dove è ospitata l'applicazione Web e in quali contesti deve essere attivato (ad esempio, in Outlook, solo per messaggi o appuntamenti che soddisfano determinate regole).
Il secondo pezzo è il applicazione web Questa applicazione fornisce l'interfaccia utente e la logica di business. È composta da HTML, CSS e JavaScript (o TypeScript) e viene eseguita all'interno di un contenitore HTML di Office (riquadro attività , componente aggiuntivo di contenuto o finestra di dialogo). Da lì, utilizza la libreria office.js per leggere e scrivere nel documento, chiamare servizi esterni, gestire l'autenticazione, visualizzare finestre di dialogo ed eseguire qualsiasi altra attività tipica di una moderna applicazione web.
Strumenti per la creazione di componenti aggiuntivi di Office
Non esiste un unico modo per avviare un progetto aggiuntivo. Microsoft offre diversi strumenti ufficialiQuesti strumenti si rivolgono a diversi profili utente: da chi preferisce i template di Visual Studio a chi lavora quotidianamente con Node.js e Visual Studio Code. Sono disponibili anche strumenti di terze parti o più specializzati, come gli editor di interfaccia utente per VBA.
Generatore Yeoman per componenti aggiuntivi di Office
Il generatore Yeoman per Office è probabilmente l'opzione più flessibile per gli sviluppatori web. Ti consente di creare progetti basati su Node.js che puoi modificare con Visual Studio Code o il tuo editore preferito. La procedura guidata ti guiderà attraverso una serie di domande per scegliere il tipo di componente aggiuntivo (riquadro attività , componente aggiuntivo di contenuto, funzioni personalizzate, Outlook, ecc.) e l'applicazione di destinazione.
Con questo generatore puoi creare progetti per Excel, OneNote, Outlook, PowerPoint, Project, Word e funzioni Excel personalizzate. Inoltre, consente di scegliere tra uno stack semplice con HTML, CSS e JavaScript/TypeScript oppure un'architettura basata su React, sempre in JavaScript o TypeScript, con l'intera struttura del progetto già pronta.
Visual Studio per progetti Office
Se ti muovi più comodamente in ambienti .NETVisual Studio include modelli specifici per i componenti aggiuntivi di Office. Questi modelli coprono principalmente Excel, Outlook, Word e PowerPoint, creando una soluzione completa che include il manifesto del componente aggiuntivo, l'app Web e, facoltativamente, i progetti backend associati.
Il progetto Visual Studio Si basa anch'esso su HTML, CSS e JavaScript, ma si integra con il classico ecosistema Microsoft.Debug, pubblicazione, creazione di pacchetti, ecc. integrati. È una buona scelta quando si lavora già con soluzioni aziendali in Visual Studio e si desidera mantenere tutto centralizzato nello stesso IDE.
Kit per sviluppatori di Microsoft 365 Agents Toolkit e componenti aggiuntivi di Office
Kit di strumenti per agenti Microsoft 365 È progettato per andare oltre i tradizionali componenti aggiuntivi e creare praticamente qualsiasi tipo di estensione per l'ecosistema Microsoft 365, combinando bot, estensioni di Teams e componenti aggiuntivi. Con questo strumento, è possibile generare progetti di componenti aggiuntivi di Office che si adattano alle più ampie applicazioni di Microsoft 365.
Kit per sviluppatori di componenti aggiuntivi di Office È un'estensione di Visual Studio Code che semplifica notevolmente la vita quotidiana. Dall'interno di VS Code, è possibile creare nuovi progetti aggiuntivi, caricare esempi di codice pronti per il test e gestire l'intero ciclo di vita dello sviluppo senza uscire dall'editor. L'estensione è progettata per funzionare sia con manifesti unificati che con manifesti dedicati ai soli componenti aggiuntivi.
Il manifesto: il cuore della configurazione del componente aggiuntivo
Ogni componente aggiuntivo di Office è descritto da un file manifest Questo indica alle applicazioni come caricarlo, quali opzioni di interfaccia esporre e quali autorizzazioni richiedere. Esistono due modelli di manifesto principali e la scelta tra questi determina come integrare il componente aggiuntivo con altre estensioni di Microsoft 365.
Tipi di manifesto: solo supplemento e manifesto unificato
- Manifesto del solo complemento. È il formato classico per i componenti aggiuntivi di Office in Excel, OneNote, Outlook, PowerPoint, Project e Word. È scritto in XML e si concentra esclusivamente sulla descrizione del componente aggiuntivo, senza interferire con altri tipi di applicazioni.
- Manifesto unificato per Microsoft 365. L'evoluzione del modello manifest in formato JSON, storicamente utilizzato nelle applicazioni Teams. Questo formato consente di raggruppare diversi tipi di estensioni di Microsoft 365 (componenti aggiuntivi di Office, estensioni di Teams, ecc.) in un'unica applicazione.
La logica di configurazione è simile in entrambi i casiÈ possibile definire un identificatore univoco (solitamente un GUID), la versione, il nome visualizzato, la descrizione, le lingue supportate, le icone, i tipi di autorizzazione (ad esempio, lettura o lettura/scrittura di documenti) e la struttura dell'interfaccia (schede, gruppi e pulsanti della barra multifunzione). È inoltre possibile specificare l'URL di avvio dell'applicazione web e qualsiasi impostazione aggiuntiva, come le scorciatoie da tastiera in Excel o Word, le regole di attivazione in Outlook o le dimensioni dei pannelli e dei componenti aggiuntivi di contenuto.
Elementi chiave dichiarati nel manifesto
Aggiunta metadati di baseIl manifesto deve descrivere dettagliatamente come il componente aggiuntivo si integra nell'esperienza di Office. Ciò include immagini di branding e icone dei comandi della barra multifunzione, che devono essere ospitate su un server che consenta la memorizzazione nella cache (intestazioni HTTP con Cache-Control: no-cache o simili per la produzione).
Un altro aspetto critico è sicurezzaTutti gli URL che puntano all'applicazione web o alle risorse del componente aggiuntivo devono utilizzare HTTPS. Sebbene alcuni scenari di sviluppo consentano certificati HTTP o autofirmati, se si desidera eseguire il componente aggiuntivo in Office sul Web o pubblicarlo su Microsoft Marketplace, SSL è obbligatorio per evitare avvisi di contenuto misto e garantire la protezione dei dati in transito.
Se si prevede di distribuire il componente aggiuntivo tramite Microsoft Marketplace, il manifesto deve includere: Oltre al GUID univoco, un URL di supporto tecnico accessibile e valido. Microsoft applica una serie di linee guida di convalida in cui vengono esaminati la coerenza dei dati del manifesto, il comportamento del componente aggiuntivo e la conformità ai requisiti di sicurezza e di esperienza utente.
Domini e origini consentiti per Office.js
Il manifesto controlla anche quali domini possono essere esplorati all'interno del pannello del pluginIn Office sul Web e nel nuovo Outlook per Windows, il riquadro attività può caricare quasi qualsiasi URL. Tuttavia, nelle applicazioni desktop, il comportamento è più restrittivo: se il componente aggiuntivo tenta di accedere a un dominio diverso da quello della home page, l'URL si apre all'esterno dell'applicazione, in una finestra separata del browser.
Per evitare quel salto esterno sul desktopÈ possibile elencare esplicitamente ogni dominio aggiuntivo che si desidera visualizzare nella finestra del componente aggiuntivo nel manifesto. Se la destinazione è elencata, verrà aperta nel pannello sia in Office desktop che in Office sul Web; in caso contrario, su desktop, verrà aperta in un browser esterno.
Interazione con i documenti tramite l'API JavaScript di Office
L'applicazione Web del componente aggiuntivo comunica con il documento di Office. (o con il messaggio nel caso di Outlook) tramite la libreria API JavaScript di Office, accessibile tramite il CDN ufficiale di Microsoft all'indirizzo https://appsforoffice.microsoft.com/lib/1/hosted/office.jsBasta fare riferimento a questo script nella sezione <head> dalla pagina per poter utilizzare i tipi e i metodi disponibili.
Una volta caricata la libreria, avrai accesso a due modelli API complementari:
- API specifiche per applicazione.
- API comuni.
Ogni modello è stato progettato per coprire scenari diversi, anche se possono essere combinati nello stesso accessorio a seconda delle esigenze.
API specifiche dell'applicazione
Le API specifiche dell'applicazione forniscono oggetti fortemente tipizzati Rappresentano entità native della specifica applicazione di Office. Ad esempio, in Excel sono disponibili oggetti per fogli di lavoro, intervalli, tabelle e grafici, che consentono di manipolare i dati in modo strutturato ed efficiente.
Questo modello si basa su operazioni batchÈ possibile concatenare le azioni all'interno di un contesto e, quando si è pronti, sincronizzare le modifiche con Office. Questo metodo di lavoro riduce il numero di passaggi tra il componente aggiuntivo e l'applicazione, migliorando significativamente le prestazioni, soprattutto in Office sul Web.
API comuni per funzionalità condivise
API comuni Si concentrano sulle funzionalità trasversali presenti in diverse applicazioni: elementi dell'interfaccia, finestre di dialogo, impostazioni client, ecc. Questo modello utilizza callback anziché promesse e, per progettazione, ogni chiamata esegue una singola operazione sull'applicazione.
Con le API comuni puoi, ad esempio, visualizzare una finestra di dialogo pop-up, gestire la configurazione di un componente aggiuntivo su host diversi o accedere a determinate funzionalità di Outlook, PowerPoint o Project non ancora coperte da API specifiche dell'applicazione, a seconda del caso d'uso.
Set di requisiti e compatibilità multipiattaforma
La compatibilità API è organizzata in set di requisitiQuesti raggruppano membri API specifici sotto un nome di versione. Esistono set di requisiti specifici per applicazione, come ExcelApi 1.7e altri condivisi, come DialogApi 1.1, che funzionano dove è supportata la funzionalità della finestra di dialogo.
Il componente aggiuntivo può verificare in fase di esecuzione se l'applicazione Office in esecuzione soddisfa i requisiti necessari. Ciò consente di personalizzare l'esperienza o di disabilitare funzionalità avanzate quando l'host non soddisfa i requisiti minimi, evitando così di causare errori imprevisti.
Esplora l'API con Script Lab
Script Lab è un componente aggiuntivo gratuito Funge da banco di prova per l'API JavaScript di Office. Viene installato da Microsoft Marketplace e funziona all'interno di applicazioni come Excel o Word, consentendo di scrivere ed eseguire frammenti di codice in tempo reale sul documento corrente.
All'interno di Script Lab hai accesso a un libreria di esempi pronti all'uso che dimostrano varie capacità APIÈ possibile utilizzare questi frammenti come base per il proprio codice, modificarli e visualizzare immediatamente il risultato nel documento, il che velocizza notevolmente la fase di prototipazione e test delle funzionalità prima di incorporarle nel plugin finale.
Come espandere l'interfaccia utente di Office
Uno dei grandi vantaggi dei componenti aggiuntivi è che consentono integrare la funzionalità direttamente nell'interfaccia di Officein modo che l'utente non abbia la sensazione di "abbandonare" l'applicazione. Questo risultato si ottiene combinando comandi di plugin e contenitori HTML come pannelli di attività , plugin di contenuto e finestre di dialogo.
- Comandi aggiuntivi Vengono utilizzati per aggiungere schede personalizzate, nuovi gruppi e pulsanti o menu aggiuntivi alla barra multifunzione di Office.
- Contenitori HTML (riquadri attività , componenti aggiuntivi di contenuto e finestre di dialogo) fungono da superficie su cui visualizzare l'interfaccia del componente aggiuntivo.
In uno scenario tipico, potresti avere un comando che aggiunge un gruppo con un pulsante "Analizza dati" in Excel; quando viene premuto, si apre un riquadro attività sulla destra con la tua app Web, che analizza l'intervallo selezionato, chiama un servizio di apprendimento automatico e restituisce i risultati evidenziando le celle o creando grafici utilizzando l'API specifica di Excel.
Creare un componente aggiuntivo del riquadro attività con Yeoman (esempio Word)
Per mettere in pratica tutti questi concettiÈ utile vedere come creare un componente aggiuntivo per il riquadro attività in pratica utilizzando il generatore di Yeoman, sia per Word che per Outlook. Sebbene i dettagli dell'interfaccia cambino tra le applicazioni, la struttura del progetto e il flusso di lavoro sono molto simili.
Prerequisiti dell'ambiente di sviluppo
Prima di generare il progettoÈ necessario avere installata l'ultima versione LTS di Node.js, scaricabile dal sito web ufficiale. Una volta installata, installare globalmente Yeoman e il generatore di Office utilizzando il comando npm install -g yo generator-officeInfine, assicurati di aver collegato Office a un abbonamento a Microsoft 365 che includa Office sul Web, poiché testerai il componente aggiuntivo sia sul desktop che sul browser.
Creazione di un componente aggiuntivo di Word con un riquadro attivitÃ
Il primo passo è decidere il tipo di manifesto che vuoi usare a seconda che tu intenda combinare il tuo componente aggiuntivo con altre estensioni in un'unica app o meno. Una volta presa la decisione, esegui yo office nella directory di lavoro.
Durante l' assistente interattivoAd esempio, è possibile scegliere un tipo di progetto, assegnare un nome come "Componente aggiuntivo di Office" e selezionare Word come applicazione client di destinazione. Al termine, il generatore crea la cartella del progetto, installa le dipendenze di Node e prepara tutto per l'uso.
All'interno della soluzione troverai il file manifest (manifest.json o manifest.xml) nella radice, che definisce la configurazione del plugin; il file ./src/taskpane/taskpane.html con il markup del riquadro attività ; il CSS in ./src/taskpane/taskpane.css; e il codice che richiama l'API di Office in ./src/taskpane/taskpane.ts o .jsa seconda che tu abbia scelto TypeScript o JavaScript.
Per testare il componente aggiuntivo nel Word desktopDevi solo andare alla cartella principale del progetto (cd "My Office Add-in"ed eseguire npm startQuesto comando avvia il server web locale e avvia Word con il componente aggiuntivo già caricato in modalità sideload. Se preferisci provarlo in Word sul web, puoi usare un comando come questo: npm run start -- web --document {url}, sostituendo l'URL con quello di un documento archiviato in OneDrive o SharePoint.
Server di sviluppo e gestione delle dipendenze
Durante lo sviluppo è comune che npm install Potrebbe non funzionare durante il passaggio automatico eseguito da Yeoman, soprattutto in caso di conflitti con le versioni delle dipendenze. In questi casi, è sufficiente accedere alla cartella del progetto e avviare npm install manualmente per risolverlo.
Se vengono visualizzati avvisi di dipendenza obsoletiPuoi contare sullo strumento npm-check-updates, installandolo con npm i -g npm-check-updates, in esecuzione ncu -u per aggiornare gli intervalli di versione in package.json e completando il processo con un nuovo npm installMolti di questi avvisi non sono critici, ma è buona norma rivederli periodicamente per mantenere il progetto in buone condizioni.
Per arrestare il server di sviluppo e disinstallare il plugin in modalità sideloading, puoi eseguire npm stop nella directory principale. Se in precedenza hai caricato manualmente il componente aggiuntivo (ad esempio, caricando il manifesto su Office sul Web), dovrai rimuoverlo manualmente anche dall'interfaccia di amministrazione corrispondente.
Dalla struttura di base di un componente aggiuntivo e degli strumenti di sviluppo (Yeoman, Visual Studio, Agents Toolkit, Script Lab) al ruolo del manifesto, delle API JavaScript, dei controlli di sicurezza e delle opzioni di distribuzione (locale, Marketplace, distribuzione centralizzata o tramite provider come Qlik), hai un mappa abbastanza completa per decidere di che tipo di componente aggiuntivo hai bisogno, come realizzarlo e come metterlo nelle mani dei tuoi utenti senza sorprese tecniche.