Si t'estàs plantejant crear els teus propis complements per a l'Office, segurament ja t'hauràs adonat que no és només “fer una mica de codi” i llest. Un add-in d'Office professional implica entendre la plataforma, l'API de JavaScript, el manifest i les eines de desenvolupament que ofereix Microsoft, a més de saber com tastar-lo, depurar-lo i, per descomptat, com fer que l'experiència d'usuari sigui agradable.
Al llarg d'aquesta guia recorrerem el camí complet, des del primer prototip fins a tenir un complement llest per utilitzar-se en Word, Excel, Outlook i altres aplicacions de Microsoft 365 . Veureu quines eines teniu a la vostra disposició (Yeoman, Visual Studio, Agents Toolkit, el Kit de desenvolupament per a Visual Studio Code), com s'estructura internament un add-in, com es connecta amb l'API d'Office i quins passos seguir per executar-lo i depurar-lo tant en escriptori com a la web.
La plataforma de complements de l'Office: el punt de partida
Tots els add-ins moderns d'Office es construeixen sobre la plataforma de complements d'Office, que és la base comuna per a Word, Excel, Outlook, PowerPoint, OneNote i Project. Això vol dir que la mateixa arquitectura es reutilitza en diferents apps, i que moltes peces del desenvolupament estan estandarditzades.
Abans d'escriure una sola línia de codi, cal tenir clars alguns conceptes clau: quines aplicacions i plataformes són compatibles, quins patrons de programació ofereix l'API de JavaScript d'Office, com es defineix el manifest del complement i de quina manera es dissenya la interfície (panells de tasques, quadres de diàleg, pestanyes personalitzades, etc.). Tot aquest cicle de vida de desenvolupament és el marc mental que utilitzaràs per anar del prototip a l'add-in real.
Com es creen els connectors per a l'Office?
Per arrencar el teu projecte tens diverses rutes oficials, cadascuna pensada per a diferents perfils de desenvolupador, però totes amb un objectiu comú: generar una solució de complement basada en HTML, CSS i JavaScript (o TypeScript) que s'integri amb Office . Les principals opcions que Microsoft ofereix actualment són:
- Generador de Yeoman per a complements d'Office.
- Visual Studio (amb suport específic per a Office Add-ins).
- Microsoft 365 Agents Toolkit.
- Kit de desenvolupament de complements d'Office per a Visual Studio Code.
Generador de Yeoman per a complements d'Office
El generador de Yeoman per a Office és ideal si et mous còmode en entorns web i línia d'ordres. Yeoman crea per tu un projecte Node.js totalment funcional que pots obrir al Visual Studio Code oa qualsevol editor, amb tota l'estructura (manifest, panell de tasques, estils i scripts) llesta per començar a personalitzar.
Amb aquest generador pots crear complements per Excel, OneNote, Outlook, PowerPoint, Project, Word i també projectes de funcions personalitzades d'Excel. A l'hora de configurar el projecte, podeu optar per una plantilla senzilla amb HTML, CSS i JavaScript (o TypeScript) o muntar l'esquelet amb React, escollint igualment entre JavaScript i TypeScript segons el que preferiu.
Per començar a fer servir Yeoman necessites tenir Node.js en la seva versió LTS instal·lada al vostre sistema, i després instal·lar globalment Yeoman i el generador específic d'Office amb npm. Des d'una consola, això es fa llançant:
npm install -g yo generator-office
Un cop configurat l'entorn, només heu d' executar al directori desitjat:
yo office
Durant l'assistent se us demanarà informació com el tipus de projecte (per exemple, Office Add-in Task Pane project), el tipus de script (JavaScript o TypeScript), el nom del complement i l'aplicació d'Office a què s'orienta (Word, Excel, Outlook, etc.). Amb les teves respostes, Yeoman generarà la carpeta del projecte, instal·larà les dependències Node necessàries i deixarà el complement llest per executar-se i provar-se.
Visual Studio per a complements d'Office
Si preferiu una experiència més clàssica i un IDE complet, Visual Studio inclou plantilles per crear complements d'Office per a Excel, Outlook, Word i PowerPoint . En aquest cas, el projecte d'add-in forma part d'una solució de Visual Studio i també es treballa amb HTML, CSS i JavaScript com a tecnologies d'interfície i lògica.
Lavantatge daquest enfocament és que aprofites les eines integrades de Visual Studio per a depuració, administració de projectes, suport de tipus i publicació. Així que, si ja vens del món .NET o sols treballar amb solucions complexes, potser et resulti més còmode aquest camí.
Microsoft 365 Agents Toolkit
Una altra opció especialment interessant si vols anar més enllà de l'add-in tradicional és el Microsoft 365 Agents Toolkit, una caixa d'eines pensada per crear extensions de Microsoft 365 en sentit ampli . Amb aquesta solució no només podeu desenvolupar complements d'Office, sinó gairebé qualsevol tipus d'extensió que interactuï amb els serveis de Microsoft 365.
Amb aquest toolkit és possible generar projectes de complements d'Office amb plantilles i assistents pensats per a integracions avançades , per exemple, escenaris on el teu complement participa de fluxos de treball més amplis o interactua amb altres serveis al núvol dins de l'ecosistema 365.
Kit de desenvolupament de complements d'Office per a Visual Studio Code
Si el teu entorn natural és VS Code, tens a la teva disposició una extensió oficial: el Kit de desenvolupament de complements d'Office, que s'integra directament a la barra d'activitat del Visual Studio Code. Amb aquesta extensió podeu crear nous projectes d'add-ins i carregar exemples ràpidament des del propi editor.
En prémer l'opció corresponent dins de l'extensió, s'obre un assistent que genera el teu projecte de complement, el situa a la carpeta de treball que triïs i l'obre en una finestra nova del Visual Studio Code . Aquesta finestra nova contindrà ja l'estructura del projecte, normalment amb un exemple de panell de tasques bàsic perquè entengueu l'arquitectura.
A partir d'aquí pots revisar fitxers clau com manifest.xml o manifest.json a l'arrel del projecte (on es configura el complement), i els fitxers que defineixen el panell de tasques: ./src/taskpane/taskpane.html per al marcatge, ./src/taskpane/taskpane.css per als estils i ./src/taskpane/taskpane.js per al codi que utilitza l'API d'Office.
Les dues peces fonamentals d'un complement d'Office
Tot add-in d'Office modern es compon, a grans trets, de dos blocs principals: un manifest que declara com s'integra el complement amb l'Office i una aplicació web que defineix la interfície d'usuari i la lògica.
- El manifest de complement descriu la configuració, les metadades, els permisos, els punts d'integració i el comportament de l'add-in.
- L'aplicació web és el conjunt de pàgines HTML, scripts i estils que es mostren en panells de tasques, complements de contingut, quadres de diàleg i altres contenidors dins de l'Office.
L'aplicació web utilitza la API de JavaScript d'Office per interactuar amb el document (o el missatge de correu, en el cas d'Outlook) en què s'està executant el complement. A més, com qualsevol aplicació web, es pot autenticar davant de serveis externs, consumir APIs REST, treballar amb identitat d'usuari i molt més.
El manifest: configuració i capacitats del complement
El manifest defineix pràcticament tot el que l'Office necessita saber sobre la teva solució, així que és un fitxer crític. S'hi inclouen les metadades (ID, nom, descripció, versió, configuració regional predeterminada) i també la relació d'aplicacions de l'Office on es pot carregar el complement.
Al manifest també s'estableixen els permisos que requereix l'add-in, la manera com s'integra amb la interfície d'Office i qualsevol UI personalitzada que afegiu. Això inclou pestanyes específiques a la cinta, botons extra, menús contextuals o ordres de complement.
Un altre aspecte que es controla des del manifest són les imatges utilitzades per a la iconografia del complement, la personalització de marca i les dimensions dels contenidors (per exemple, la mida d'un complement de contingut o l'alçada preferida d'un add-in d'Outlook).
En el cas concret d'Outlook, al manifest podeu definir regles que decideixen quan s'activa el complement segons el context d'un missatge o una cita , i per a aplicacions com Excel i Word és possible declarar mètodes abreujats de teclat específics que disparin funcionalitats de l'add-in.
L'aplicació web i la interacció amb el document de l'Office
La segona part clau és laplicació web, que és la que lusuari veu i amb la qual interactua. Aquesta app s'allotja normalment en un servidor web (pot ser local en desenvolupament, o al núvol en producció) i es renderitza en panells de tasques, quadres de diàleg o regions de contingut dins de l'Office.
Per poder parlar amb el document, l'aplicació web es recolza a l' API de JavaScript d'Office, que s'importa mitjançant un script allotjat al CDN oficial . La ruta típica és:
https://appsforoffice.microsoft.com/lib/1/hosted/office.js
A qualsevol pàgina web del complement on vulguis fer servir l'API, has de fer referència a aquest fitxer dins d'una etiqueta <script> al <head> del document HTML, per exemple:
<head>...<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>...</head>
A partir d´aquí ja pots utilitzar els objectes i mètodes exposats per Office.js per llegir i modificar el contingut, mostrar diàlegs, utilitzar configuracions del client i molt més.
Dos models d'API: específiques d'aplicació i comuns
L'API de JavaScript per a l'Office no és un únic bloc homogeni; s'organitza en dos models diferents amb objectius complementaris. D'una banda, tenim les API específiques de cada aplicació (Excel, Word, etc.) i, de l'altra, les API comunes que funcionen en diversos hosts.
Les API específiques d'aplicació ofereixen objectes fortament tipats que representen entitats pròpies de cada programa (per exemple, fulles, rangs, taules i gràfics a Excel). Aquest model es va introduir amb Office 2016 i utilitza promeses, permetent agrupar diverses operacions en una sola trucada per millorar el rendiment, especialment a Office a la web.
Per la seva banda, les API comuns permeten accedir a parts de l'experiència que són compartides entre diferents aplicacions: elements d'interfície, quadres de diàleg, configuració del client i fins i tot funcionalitats per interactuar amb Outlook, PowerPoint o Project sota un mateix model. En aquest cas, el patró és més clàssic, basat en callbacks, i sol permetre només una operació per sol·licitud. Aquestes API comunes apareixen amb l'Office 2013 i continuen sent rellevants quan vols que el teu complement funcioni en el màxim nombre possible d'aplicacions.
Conjunts de requisits de l'API
Dins del món Office.js, les funcionalitats s'agrupen en conjunts anomenats requirement sets. Un conjunt de requisits és, bàsicament, un grup amb nom de membres de l'API que representen una determinada versió o bloc de capacitats.
Hi ha conjunts orientats a una aplicació concreta, com ara ExcelApi 1.7, que només es pot fer servir a Excel , i altres de caràcter transversal, com DialogApi 1.1, que serveix per manejar quadres de diàleg en qualsevol aplicació que ho suporti.
Des del teu complement pots comprovar aquests conjunts de requisits per determinar si l'aplicació i la plataforma on s'està executant suporten les funcions que necessites . Això és clau quan vols mantenir compatibilitat amb versions diferents de l'Office, tant en escriptori com a web o en altres plataformes.
La compatibilitat dels requirement sets depèn de l'aplicació concreta (Word, Excel, etc.), la versió instal·lada i el sistema operatiu o entorn d'execució. La documentació oficial de Microsoft detalla per a cada combinació quins conjunts i API estan disponibles.
Explorar l'API amb Script Lab
Si voleu experimentar ràpidament sense haver de muntar un projecte complet, teniu a la vostra disposició Script Lab. Script Lab és un complement gratuït per a l'Office que us deixa escriure, executar i provar fragments de codi Office.js directament des d'aplicacions com Excel o Word.
En instal·lar-lo des de Microsoft Marketplace, veuràs que ofereix una biblioteca d'exemples ja preparats per a diferents operacions típiques: manipular rangs, treballar amb taules, mostrar diàlegs, etc. Podeu executar aquests fragments, modificar-los o usar-los com a punt de partida per al codi del vostre propi complement.
Aquesta eina és especialment útil a la fase de prototip, perquè et permet validar ràpidament si una API fa el que necessites, veure com es comporta a Office a la web oa l'escriptori i ajustar la teva lògica abans d'integrar-la al projecte real.
Estendre la interfície d'usuari d'Office amb el vostre complement
Un dels grans atractius dels complements dOffice és la seva capacitat per ampliar la interfície dusuari i enganxar-se a lexperiència nativa de Word, Excel o Outlook . Aquesta extensió de la UI es basa principalment en ordres de complement i en contenidors HTML com a panells de tasques, complements de contingut i quadres de diàleg.
Els ordres de complement et permeten afegir una pestanya personalitzada, botons propis i menús addicionals a la cinta de l'aplicació o fins i tot ampliar els menús contextuals que apareixen en fer clic dret sobre text o objectes (per exemple, cel·les d'Excel). Quan l'usuari prem una de les ordres, es dispara l'acció associada: executar una funció JavaScript, obrir un panell de tasques o llançar un quadre de diàleg.
D'altra banda, els contenidors HTML (panells de tasques, complements de contingut i quadres de diàleg) són “l'espai” on es mostra la interfície de la teva web app. El contingut de cada contenidor procedeix d'una pàgina web allotjada al vostre servidor, que pot fer servir l'API d'Office, trucar a serveis externs, autenticar usuaris i realitzar qualsevol lògica pròpia d'una aplicació web moderna.
A la pràctica pots tenir, per exemple, un botó a la cinta que obre un panell de tasques a la dreta del document, juntament amb un quadre de diàleg emergent i un complement de contingut incrustat directament a la superfície del document. Tot això coordinat mitjançant JavaScript i Office.js.
Crear projectes de complement al Visual Studio Code amb el Kit de desenvolupament
Quan treballes amb el Kit de desenvolupament de complements d'Office al Visual Studio Code, el flux típic és força directe. Primer necessites complir els requisits previs (Node.js, extensió instal·lada, Office connectat a Microsoft 365) i després pots llançar l'assistent de creació de projecte des de la icona del kit a la barra d'activitat.
Després de seleccionar l'opció de crear un nou complement, se us demanarà que escolliu el tipus de projecte, el nom i la carpeta de treball. Un cop confirmades aquestes dades, l'extensió genera automàticament el projecte, instal·la les dependències necessàries i obre la solució en una segona finestra del Visual Studio Code (convé tancar la primera per evitar confusions).
Dins del projecte trobareu sempre alguns fitxers clau: el manifest (manifest.xml o manifest.json) a l'arrel i els fitxers del panell de tasques a la carpeta src/taskpane . L'HTML defineix l'estructura del panell, el full CSS controla l'aspecte visual i el fitxer JavaScript conté les trucades a l'API Office.js que connecten la interfície amb l'aplicació client de l'Office.
Executar i aturar la vista prèvia amb el Kit de desenvolupament
Per provar el complement des de VS Code, es fa servir el propi kit de desenvolupament. Simplement seleccioneu la icona de l'extensió, escolliu l'opció “Vista prèvia del complement d'Office (F5)” i després indiqueu l'aplicació de destinació, per exemple “Excel Desktop (Edge Chromium)” o “Word Desktop (Edge Chromium)”.
L'extensió s'encarrega de verificar que es compleixen els requisits previs, arrencar el servidor web local, registrar el complement i llançar l'aplicació d'escriptori de l'Office amb l'add-in carregat des del vostre entorn local. La primera vegada pot trigar uns minuts, perquè s'instal·len dependències i potser haureu d'acceptar la instal·lació d'un certificat local.
Quan acabis de provar o depurar, és important aturar correctament la vista prèvia des de la pròpia extensió, usant l'opció “Aturar la vista prèvia del complement d'Office” . Això tanca el servidor, elimina el complement del registre i neteja la memòria cau. Després d'això ja podeu tancar l'aplicació d'Office amb tranquil·litat.
Si alguna cosa falla en executar el complement, el més habitual és revisar el terminal integrat de VS Code. Si persisteixen els problemes, es recomana tancar totes les instàncies de l'Office obertes i aturar qualsevol servidor antic del kit de desenvolupament abans de tornar a iniciar la vista prèvia . Per a incidències més complicades hi ha documentació de solució de problemes i, en última instància, sempre pots obrir un issue a GitHub per obtenir ajuda.
Crear un complement amb Yeoman: de “Hola, món” a una mica més complex
Quan fas servir Yeoman per generar un complement, el procés pràctic segueix una seqüència força clara. Després d'instal·lar Node.js, Yeoman i el generador d'Office, executeu l'ordre jo office, responeu unes quantes preguntes i obteniu una carpeta amb un projecte executable.
A l'exemple típic de Word, podries triar un Office Add-in Task Pane project amb JavaScript, anomenar-lo “My Office Add-in” i seleccionar Word com a aplicació client . El generador crearà l'esquelet del connector i executarà un npm install inicial per deixar les dependències preparades.
Per explorar el que s'ha creat, només cal accedir a la carpeta del projecte i obrir els fitxers principals: el manifest (manifest.xml o manifest.json), l'HTML del panell de tasques, el CSS i l'script JavaScript que conté les trucades a Office.js . Normalment l'exemple inclou una acció simple, com ara escriure “Hola, món” al document o canviar l'estil d'un text.
L'execució es fa des de la línia d'ordres. Al directori arrel del projecte pots llançar npm start per iniciar el servidor local i obrir Word amb el complement carregat. Si voleu provar-ho a Office a la web, també hi ha una variant d'ordre que inclou l'URL d'un document a OneDrive o SharePoint:
npm run start -- web --document {url}
Un cop al Word, si el panell de tasques del teu complement no apareix automàticament, pots obrir un document nou, anar a la pestanya Inici i prémer el botó “Mostrar panell de tasques” del teu add-in . Al panell hi sol haver un enllaç o botó “Executar” que dispara la funcionalitat d'exemple (per exemple, inserir “Hola, mundo” en blau).
Quan vulguis aturar el servidor local i desinstal·lar el complement, pots fer servir l'ordre npm stop, que tanca el servidor i, en el cas habitual, treu l'add-in registrat per a aquesta sessió . Si en algun moment el vau carregar manualment com a complement local a Office a la web, haureu de seguir el procediment d'eliminació manual des de la pròpia interfície d'Office.
De vegades, la instal·lació automàtica de dependències que fa Yeoman (npm install) pot fallar. Si veieu errors en executar npm start, el més senzill és anar a la carpeta del projecte i llançar tu mateix npm install per resoldre els mòduls que faltin . És normal que apareguin algunes advertències durant la instal·lació; en la majoria de casos no impedeixen que tot funcioni.
Si voleu afinar les versions dels paquets i netejar dependències obsoletes, podeu recórrer a npm-check-updates (ncu) per revisar i actualitzar les dependències en bloc . El flux seria instal·lar ncu de forma global, executar ncu -u a l'arrel del projecte i finalment tornar a córrer npm install.
Primer complement d'Outlook amb Yeoman
El cas d'Outlook té el seu propi matís, sobretot per la varietat de clients disponibles: Outlook a la web, el nou Outlook a Windows, Outlook clàssic a Windows i Outlook a Mac. Tots ells poden fer servir el mateix complement si compleixes els requisits previs.
El procés de creació amb Yeoman és molt semblant al de Word. Instal·les Node.js, Yeoman i el generador d'Office, executes jo office i aquesta vegada tries Outlook com a aplicació client. De nou selecciones un projecte tipus panell de tasques, defineixes el nom del complement i, a més, decideixes quin tipus de manifest vols fer servir (per exemple, Unified manifest for Microsoft 365 o Add-in only manifest segons el teu escenari).
El generador us deixarà preparat un projecte amb el vostre manifest (JSON o XML), l'HTML del panell de tasques, els estils i el JavaScript que utilitza l'API d'Office per accedir al missatge seleccionat. L'exemple bàsic acostuma a mostrar almenys una propietat del correu, com l'assumpte, al mateix panell de tasques.
npm start
Aquesta ordre arrenca el servidor web local i registra el complement perquè es carregui automàticament a l'Outlook . Després t'adreces a un missatge al Tauler de lectura o obris un en una finestra a part, i allà busques el botó “Mostra panell de tasques” corresponent al teu add-in . La ubicació varia segons el client:
- A Outlook a la web i nou Outlook per a Windows, normalment accedeixes des de la barra d'accions del missatge, al menú d'aplicacions.
- A l'Outlook clàssic per a Windows, el botó sol aparèixer a la pestanya Inici o Missatge de la cinta.
- A Outlook per a Mac, veuràs el nom del complement a la cinta; potser haureu de desplegar el menú de punts suspensius per trobar-lo.
En obrir el panell de tasques es carregarà la interfície del teu complement i podràs prémer a l'enllaç o botó “Executar” perquè, per exemple, es mostri l'assumpte del correu dins del mateix panell . És una manera ràpida de comprovar que l'API d'Outlook està funcionant i que el vostre add-in rep el context del missatge seleccionat.
Per aturar el servidor local i desinstal·lar el complement, pots utilitzar npm stop a la consola, que s'encarrega de tancar el servidor i netejar el registre de l'add-in si aquest es va instal·lar mitjançant npm start. Si hagueu carregat el complement manualment, haureu de seguir el procés d'eliminació manual a l'aplicació d'Outlook corresponent.
Els mateixos consells de solució de problemes apliquen aquí: si npm install falla al principi, executa-ho manualment, ignora advertiments no crítics i recorre a npm-check-updates si vols actualitzar dependències de forma controlada. A més, la documentació oficial recull exemples de codi més elaborats, com un complement “Hola món” específic per a Word o tutorials més avançats per a Outlook.
Com trobar i utilitzar el teu complement dins de l'Office
Quan el vostre complement està instal·lat o carregat al compte de Microsoft 365, el següent pas és localitzar-lo dins de l'aplicació. El primer és assegurar-te que has iniciat sessió a l'Office amb el compte adequat , ja que molts complements s'associen a l'usuari oa la subscripció.
En aplicacions com Word, Excel o PowerPoint, el camí estàndard és anar al menú Inserir > Els meus complements, on es mostra el quadre “Complements per a Office”. Des d'aquí podeu cercar el vostre add-in per nom; si no apareix a la primera, convé revisar que estàs correctament autenticat i prémer el botó d'actualitzar per recarregar la llista.
Un cop localitzeu el complement a la llista, només cal fer doble clic per iniciar-lo i que es carregui al document . A partir d'aquest moment ja podràs fer-lo servir igual que vas fer durant les proves locals, però apuntant a l'entorn de producció oa l'allotjament que hagis configurat per a l'aplicació web de l'add-in.
Amb tot aquest recorregut ja tens una visió completa del procés: des de l'elecció d'eines (Yeoman, Visual Studio, Agents Toolkit o el Kit per a VS Code), passant per l'estructura interna d'un complement (manifest més aplicació web), fins a la interacció amb Office mitjançant Office.js, els requirement sets i Script Lab, a més dels fluids Word, Excel o Outlook tant en escriptori com a la web; amb aquestes bases ben assentades, convertir un simple prototip en un complement de Office llest per a producció es torna un camí força més clar i assumible. Comparteix aquesta informació i altres persones coneixeran del terme.