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 così rapidamente come se tutto il codice fosse contenuto in un singolo 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 della raccolta 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 disporre dell'ID script della libreria che vuoi 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, accanto a "Librerie", fai clic su Aggiungi una libreria .
2. Nel campo "ID script", incolla l'ID script della raccolta.
3. Fai clic su Cerca.
   Se si verifica un errore, assicurati di avere almeno accesso a livello di visualizzazione al progetto che stai tentando di includere.
4. Fai clic sul menu a discesa Versione e seleziona la versione della raccolta da utilizzare.
5. Verifica che il nome predefinito "Identificatore" sia quello che vuoi utilizzare con questa libreria. Questo è il nome utilizzato dallo script per fare riferimento alla libreria. Ad esempio, se lo imposti su Test, puoi chiamare un metodo di quella libreria come segue: 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 aggiunta più di recente sostituisce il servizio o la libreria esistente.
6. Fai clic su Aggiungi.

Utilizzare una libreria

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

Per aprire la documentazione di riferimento di una raccolta inclusa:

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

Rimuovere una raccolta

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

Se una raccolta 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 libreria in "Raccolte".
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, segui i passaggi riportati di seguito.

1. Crea un deployment con versionamento del tuo script.
2. Condividi almeno l'accesso a livello di visualizzazione con tutti i potenziali utenti della libreria.
3. Fornisci a questi utenti l'ID script, disponibile nella pagina Impostazioni progetto .

Best practice

Ecco alcune linee guida da seguire quando scrivi una libreria:

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

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

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

Una risorsa non condivisa indica che sia la libreria sia lo script di inclusione hanno accesso integrato solo alla propria istanza della risorsa. Tuttavia, una libreria può fornire accesso alle sue risorse non condivise disponendo di funzioni esplicite che operano su di esse. Ecco un esempio di funzione da includere nella raccolta per esporre le relative proprietà di 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à di script:

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

Risorsa	Condivisi*	Non condiviso**	Note
Blocca			La stessa istanza è visibile a tutti, inclusi gli script, quando viene creata nella raccolta.
Proprietà script			La stessa istanza è visibile a tutti, inclusi gli script, quando viene creata nella raccolta.
Cache			La stessa istanza è visibile a tutti, inclusi gli script, quando viene creata nella raccolta.
Trigger			Gli trigger semplici creati nella libreria non vengono attivati dallo script incluso.
ScriptApp
UiApp
Proprietà utente
Logger e trascrizione dell'esecuzione
Sites, Fogli e altri contenitori			Una chiamata a getActive() restituisce il contenitore dello script incluso.
MailApp e GmailApp
* Ciò significa che la libreria non ha la propria istanza della funzionalità/risorsa e utilizza quella creata dallo script che l'ha invocata. ** Ciò significa che la libreria ha la propria istanza della risorsa/funzionalità e che tutti gli script che la utilizzano condividono e hanno accesso alla stessa istanza.

Testa una libreria

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

Devi comunque salvare almeno una versione della libreria.

Eseguire il debug di una libreria

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