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 dell'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 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
- A sinistra dell'editor di Apps Script, fai clic su Aggiungi una libreria accanto a "Librerie".
- Nel campo "ID script", incolla l'ID script della libreria.
- Fai clic su Cerca.
- Fai clic sul menu a discesa Versione e seleziona la versione della libreria da utilizzare.
- Controlla se il nome predefinito dell'"Identificatore" è quello che vuoi utilizzare con questa libreria. Si tratta del 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()
. - 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
subito 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, 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 libreria.Aggiornare una libreria
Puoi modificare la versione della libreria o aggiornarne l'identificatore.
- A sinistra dell'editor, nella sezione "Biblioteche", fai clic sul nome della biblioteca.
- 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.
- Crea un deployment con il controllo delle versioni dello script.
- Condividi almeno l'accesso a livello di visualizzazione con tutti i potenziali utenti della raccolta.
- Fornisci a questi utenti l'ID script, disponibile nella pagina Impostazioni progetto.
best practice
Ecco alcune linee guida da seguire quando si scrive una biblioteca:
- Scegli un nome significativo per il progetto poiché viene utilizzato come identificatore predefinito quando la libreria è inclusa da altri.
- 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_()
. - 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 esplicitamente nell'oggetto globale. Ad esempio,Object.defineProperty()
conenumerable
impostato sufalse
crea un simbolo che puoi usare nella tua raccolta, ma non è accessibile ai tuoi utenti. 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. 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 utilizzi le librerie, esistono due tipi di risorse: condivise e non condivise. Una risorsa condivisa significa che sia la libreria sia lo script di inclusione dispongono di 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 significa che sia la libreria sia lo script incluso hanno accesso integrato solo alla propria istanza della risorsa. Tuttavia, una libreria può fornire l'accesso alle risorse non condivise grazie a funzioni esplicite che le consentono. Di seguito è riportato un esempio di funzione da includere nella libreria per esporre le proprietà degli script:
function getLibraryProperty(key) {
return ScriptProperties.getProperty(key);
}
Il seguente diagramma illustra una risorsa non condivisa utilizzando l'esempio di proprietà script:
Questa tabella elenca le risorse condivise e non condivise come riferimento:
Risorsa | Condiviso* | Non condiviso** | 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 dello strumento di log ed esecuzione | |||
Sites, Fogli e altri contenitori | 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
caratteristica/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 utilizzano la libreria condividono e hanno accesso alla stessa istanza. |
Testare una libreria
Per testare la tua raccolta, utilizza il deployment head. Chiunque abbia accesso a livello di editor allo script può utilizzare il deployment head.
Eseguire il debug di una libreria
Quando utilizzi il debugger in un progetto che include una libreria, puoi accedere a una funzione della libreria inclusa. Il codice appare nel debugger in modalità di sola visualizzazione e nella versione corretta.