Informazioni sulle API JavaScript di Office
In questa unità, verranno approfonditi il modello di programmazione dei componenti aggiuntivi per Office, gli strumenti di sviluppo e le funzionalità delle API JavaScript di Office per Excel, Outlook e Word.
Informazioni sul modello di programmazione dei componenti aggiuntivi per Office
Il modello di programmazione dei componenti aggiuntivi per Office si basa su due modelli a oggetti JavaScript:
- API JavaScript specifiche dell'host: API specifiche dell'host per Excel e Word forniscono oggetti tipizzati che è possibile usare per accedere a specifici elementi nell'applicazione host. Ad esempio, l'API di Excel contiene oggetti che rappresentano fogli di lavoro, intervalli, tabelle, grafici e altro ancora.
- API comune: introdotta con Office 2013, l'AI comune consente di accedere a funzionalità quali:
- Interfaccia utente
- Finestre di dialogo
- Impostazioni client comuni a più tipi di applicazioni di Office
Le funzioni personalizzate utilizzano un modello di programmazione leggermente diverso e verranno trattate in un'unità successiva.
Set di requisiti dell'API JavaScript di Office
Il controllo sulla versione di Office installata dagli utenti potrebbe non essere sempre mantenuto. A seconda della versione di Office e della piattaforma in cui viene eseguita, sono disponibili diverse API e funzionalità supportate per il componente aggiuntivo. Ad esempio, Office 2016 supporta più funzionalità rispetto a Office 2013. Per gestire questa situazione, vengono forniti set di requisiti che consentono di determinare se un host di Office supporta le funzionalità necessarie nel componente aggiuntivo di Office.
I set di requisiti possono essere specifici degli host di Office, ad esempio un set ExcelApi 1.7, o comuni a più host, ad esempio la Dialog API. Il supporto del set di requisiti varia in base alla versione dell’host e dell’host di Office.
È possibile verificare a livello di programmazione se i set di requisiti sono supportati dall'host di Office del componente aggiuntivo tramite l’utilizzo di isSetSupported. Se il set di requisiti è supportato, isSetSupported restituisce true e il componente aggiuntivo può eseguire il codice aggiuntivo che utilizza i membri dell'API da quel set di requisiti. Se l'host di Office non supporta il set di requisiti, isSetSupported restituisce false e non viene eseguito il codice aggiuntivo. Il codice seguente mostra la sintassi da utilizzare con isSetSupported.
if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion)) {
// Code that uses API members from RequirementSetName.
}
Nota
Programma Office Insider
Per ricevere le modifiche più recenti o mensili agli host di Office, è possibile partecipare al programma Office Insider. Questo programma è solo per PC Windows e richiede un abbonamento a Microsoft 365. In qualsiasi applicazione di Office seleziona File>Account>Office Insider per partecipare rapidamente al programma.
Utilizzo delle API JavaScript di Office
Per utilizzare le API, è possibile consultarle nella rete per la distribuzione di contenuti (CDN) di Office.js, solitamente aggiungendo una delle seguenti istruzioni di codice al tag di <head> della pagina.
<!-- Reference the production APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
<!-- Reference the beta/preview APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js" type="text/javascript"></script>
Oltre ad aggiungere il collegamento alla rete CDN preferito, tutti i componenti aggiuntivi per Office richiedono una chiamata a Office.onReady(). Il codice del componente aggiuntivo viene inserito in questo metodo e viene chiamato dopo l'inizializzazione della raccolta Office.js. All'interno del metodo onReady() è possibile determinare l'host in cui è in esecuzione il componente aggiuntivo verificando il valore dell’enumerazione Office.HostType (ad esempio Excel o Word). È possibile verificare la piattaforma su cui è in esecuzione il componente aggiuntivo con un valore dell’enumerazione Office.PlatformType (ad esempio, PC o Mac).
Se si usano altri framework JavaScript che includono il proprio gestore o i propri test di inizializzazione, essi devono essere inseriti nella risposta a Office.onReady(). Ad esempio, è possibile fare riferimento alla funzione $(document).ready() jQuery, come illustrato nell'esempio di codice seguente.
Office.onReady(function() {
// Office is ready.
$(document).ready(function () {
// The document is ready.
});
});
Esecuzione di chiamate asincrone con oggetti proxy
Quando si usa un documento, le azioni di lettura o scrittura richieste vengono eseguite in batch mediante un oggetto proxy. Le chiamate API non leggono o aggiornano effettivamente il documento sottostante finché non si chiama il metodo sync().
Per una maggiore sicurezza, il componente aggiuntivo viene eseguito in un ambiente JavaScript in modalità sandbox che non può accedere direttamente al documento o ad altri componenti aggiuntivi. La piattaforma dei componenti aggiuntivi per Office fornisce un oggetto RequestContext che a sua volta fornisce oggetti proxy per rappresentare il documento, ad esempio fogli di lavoro, intervalli e tabelle. La RequestContext viene in genere passata al codice come parametro denominato context. È possibile usare l’oggettocontext per ottenere gli oggetti proxy necessari per utilizzare il documento.
Per poter leggere le proprietà di un oggetto proxy, è necessario caricare le proprietà in modo da popolare l'oggetto proxy con i dati dal documento di Office. A questo scopo, chiamare il metodo load() nell’oggetto proxy per le proprietà necessarie. Chiamare quindi il metodo context.sync(), che effettuerà il caricamento di tutte le proprietà richieste. Ad esempio, se si crea un oggetto intervallo proxy per utilizzare un intervallo selezionato dall'utente in un foglio di lavoro di Excel e si vuole quindi leggere la proprietà address dell'intervallo selezionato, è necessario caricare la proprietà address prima di poterla leggere. Per richiedere il caricamento delle proprietà di un oggetto proxy, chiamare il metodo load() nell'oggetto e specificare le proprietà da caricare.
L'esempio seguente mostra una funzione che definisce un oggetto proxy locale (selectedRange), carica la proprietà address dell'oggetto e quindi chiama context.sync(). Quando la promessa di context.sync() è risolta, il codice può leggere la proprietà address. Per questo host specifico è richiesto Excel.run per caricare le proprietà che influiscono sul comportamento della piattaforma durante l'esecuzione della funzione. Non tutti gli host contengono una chiamata.
Excel.run(function (context) {
var selectedRange = context.workbook.getSelectedRange();
selectedRange.load('address');
return context.sync()
.then(function () {
console.log('The selected range is: ' + selectedRange.address);
});
}).catch(function (error) {
console.log('error: ' + error);
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Informazioni sugli strumenti di sviluppo dei componenti aggiuntivi per Office
È possibile usare gli strumenti di sviluppo dei componenti aggiuntivi di Office per creare un componente aggiuntivo di Office, esplorare le API JavaScript di Office e convalidare un file manifesto del componente aggiuntivo di Office. In questa unità, saranno approfondite i seguenti strumenti:
- Generatore Yeoman per i componenti aggiuntivi per Office
- Visual Studio
- Script Lab
- Manifest validator
Creazione di un componente aggiuntivo per Office
È possibile creare un componente aggiuntivo per Office usando il generatore Yeoman per i componenti aggiuntivi di Office o Visual Studio.
Consiglio
Per altre informazioni sul generatore Yeoman per i componenti aggiuntivi per Office, consultare il link github.com/OfficeDev/generator-office.
Generatore Yeoman per i componenti aggiuntivi per Office
Il generatore Yeoman per componenti aggiuntivi per Office può essere usato per creare un progetto di componente aggiuntivo per Office Node.js, che è possibile gestire con Visual Studio Code o con qualsiasi altro editor. Il generatore può creare componenti aggiuntivi per Office per:
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
- Funzioni personalizzate di Excel
È possibile creare il progetto con HTML, CSS e JavaScript oppure Angular o React. È disponibile anche l’opzione TypeScript.
Per creare un progetto di componente aggiuntivo per Office con il generatore Yeoman, completare i seguenti passaggi.
Per installare globalmente Yeoman e il generatore Yeoman per i componenti aggiuntivi per Office tramite npm, Gestione pacchetti del nodo, eseguire il comando seguente.
npm install -g yo generator-officePer creare un progetto di componente aggiuntivo con il generatore Yeoman, eseguire il comando seguente.
yo office
Visual Studio
È possibile utilizzare Visual Studio per creare componenti aggiuntivi per Office per Excel, Word, PowerPoint o Outlook. Un progetto di componente aggiuntivo per Office viene creato come parte di una soluzione Visual Studio. È quindi possibile utilizzare le funzionalità di Visual Studio, per esempio selezionando Start o la scegliendo F5, per eseguire automaticamente e localmente il componente aggiuntivo in IIS. I progetti di componenti aggiuntivi di Office creati con Visual Studio usare HTML, CSS e JavaScript.
Per creare un componente aggiuntivo per Office con Visual Studio, creare un nuovo progetto C# o Visual Basic e scegliere uno dei tipi di progetto seguenti.
- Componente aggiuntivo Web per Excel
- Componente aggiuntivo Web per Outlook
- Componente aggiuntivo Web per PowerPoint
- Componente aggiuntivo Web per Word
Esplorare le API con Script Lab
Script Lab è un componente aggiuntivo che consente di eseguire frammenti di JavaScript di Office mentre si utilizza un'applicazione di Office, ad esempio Excel o Word. È disponibile gratuitamente tramite AppSource ed è uno strumento utile da includere nel toolkit di sviluppo durante i test e la verifica delle funzionalità da includere nel componente aggiuntivo. In Script Lab è possibile accedere a una raccolta di esempi predefiniti per provare rapidamente le API o persino utilizzare un esempio come punto di partenza per il proprio codice.
Il video seguente mostra Script Lab in azione.
Convalida del file manifesto di un componente aggiuntivo di Office
Il manifesto dei componenti aggiuntivi per Office esamina il file manifesto del componente aggiuntivo per determinarne la correttezza e la completezza. Se il progetto di componente aggiuntivo è stato creato tramite il generatore Yeoman per i componenti aggiuntivi per Office (versione 1.1.17 o successiva), è possibile convalidare il manifesto eseguendo il seguente comando nella directory radice del progetto.
npm run validate
Se il generatore di Yeoman non è stato utilizzato per creare il progetto di componente aggiuntivo, è possibile convalidare il manifesto del componente aggiuntivo completando i seguenti passaggi.
Installare Node.js.
Eseguire il comando seguente nella directory radice del progetto.
Importante
Sostituire
{{MANIFEST_FILE}}con il nome del file manifesto.npx office-addin-manifest validate {{MANIFEST_FILE}}
Informazioni sulle funzionalità dell'API JavaScript per Excel
Le API JavaScript per Excel forniscono ai componenti aggiuntivi l'accesso ai documenti di Excel. Un componente aggiuntivo per Excel può gestire il contenuto, la formattazione e la struttura di una cartella di lavoro o di un foglio di calcolo.
Informazioni sulle funzionalità dell'API JavaScript per Outlook
Le API JavaScript per Outlook forniscono ai componenti aggiuntivi l'accesso alla cassetta postale, ai messaggi e agli appuntamenti dell'utente su Outlook. Un componente aggiuntivo per Outlook può recuperare il contenuto e le proprietà di un messaggio o di un appuntamento. Un componente aggiuntivo può anche gestire il contenuto, la formattazione e la struttura di un messaggio o di un appuntamento in fase di composizione.
Modello a oggetti
Per comprendere le API per Outlook, è necessario prima di tutto capire in che modo i componenti principali di una cassetta postale sono correlati tra loro.
- L’oggetto Cassetta postale consente di gestire l'autenticazione, un elemento selezionato e di visualizzare i dettagli del profilo utente.
- L’oggetto Elemento rappresenta il messaggio o l'appuntamento selezionato che l'utente sta leggendo o componendo.
Grazie alle API per Outlook è possibile gestire molte proprietà di un messaggio di posta elettronica o di un appuntamento. Molte delle API sono organizzate in base alla modalità di accesso dell'utente. La tabella seguente illustra i tipi di elemento e modalità.
| Tipo di elemento | Modalità |
|---|---|
| Messaggio | Lettura Composizione |
| Appuntamento/riunione | Partecipante (lettura) Organizzatore (composizione) |
Funzionalità principali
Oltre ai componenti aggiuntivi del riquadro attività, è possibile creare componenti aggiuntivi contestuali e del modulo. In questa sezione, verranno approfondite alcune funzionalità principali delle API per Outlook.
- Opzioni di autenticazione
- Componenti aggiuntivi contestuali
- Componenti aggiuntivi del modulo
Autenticazione
Il componente aggiuntivo per Outlook può accedere alle informazioni da qualsiasi punto di Internet. Alcuni esempi includono il server che ospita il componente aggiuntivo, la rete interna o qualsiasi altra posizione nel cloud. Se queste informazioni sono protette, il componente aggiuntivo deve essere in grado di autenticare l'utente. I componenti aggiuntivi per Outlook offrono molti metodi di autenticazione diversi, a seconda dello scenario specifico.
Token di identità per l’utente di Exchange
I token di identità per gli utenti di Exchange consentono al componente aggiuntivo di stabilire l'identità dell'utente. Verificando l'identità dell'utente, è possibile autenticare un utente nel sistema una sola volta, quindi accettare il token di identità per l'utente come autorizzazione per richieste future. È consigliabile utilizzare token di identità per l’utente se il componente aggiuntivo viene utilizzato principalmente da utenti locali di Exchange o richiede l’accesso a un servizio non Microsoft controllato dall'utente. Il componente aggiuntivo può chiamare getUserIdentityTokenAsync() per ottenere token di identità per l’utente di Exchange.
Ottenere i token di accesso con i flussi OAuth2
I componenti aggiuntivi possono anche accedere ai servizi di terze parti che supportano OAuth2 per l'autorizzazione. È consigliabile utilizzare token OAuth2 se il componente aggiuntivo richiede l’accesso a un servizio di terze parti non controllato dall’utente. Mediante questo metodo, il componente aggiuntivo chiede all'utente di accedere al servizio con il metodo displayDialogAsync(), ad esempio per l'inizializzazione del flusso OAuth2.
Token di richiamata
I token di richiamata forniscono al componente aggiuntivo l'accesso alla cassetta postale dell'utente dal server, tramite Servizi Web Exchange (EWS) o l'API REST di Outlook. I componenti aggiuntivi ottengono token di richiamata mediante uno dei metodi getCallbackTokenAsync(). Il livello di accesso è controllato dalle autorizzazioni specificate nel manifesto del componente aggiuntivo.
Riepilogo autenticazione
Nella tabella seguente viene riepilogato quando utilizzare ogni tipo di token di accesso.
| Token di accesso | Utilizzare se il componente aggiuntivo... |
|---|---|
| Token di identità per l’utente di Exchange | È utilizzato principalmente dagli utenti locali di Exchange. Richiede l'accesso a un servizio non Microsoft controllato dall’utente. |
| Token di accesso OAuth2 | Richiede l’accesso a un servizio di terze parti non controllato dall’utente. |
| Token di richiamata | Richiede l’accesso alla cassetta postale dell'utente dal server. |
Componenti aggiuntivi contestuali
I componenti aggiuntivi contestuali sono componenti aggiuntivi per Outlook che vengono attivati in base al testo di un messaggio o di un appuntamento. Potrebbero essere stati visualizzati i componenti aggiuntivi contestuali predefiniti in Outlook, ad esempio Bing Maps o Riunioni suggerite. Mediante i componenti aggiuntivi contestuali, un utente può avviare le attività relative a un messaggio senza chiudere il messaggio stesso. Ne risulta un'esperienza utente più semplice e completa.
La tabella seguente elenca alcuni esempi di attività in base alla selezione di un utente.
| L'utente sceglie... | Componente aggiuntivo contestuale in azione |
|---|---|
| Indirizzo | Aprire una mappa della località. |
| Stringa | Aprire un componente aggiuntivo per suggerimenti di riunione. |
| Numero di telefono | Aggiungere un numero ai contatti. |
Nota
I componenti aggiuntivi contestuali non sono al momento disponibili in Outlook per Android e iOS.
L'immagine seguente mostra un componente aggiuntivo contestuale visualizzato in Outlook.
Un componente aggiuntivo contestuale visualizzato in Outlook
Il manifesto di un componente aggiuntivo contestuale deve includere un elemento ExtensionPoint con un attributo xsi:type impostato su DetectedEntity. All'interno dell’elemento ExtensionPoint, il componente aggiuntivo specifica le entità o le espressioni regolari che consentono di attivarlo. Se specificata, l’entità può essere una delle proprietà nell'oggetto Entities.
Di conseguenza, il manifesto del componente aggiuntivo deve contenere una regola del tipo ItemHasKnownEntity o ItemHasRegularExpressionMatch. L'esempio seguente mostra come specificare che un componente aggiuntivo deve attivarsi nei messaggi al rilevamento di un numero di telefono.
<ExtensionPoint xsi:type="DetectedEntity">
<Label resid="contextLabel" />
<SourceLocation resid="detectedEntityURL" />
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="PhoneNumber" Highlight="all" />
</Rule>
</ExtensionPoint>
Una volta associato a un account, un componente aggiuntivo contestuale viene avviato automaticamente quando l'utente seleziona un'entità o un'espressione regolare evidenziata.
Un utente avvia un componente aggiuntivo contestuale tramite testo, un'entità nota o un'espressione regolare di uno sviluppatore. Un utente in genere identifica un componente aggiuntivo contestuale perché l'entità è evidenziata.
Componenti aggiuntivi del modulo
I componenti aggiuntivi del modulo vengono visualizzati nella barra di spostamento di Outlook, direttamente accanto a posta elettronica, attività e calendari. È possibile utilizzare tutte le funzionalità dell'API JavaScript per Outlook nel componente aggiuntivo e creare pulsanti di comando nella barra multifunzione di Outlook in modo che l'utente possa interagire con il contenuto del componente aggiuntivo.
Nota
I componenti aggiuntivi del modulo sono supportati solo in Outlook 2016 o versione successiva su Windows.
L'immagine seguente mostra un esempio di componente aggiuntivo di estensione del modulo.
Un esempio di componente aggiuntivo del modulo in Outlook su Windows
Per creare un componente aggiuntivo del modulo, includere il punto di estensione del modulo nel file manifesto del componente aggiuntivo. L'esempio seguente mostra un frammento di un file manifesto modificato in modo da definire l'estensione del modulo.
...
<!-- Add Outlook module extension point. -->
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides"
xsi:type="VersionOverridesV1_0">
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
xsi:type="VersionOverridesV1_1">
<!-- Begin override of existing elements. -->
<Description resid="residVersionOverrideDesc" />
<Requirements>
<bt:Sets DefaultMinVersion="1.3">
<bt:Set Name="Mailbox" />
</bt:Sets>
</Requirements>
<!-- End override of existing elements. -->
<Hosts>
<Host xsi:type="MailHost">
<DesktopFormFactor>
<!-- Set the URL of the file that contains the
JavaScript function that controls the extension. -->
<FunctionFile resid="residFunctionFileUrl" />
<!-- Module extension point for a ModuleApp -->
<ExtensionPoint xsi:type="Module">
<SourceLocation resid="residExtensionPointUrl" />
<Label resid="residExtensionPointLabel" />
<CommandSurface>
<CustomTab id="idTab">
<Group id="idGroup">
<Label resid="residGroupLabel" />
<Control xsi:type="Button" id="group.changeToAssociate">
<Label resid="residChangeToAssociateLabel" />
<Supertip>
<Title resid="residChangeToAssociateLabel" />
<Description resid="residChangeToAssociateDesc" />
</Supertip>
<Icon>
<bt:Image size="16" resid="residAssociateIcon16" />
<bt:Image size="32" resid="residAssociateIcon32" />
<bt:Image size="80" resid="residAssociateIcon80" />
</Icon>
<Action xsi:type="ExecuteFunction">
<FunctionName>changeToAssociateRate</FunctionName>
</Action>
</Control>
</Group>
<Label resid="residCustomTabLabel" />
</CustomTab>
</CommandSurface>
</ExtensionPoint>
</DesktopFormFactor>
</Host>
</Hosts>
<Resources>
...
</Resources>
</VersionOverrides>
</VersionOverrides>
Guida introduttiva allo sviluppo di componenti aggiuntivi per Outlook
Per sviluppare un componente aggiuntivo per Outlook, utilizzare:
- Il generatore Yeoman per i componenti aggiuntivi per Office
- Visual Studio
È possibile utilizzare un modello di base, quindi aggiungere le funzionalità.
Informazioni sulle funzionalità dell'API JavaScript per Word
Le API JavaScript per Word forniscono ai componenti aggiuntivi l'accesso ai documenti di Word. Un componente aggiuntivo per Word può gestire il contenuto, la formattazione e la struttura di un documento.
Modello a oggetti
Per comprendere le API per Word, è necessario prima di tutto capire in che modo i componenti principali di un documento sono correlati tra loro.
- Un Documento contiene un Corpo e almeno una Sezione.
- Un Corpo può includere:
- Paragrafo (uno o più)
- Tabella (una o più)
- Elenco (uno o più)
- Testo
- Oggetti come immagini ed elenchi
- Un Sezione consente di accedere al corpo, alle intestazioni e ai piè di pagina.
Scenari principali
In questa sezione, verranno approfonditi alcuni scenari principali per le API per Word.
- Utilizzare il testo del documento
- Ricerca
Nota
È possibile applicare una formattazione semplice a un intero documento esistente utilizzando le API Office.js. Tuttavia, se si vuole applicare una formattazione complessa o utilizzare oggetti di contenuto formattato, è possibile utilizzare formati Office Open XML (OOXML) per creare tali effetti. Tra gli esempi di funzionalità dei formati OOXML figurano l'applicazione di ombreggiature al testo o alle immagini, la conversione di caselle di testo in forme e l'inserimento di grafici di Excel come grafici dinamici nei documenti di Word. Poiché si tratta di competenze avanzate, questo argomento verrà affrontato solo in parte per gli sviluppatori esperti di OOXML.
Utilizzo del testo del documento
I componenti aggiuntivi di Word utilizzano il gestore dell'evento Office.onReady() per l’avvio. Se destinato a Word 2016 o versione successiva, il componente aggiuntivo chiama il metodo Word.run() per eseguire le API JavaScript per Word. Il componente aggiuntivo deve passare una funzione a Word.run() che prevede che un oggetto di contesto venga passato come parametro. L'oggetto di contesto consente al componente aggiuntivo di interagire con il documento di Word. È possibile utilizzare l'oggetto di contesto per creare gli oggetti proxy necessari al documento di Word e caricare i proxy con le proprietà da utilizzare. È inoltre possibile programmare le azioni da eseguire utilizzando queste proprietà. Come di consueto, un context.sync() esegue il comando, quindi sincronizza lo stato tra gli oggetti proxy e gli oggetti nel documento di Word.
L'esempio seguente mostra il codice che inserisce del testo dopo il corpo del testo di un documento di Word. Per semplicità, questo esempio omette il codice Office.onReady() ed è incentrato sul codice all'interno di un blocco di codice Word.run().
// Run a batch operation against the Word JavaScript API.
Word.run(function (context) {
// Create a proxy object for the document body.
var body = context.document.body;
// Queue a command to load the text property of the proxy body object.
body.load("text");
// Queue a command to insert text into the end of the Word document body.
body.insertText('This is text inserted after loading the body.text property',
Word.InsertLocation.end);
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log("Body contents: " + body.text);
});
})
Ricerca
È possibile utilizzare le API per ricercare nel documento del testo che soddisfa i criteri specificati. È inoltre possibile restringere l'ambito della ricerca in base a determinati tipi di contenuto, ad esempio paragrafi o tabelle.
L'esempio di codice seguente ricerca il testo "il video che" e ignora la punteggiatura. Se il testo viene trovato, le corrispondenze sono visualizzate in grassetto, evidenziate in giallo e il colore del carattere è impostato sul viola.
// Run a batch operation against the Word object model.
Word.run(function (context) {
// Queue a command to search the document and ignore punctuation.
var searchResults = context.document.body.search('video you', {ignorePunct: true});
// Queue a command to load the search results and get the font property values.
context.load(searchResults, 'font');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log('Found count: ' + searchResults.items.length);
// Queue a set of commands to change the font for each found item.
for (var i = 0; i < searchResults.items.length; i++) {
searchResults.items[i].font.color = 'purple';
searchResults.items[i].font.highlightColor = '#FFFF00'; // Yellow
searchResults.items[i].font.bold = true;
}
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync();
});
})
.catch(function (error) {
console.log('Error: ' + JSON.stringify(error));
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Guida introduttiva allo sviluppo di componenti aggiuntivi per Word
Per sviluppare un componente aggiuntivo per Word, utilizzare:
- Il generatore Yeoman per i componenti aggiuntivi per Office
- Visual Studio
Per ulteriori informazioni sulle API, è consigliabile utilizzare il componente aggiuntivo Script Lab. Sono disponibili molti frammenti di codice TypeScript e JavaScript ed è possibile utilizzare i documenti di Word senza creare un intero componente aggiuntivo.
Informazioni sulle funzionalità delle funzioni personalizzate
Le funzioni personalizzate presentano diverse funzionalità e restrizioni univoche poiché vengono eseguite in una fase di esecuzione distinta da altre interazioni con i componenti aggiuntivi, ad esempio i riquadri attività.
Funzionalità delle funzioni personalizzate
È possibile creare funzioni JavaScript o TypeScript personalizzate a cui è possibile accedere, quali funzioni di Excel incorporate come SUM(). È inoltre possibile creare funzioni di flusso personalizzate che restituiscono un valore in base a un timer. Ad esempio, è possibile aggiornare il valore di ora corrente in una cella ogni secondo. È possibile effettuare chiamate di rete anche da funzioni personalizzate.
Esempio di JavaScript per funzioni personalizzate
Nell'esempio di codice seguente viene definita la funzione personalizzata add() che accetta due numeri e ne restituisce la somma.
/**
* Adds two numbers.
* @customfunction
* @param first First number.
* @param second Second number.
* @returns The sum of the two numbers.
*/
function add(first, second){
return first + second;
}
Descrizioni dei commenti al codice JSDoc
I tag JSDoc nei commenti al codice sono utilizzati per generare un file di metadati JSON che descrive la funzione personalizzata in Excel. Il file di metadati JSON consente a Excel di presentare in modo accurato le informazioni a un utente e di passare i parametri previsti alla funzione personalizzata.
@customfunction: viene dichiarato per primo e indica che si tratta di una funzione personalizzata. Obbligatorio.@param: descrive il parametro. Includere per ciascun parametro definito dalla funzione.@returns: descrive gli output della funzione.
Nota
La descrizione del commento "Somma due numeri". viene aggiunta anche al file di metadati JSON per Excel per visualizzare quando l'utente visualizza la funzione personalizzata.
Restrizioni di runtime delle funzioni personalizzate
Il runtime delle funzioni personalizzate esegue solo JavaScript. Non è presente un modello DOM (Document Object Model) o un archivio locale, come in un ambiente di runtime JavaScript basato su browser. Non è pertanto possibile caricare raccolte che utilizzano il DOM, ad esempio jQuery. Inoltre, non è possibile accedere all'API Office.js per interagire con il documento come è possibile fare da un riquadro attività. Il runtime delle funzioni personalizzate è invece ottimizzato per attività quali l'esecuzione di calcoli rapidi. Generalmente, non richiede l’utilizzo di alcune API Office.js, come ad esempio gli strumenti di formattazione in Excel.
Le funzioni personalizzate una pagina Web che carica il runtime delle funzioni personalizzate. Poiché il runtime delle funzioni personalizzate non hanno un'interfaccia utente, la pagina Web non può essere visualizzata. Nella pagina Web è presente il tag script seguente che carica la raccolta per il runtime delle funzioni personalizzate.
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/custom-functions-runtime.js" type="text/javascript"></script>
Generalmente, le funzioni personalizzate sono combinate con un riquadro attività nello stesso componente aggiuntivo. Se si crea il progetto di componente aggiuntivo con il generatore Yeoman per i componenti aggiuntivi per Office, il progetto presenterà una pagina Web per le funzioni personalizzate e una pagina Web con l'interfaccia utente per il riquadro attività.
Utilizzo dell'API di archiviazione per comunicare con il riquadro attività
Il codice della funzione personalizzata e del riquadro attività, che utilizza Office.js, non possono chiamarsi o comunicare direttamente tra loro. Tuttavia, è possibile utilizzare un'API di archiviazione che consente di condividere i dati. Uno scenario comune per l'utilizzo dell'API di archiviazione è quando il componente aggiuntivo richiede di condividere un token di sicurezza per accedere a una risorsa di rete protetta. L'utente potrebbe prima chiamare una funzione personalizzata che richiede di effettuare l'accesso. Dopo l'autenticazione, la funzione riceve il token di sicurezza. Quindi, condivide il token di sicurezza utilizzando l'API di archiviazione, in modo che, in un secondo momento, quando l'utente apre il riquadro attività, non sia necessario effettuare di nuovo l'accesso.
In alternativa, l'utente potrebbe prima aprire il riquadro attività. In questo caso, il riquadro attività effettua l’accesso e condivide il token di sicurezza tramite l'API di archiviazione. In un secondo momento, quando viene utilizzata una funzione personalizzata, questa può ottenere il token di sicurezza tramite l'API di archiviazione.
Esempio di API di archiviazione
L'esempio di codice seguente mostra come archiviare e recuperare i valori creati dall'utente.
/**
* @customfunction
* @description Stores a value in OfficeRuntime.storage.
* @param {any} key Key in the key-value pair you will store.
* @param {any} value Value in the key-value pair you will store.
*/
function storeValue(key, value) {
return OfficeRuntime.storage.setItem(key, value).then(function (result) {
return "Success: Item with key '" + key + "' saved to storage.";
}, function (error) {
return "Error: Unable to save item with key '" + key + "' to storage. " + error;
});
}
/**
* @customfunction
* @description Gets value from OfficeRuntime.storage.
* @param {any} key Key of item you intend to get.
*/
function getValue(key) {
return OfficeRuntime.storage.getItem(key);
}
Dialog API
Le funzioni personalizzate sono caratterizzate da proprie Dialog API, perché non possono accedere all'API Office.js. Tuttavia, la funzionalità è simile. Lo scenario più comune consiste nell'avviare una finestra di dialogo per consentire l’accesso a un utente e ricevere un token di sicurezza.
L'esempio di codice seguente mostra come visualizzare una finestra di dialogo Web da una funzione personalizzata.
OfficeRuntime.displayWebDialog('https://myDomain/myDialog.html', {height: 30, width: 20});
Creazione di un progetto di funzioni personalizzate
È possibile creare un progetto di funzioni personalizzate utilizzando il generatore Yeoman per componenti aggiuntivi per Office. Eseguire yo office per avviare il generatore, quindi selezionare l’opzione Progetto di componente aggiuntivo per funzioni personalizzate per Excel. Una volta creato, il progetto conterrà una cartella src/taskpane/ per i file di origine del riquadro attività e una cartella /src/functions per i file di origine delle funzioni personalizzate.
Nota
Non è possibile creare un progetto di funzioni personalizzate in Visual Studio.
Riepilogo
In questa unità, sono stati approfonditi il modello di programmazione e gli strumenti di sviluppo dei componenti aggiuntivi per Office e le funzionalità delle API JavaScript di Office per Excel, Outlook e Word.