Librerie

Una libreria è un progetto di script le cui funzioni possono essere riutilizzate in altri script.

Uno script che utilizza una libreria non viene eseguito con la stessa rapidità di uno in cui tutto il codice è contenuto in un unico progetto di script. Sebbene le librerie possano semplificare lo sviluppo e la manutenzione, utilizzale con parsimonia nei progetti in cui la velocità è fondamentale. A causa di questo problema, l'utilizzo delle librerie deve essere limitato nei componenti aggiuntivi di Google Workspace.

Ottenere l'accesso a una libreria

Per includere una libreria nel tuo progetto, devi avere almeno l'accesso a livello di visualizzazione. Se non sei l'autore della libreria che vuoi includere, contatta l'autore e richiedi l'accesso.

Ti serve l'ID dello script della libreria che vuoi includere. Quando hai accesso alla libreria, trova l'ID dello script nella pagina Impostazioni progetto .

Aggiungere una libreria al progetto di script

A sinistra dell'editor di Apps Script, accanto a "Librerie", fai clic su Aggiungi una libreria .
Nel campo "ID script", incolla l'ID dello script della libreria.
Fai clic su Cerca.
Se si verifica un errore, assicurati di avere almeno l'accesso a livello di visualizzazione al progetto che stai tentando di includere.
Fai clic sul menu a discesa Versione e seleziona la versione della libreria da utilizzare.
Controlla se il nome "Identificatore" predefinito è quello che vuoi utilizzare con questa libreria. Questo è il nome che lo script utilizza per fare riferimento alla libreria. Ad esempio, se lo imposti su Test, chiama un metodo della libreria nel seguente modo: Test.libraryMethod.
Se utilizzi un nome identificatore che corrisponde al nome di un servizio già esistente, ad esempio MailApp, o di una libreria aggiunta in precedenza, la libreria che hai aggiunto più di recente sostituisce il servizio o la libreria esistente.
Fai clic su Aggiungi.

Utilizzare una libreria

Utilizza la libreria inclusa come faresti con un servizio predefinito. Ad esempio, se Test è l'identificatore della libreria, digita Test seguito immediatamente da un punto per visualizzare l'elenco dei metodi nella libreria.

Per aprire la documentazione di riferimento di una libreria inclusa:

A sinistra dell'editor di script, accanto al nome della libreria, fai clic su Altro > Apri in una nuova scheda.

Rimuovere una libreria

A sinistra dell'editor di script, accanto al nome della libreria, fai clic su Altro > Rimuovi > Rimuovi libreria.

Se una libreria viene eliminata dall'autore, devi comunque rimuoverla dall'elenco delle librerie incluse.

Aggiornare una libreria

Modifica la versione della libreria o aggiorna il relativo identificatore.

A sinistra dell'editor, in "Librerie", fai clic sul nome della libreria.
Apporta le modifiche e fai clic su Salva.

Creare e condividere una libreria

Per utilizzare e condividere il progetto di script come libreria:

Crea un deployment con controllo delle versioni dello script.
Condividi almeno l'accesso a livello di visualizzazione con tutti i potenziali utenti della libreria.
Fornisci agli utenti l'ID dello script, che puoi trovare nella pagina Project Settings .

Best practice

Ecco alcune linee guida da seguire quando scrivi una libreria:

Scegli un nome significativo per il progetto, perché viene utilizzato come identificatore predefinito quando la libreria viene inclusa da altri.
Per fare in modo che uno o più metodi dello script non siano visibili (né utilizzabili) dagli utenti della libreria, termina il nome del metodo con un trattino basso. Ad esempio, myPrivateMethod_.
Solo le proprietà globali enumerabili sono visibili agli utenti della libreria. Sono incluse le dichiarazioni di funzioni, le variabili create al di fuori di una funzione con var e le proprietà impostate in modo esplicito sull'oggetto globale. Ad esempio, Object.defineProperty() con enumerable impostato su false crea un simbolo che puoi utilizzare nella libreria, ma questo simbolo non è accessibile ai tuoi utenti.

Per assicurarti che gli utenti della libreria possano utilizzare il completamento automatico dell'editor di script e la documentazione generata automaticamente, includi la documentazione in stile JSDoc per tutte le tue funzioni. Ad esempio:

/**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Definizione dell'ambito delle risorse

Quando lavori con le librerie, esistono due tipi di risorse: condivise e non condivise. Una risorsa condivisa significa che sia la libreria sia lo script di inclusione hanno un accesso integrato alla stessa istanza della risorsa. Il seguente diagramma illustra una risorsa condivisa utilizzando l'esempio delle proprietà utente:

Risorsa condivisa

Una risorsa non condivisa significa che sia la libreria sia lo script di inclusione hanno accesso integrato solo alla propria istanza della risorsa. Tuttavia, una libreria può fornire l'accesso alle proprie risorse non condivise tramite funzioni esplicite che operano su di esse. Ecco un esempio di funzione che puoi includere nella libreria per esporre le relative proprietà script:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

Il seguente diagramma illustra una risorsa non condivisa utilizzando l'esempio delle proprietà script:

Esempio di risorsa non condivisa

Questa tabella elenca le risorse condivise e non condivise per riferimento:

Risorsa	Condivisa*	Non condivisa**	Note
Blocca			La stessa istanza è visibile a tutti gli script di inclusione quando viene creata in la libreria.
Proprietà script			La stessa istanza è visibile a tutti gli script di inclusione quando viene creata in la libreria.
Cache			La stessa istanza è visibile a tutti gli script di inclusione quando viene creata in la libreria.
Trigger			I trigger semplici creati nella libreria non vengono attivati dallo script di inclusione. script.
ScriptApp
UiApp
Proprietà utente
Log e trascrizione dell'esecuzione
Siti, Fogli e altri container			Una chiamata a `getActive` restituisce il container dello script di inclusione.
MailApp e GmailApp
* Ciò significa che la libreria non ha una propria istanza della funzionalità/risorsa e utilizza invece quella creata dallo script che l'ha richiamata. ** Ciò significa che la libreria ha una propria istanza della risorsa/funzionalità e che tutti gli script che utilizzano la libreria condividono e hanno accesso a quella stessa istanza.

Testare una libreria

Per testare la libreria, utilizza il deployment head. Chiunque abbia accesso a livello di editor allo script può utilizzare il deployment head.

Devi comunque salvare almeno una versione della libreria.

Eseguire il debug di una libreria

Quando esegui il debug di uno script che include una libreria, non puoi eseguire lo step into nel codice della libreria né impostare punti di interruzione. Se provi a eseguire lo step into in una funzione della libreria in modalità di debug, il debugger salta la funzione e passa alla riga successiva nello script di chiamata.

L'utilizzo di HEAD (modalità di sviluppo) per la versione della libreria non consente di eseguire lo step into nella libreria o di raggiungere i punti di interruzione al suo interno.

Per eseguire il debug del codice della libreria, utilizza uno dei seguenti metodi:

Eseguire il debug dal progetto della libreria: apri il progetto di script della libreria nell'editor di Apps Script. Per testare le funzioni della libreria con argomenti specifici, crea una funzione "test" temporanea all'interno del progetto della libreria che chiama le funzioni della libreria, quindi esegui la funzione di test in modalità di debug.
Registrazione: utilizza console.log() all'interno delle funzioni della libreria per generare informazioni nei log di esecuzione. Quando la libreria viene chiamata da un altro script, questi log vengono visualizzati nei log di esecuzione dello script di chiamata.