Librerie

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

Ottenere l'accesso a una raccolta

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

È necessario l'ID script della libreria da includere. Quando hai accesso alla libreria, puoi trovare l'ID script nella pagina settings 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 add.
2. Nel campo "ID script", incolla l'ID script della libreria.
3. Fai clic su Cerca.
4. Fai clic sul menu a discesa Versione e seleziona la versione della libreria da utilizzare.
5. Verifica se il nome predefinito dell'"Identificatore" è 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 di quella libreria come segue: Test.libraryMethod().
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 libreria, digita Test immediatamente seguito da un punto per visualizzare l'elenco dei metodi nella libreria.

La documentazione di riferimento per una libreria inclusa può essere aperta seguendo questi passaggi:

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

Rimuovere una raccolta

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

Aggiornare una raccolta

Puoi modificare la versione della libreria o aggiornare il relativo identificatore.

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

Creare e condividere una raccolta

Per utilizzare e condividere il tuo progetto di script come libreria, segui i passaggi riportati di seguito.

1. Crea un deployment con controllo delle versioni del tuo script.
2. Condividi almeno l'accesso a livello di visualizzazione con tutti i potenziali utenti della raccolta.
3. Fornisci a questi utenti l'ID script, che puoi trovare nella pagina settings Impostazioni progetto.

Best practice

Ecco alcune linee guida da seguire quando scrivi una biblioteca:

1. Scegli un nome significativo per il progetto, dato che viene utilizzato come identificatore predefinito quando la libreria viene inclusa da altri.
2. Se vuoi che uno o più metodi dello script non siano visibili (né utilizzabili) dagli utenti della tua libreria, puoi terminare il nome del metodo con un trattino basso. Ad esempio, myPrivateMethod_().
3. Solo le proprietà globali enumerabili sono visibili agli utenti delle librerie. 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 raccolta, ma non è accessibile ai tuoi utenti.

4. Se vuoi che gli utenti della libreria utilizzino il completamento automatico dell'editor di script e la documentazione generata automaticamente, devi disporre di 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) { ... }
   

Determinazione 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 accesso integrato alla stessa istanza della risorsa. Il seguente diagramma illustra una risorsa condivisa utilizzando l'esempio delle proprietà utente:

Una risorsa non condivisa significa che sia la libreria sia lo script di inclusione hanno accesso integrato solo all'istanza della risorsa. Tuttavia, una libreria può fornire accesso alle proprie risorse non condivise disponendo di funzioni esplicite che le consentono. Ecco un esempio di una funzione che dovresti includere nella libreria per esporre le relative proprietà dello script:

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

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

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

Risorsa	Condiviso*	Non condivisi**	Note
Blocca			La stessa istanza è visibile a tutti, inclusi gli script, quando viene creata nella libreria.
Proprietà script			La stessa istanza è visibile a tutti, inclusi gli script, quando viene creata nella libreria.
Cache			La stessa istanza è visibile a tutti, inclusi gli script, quando viene creata nella libreria.
Trigger			I trigger semplici creati nella libreria non vengono attivati dallo script di inclusione.
ScriptApp
UiApp
Proprietà utente
Trascrizione logger ed esecuzione
Sites, Fogli 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, ma utilizza quella creata dallo script che l'ha richiamata. ** 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.

Testare una libreria

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

Eseguire il debug di una libreria

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