Librerie

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

Avviso :uno script che utilizza una libreria non viene eseguito rapidamente come farebbe se tutto il codice fosse contenuto in un unico progetto di script. Anche se le librerie possono rendere più semplici lo sviluppo e la manutenzione, usale con parsimonia nei progetti in cui la velocità è fondamentale. A causa di questo problema, l'utilizzo della libreria dovrebbe essere limitato nei componenti aggiuntivi.

Ottenere l'accesso a una raccolta

Per includere una libreria nel progetto, devi disporre almeno dell'accesso a livello di vista. Se non sei l'autore della raccolta che vuoi includere, contatta l'autore e richiedi l'accesso.

Devi inserire l'ID script della libreria da includere. Quando hai accesso alla libreria, puoi trovare l'ID script nella pagina Impostazioni progetto .

Aggiungere una libreria al progetto di script

1. A sinistra dell'editor di Apps Script, fai clic su Aggiungi una libreria accanto a "Librerie".
2. Nel campo "ID script", incolla l'ID script della libreria.
3. Fai clic su Cerca.
   Se riscontri un errore, assicurati di disporre almeno dell'accesso a livello di vista al progetto che vuoi includere.
4. Fai clic sul menu a discesa Versione e seleziona la versione della libreria da utilizzare.
5. Verifica 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, puoi chiamare un metodo della libreria come segue: Test.libraryMethod().
   Se utilizzi un nome identificatore che corrisponde al nome di un servizio esistente, ad esempio MailApp o una libreria aggiunta in precedenza, la libreria aggiunta più di recente sostituisce il servizio o la libreria esistenti.
6. Fai clic su Aggiungi.

Utilizza una raccolta

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

Per aprire la documentazione di riferimento per una libreria inclusa, segui questi passaggi:

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

Rimuovere una raccolta

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

Se una biblioteca viene eliminata dall'autore, devi comunque rimuoverla dall'elenco delle raccolte incluse.

Aggiornare una raccolta

Puoi modificare la versione della raccolta o aggiornarne l'identificatore.

1. A sinistra dell'editor, fai clic sul nome della raccolta nella sezione "Librerie".
2. Apporta le modifiche e fai clic su Save (Salva).

Creare e condividere una raccolta

Per utilizzare e condividere il progetto di script come libreria, procedi nel seguente modo.

1. Crea un deployment con versione dello script.
2. Condividi almeno il livello di visualizzazione con tutti i potenziali utenti della raccolta.
3. Fornisci a tali utenti l'ID script, che puoi trovare nella pagina Impostazioni progetto .

Best practice

Di seguito sono riportate alcune linee guida da seguire per scrivere una raccolta:

1. Scegli un nome significativo per il tuo progetto, poiché viene utilizzato come identificatore predefinito quando la tua libreria è inclusa da altri.
2. Se vuoi che uno o più metodi dello script non siano visibili (né utilizzabili) agli utenti della tua libreria, puoi terminare il nome del metodo con un trattino basso. Ad esempio, myPrivateMethod_().
3. Solo gli enumerabili proprietà globali sono visibili agli utenti della libreria. Sono incluse le dichiarazioni di funzioni, le variabili create al di fuori di una funzione con var, nonché le proprietà impostate esplicitamente sull'oggetto globale. Ad esempio, Object.defineProperty() con enumerable impostato su false crea un simbolo che puoi utilizzare nella tua raccolta, ma questo simbolo non è accessibile per i tuoi utenti.

4. Se vuoi che gli utenti della tua libreria utilizzino il completamento automatico dell'editor di script e la documentazione generata automaticamente, devi avere una documentazione in stile JSDoc per tutte le tue funzioni. 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) { ... }
   

Ambito delle risorse

Esistono due tipi di risorse quando lavori con le librerie: condivise e non condivise. Una risorsa condivisa significa che sia la libreria che 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:

Una risorsa non condivisa indica che sia la libreria che lo script di inclusione hanno accesso integrato solo alla rispettiva istanza della risorsa. Tuttavia, una libreria può fornire l'accesso alle risorse non condivise tramite funzioni esplicite che vi operano. Ecco un esempio di funzione che includeresti nella libreria per esporre le proprietà dello script:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

Il seguente diagramma illustra una risorsa non condivisa usando l'esempio di proprietà script:

In questa tabella sono elencate le risorse condivise e non condivise per riferimento futuro:

Risorsa	Condivisa*	Non condiviso**	Note
Blocca			La stessa istanza è visibile a tutti gli script, inclusi quelli creati nella libreria.
Proprietà script			La stessa istanza è visibile a tutti gli script, inclusi quelli creati nella libreria.
Cache			La stessa istanza è visibile a tutti gli script, inclusi quelli creati nella libreria.
Trigger			I trigger semplici creati nella libreria non vengono attivati dallo script di inclusione.
App Script
App Ui
Proprietà utente
Strumento di log e trascrizione dell'esecuzione
Siti, fogli di lavoro e altri contenitori			Una chiamata a getActive() restituisce il container dello script incluso.
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 la propria istanza della risorsa o della funzionalità e che tutti gli script che la utilizzano condividono e hanno accesso alla stessa istanza.

Testare una raccolta

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

Hai ancora bisogno di almeno una versione della libreria salvata.

Eseguire il debug di una libreria

Quando utilizzi il debugger in un progetto che include una libreria, puoi passare a una funzione della libreria inclusa. Il codice viene visualizzato nel debugger in modalità di sola visualizzazione e nella versione corretta.