Elementi di base di Apps Script con Fogli Google #1: macro e funzioni personalizzate

1. Ti diamo il benvenuto in Apps Script

Che cos'è Apps Script?

Apps Script è una piattaforma per lo sviluppo rapido di applicazioni che ti consente di automatizzare, personalizzare ed estendere la tua esperienza con Google Workspace. Con Apps Script, puoi risparmiare tempo e fatica semplificando il lavoro oneroso o complesso in Google Workspace.

Le funzionalità di Apps Script includono:

• I servizi integrati di Apps Script ti consentono di leggere, aggiornare e manipolare i dati delle applicazioni Google Workspace con gli script.
• Puoi creare script utilizzando l'editor di codice in-browser di Apps Script. Non è necessario installare o eseguire software di sviluppo del codice.
• Puoi progettare interfacce utente per gli editor di Google Workspace che ti consentono di attivare gli script direttamente da questi editor utilizzando voci di menu, finestre di dialogo e barre laterali.

Questa playlist di codelab su Nozioni di base di Apps Script con Fogli Google insegna le basi di Apps Script e come utilizzarlo per migliorare la tua esperienza con Fogli Google. Questo codelab si concentra sull'insegnamento delle nozioni di base di Apps Script.

Il servizio Fogli

Puoi utilizzare Apps Script per estendere Fogli Google e risparmiare tempo e fatica. Apps Script fornisce il servizio Fogli che consente agli script di interagire con i file Google Sheets e i dati in essi contenuti. Puoi utilizzare questo servizio per automatizzare le seguenti attività comuni dei fogli di lavoro:

• Crea o modifica un foglio di lavoro.
• Leggere e aggiornare dati, formule e formattazione delle celle.
• Crea pulsanti e menu personalizzati.
• Importa ed esporta dati da altre applicazioni Google o da origini di terze parti.
• Condividi e controlla l'accesso ai fogli di lavoro.

Obiettivi didattici

Questa playlist copre tutti gli argomenti di cui avrai bisogno per iniziare a utilizzare Apps Script con Fogli Google:

1. Macro e funzioni personalizzate
2. Fogli di lavoro, fogli e intervalli
3. Utilizzare i dati
4. Formattazione dei dati
5. Creare grafici e presentare i dati in Presentazioni

I codelab di questa playlist devono essere letti in ordine, quindi inizia da questo e completali in sequenza per un'esperienza di apprendimento ottimale.

Passa alla sezione successiva per scoprire di più sui contenuti di questo codelab.

2. Introduzione

Ti diamo il benvenuto al primo codelab di questa playlist. In questo codelab imparerai le nozioni di base sull'utilizzo di Apps Script con Fogli Google. Nello specifico, questo codelab si concentra su due concetti chiave: macro e funzioni personalizzate.

Una macro è una serie di azioni registrate in Fogli Google. Una volta registrata, puoi attivare una macro per ripetere queste azioni in un secondo momento con una voce di menu o un tasto di scelta rapida. Puoi creare e aggiornare le tue macro sia in Fogli Google che nell'editor di codice Apps Script.

Nell'editor di codice Apps Script, puoi anche creare funzioni personalizzate. Analogamente alle funzioni integrate offerte da Fogli (ad esempio SUM o AVERAGE), puoi utilizzare Apps Script per scrivere le tue funzioni personalizzate per operazioni semplici e di nicchia (come conversioni o concatenazione di stringhe). Una volta create, puoi chiamare queste funzioni in Fogli come faresti con una funzione integrata. Le funzioni personalizzate possono essere utilizzate anche nelle formule delle celle che scrivi, combinandole con altre funzioni in base alle esigenze.

Continua a leggere per scoprire i concetti e i requisiti di questo codelab.

Obiettivi didattici

• Come creare uno script per Fogli Google.
• Come navigare nell'editor di Apps Script.
• Come creare e aggiornare le macro.
• Come creare la tua prima funzione personalizzata di Fogli.

Che cosa ti serve

• Familiarità di base con JavaScript
• Familiarità di base con Fogli Google
• Possibilità di leggere i fogli Notazione A1

Hai terminato le presentazioni. Vai alla sezione successiva per iniziare a lavorare con le macro.

3. Creare una macro in Fogli

In genere, quando lavori nei fogli di lavoro, puoi entrare in un ciclo di azioni ripetitive, come copiare valori delle celle, formattare, creare formule e così via, che possono diventare noiose e portare a errori. Per automatizzare le azioni ripetute, Fogli Google fornisce le macro. Le macro ti consentono di "registrare" una serie di azioni in un foglio. Con una macro registrata, puoi ripetere le stesse azioni altrove in un foglio di lavoro con una semplice pressione di una scorciatoia da tastiera.

In questa sezione, imparerai a creare una macro in Fogli. Nella sezione successiva vedrai come vengono create le macro utilizzando Apps Script.

Prima di iniziare

Prima di continuare, devi avere un foglio di lavoro con alcuni dati. Ne abbiamo fornito uno: fai clic su questo link per copiare il foglio di dati e poi fai clic su Crea una copia.

Una copia del foglio di lavoro di esempio da utilizzare viene inserita nella cartella di Google Drive e denominata "Copia dei 10 film con maggiori incassi (2018)".

Creare una macro

Ora che hai un foglio di lavoro su cui lavorare, puoi registrare una macro in Fogli Google. Per questo esempio, creerai una macro che formatta una riga di intestazione per i tuoi dati. segui questa procedura:

1. Fai clic sulla cella A1 per posizionare il cursore nella riga. Questa è la riga di intestazione.
2. Nel menu, seleziona Estensioni > Macro > Registra macro.

Una volta avviata la registrazione, Fogli Google memorizza ogni azione che esegui nel foglio di lavoro: evidenziazione delle celle, aggiunta di dati, passaggio a fogli diversi, formattazione e così via. Queste azioni diventano lo "script" che viene ripetuto dopo aver salvato e attivato la macro.

3. Nella finestra di dialogo Macro, seleziona Riferimento relativo.

4. Seleziona riga 1.

5. Ricolora il Colore di riempimento della prima riga da bianco a magenta scuro 3.

6. Modifica il colore del testo della prima riga da nero a bianco.

7. Per mettere il testo in grassetto, premi Ctrl+B (o Cmd+B su macOS).
8. Per bloccare la prima riga, seleziona Visualizza > Blocca > 1 riga.

9. Fai clic su Salva nella finestra di dialogo della macro. Una nuova finestra di dialogo ti chiede di assegnare un nome alla macro. Inserisci il nome "Intestazione" e fai clic su Salva.

Utilizzando l'interfaccia utente di Fogli, hai creato una macro specializzata per la formattazione delle intestazioni.

Attivare la macro

Puoi applicare la nuova macro in Fogli seguendo queste istruzioni:

1. Per creare un foglio, fai clic su Aggiungi foglio .

2. Nel nuovo foglio, aggiungi del testo a A1:C2. Non esitare a seguire gli input di esempio riportati di seguito:

3. Evidenzia la prima riga.

4. Per applicare la macro all'area selezionata, fai clic su Estensioni > Macro > Intestazione.
5. Autorizza la macro seguendo le istruzioni sullo schermo.

6. Ripeti il passaggio 4 per eseguire di nuovo la macro (l'autorizzazione interrompe la prima esecuzione).

Congratulazioni, hai imparato ad applicare le macro in Fogli. Il foglio di lavoro dovrebbe avere il seguente aspetto:

Le macro ti consentono di creare fogli di lavoro in modo efficiente e, nella parte successiva di questo codelab, imparerai a renderle ancora più potenti. Il segreto è che quando registri una macro, in realtà scrivi codice Apps Script. Dietro le quinte, Fogli crea il codice che corrisponde alle azioni della macro. Nella sezione successiva, imparerai a modificare il codice direttamente utilizzando l'editor in-browser di Apps Script.

4. Macro nell'editor di script

Mentre crei una macro, Fogli Google salva le tue azioni come funzione Apps Script. Quando attivi la macro, Fogli Google chiama la funzione Apps Script per applicare queste azioni nello stesso ordine.

L'editor di script

Ora che hai creato una macro, puoi esaminarne il codice. Per visualizzare lo script della macro, fai clic su Estensioni > Apps Script per aprire l'editor di codice del browser per Apps Script.

L'editor di script ti consente di scrivere codice in Apps Script ed eseguire questi script sui server Google.

Analisi di macros.gs

Rivedi lo script attuale. Fogli ha creato il file di script macros.gs quando hai registrato la macro Header, riempiendolo con una funzione Apps Script corrispondente chiamata Header. Quando attivi la macro Header, Fogli esegue questa funzione.

Guarda l'immagine di seguito per familiarizzare con la struttura della funzione macro in Apps Script. Se hai registrato i passaggi in un ordine diverso o hai fatto clic sul foglio di lavoro durante la registrazione, il codice potrebbe essere leggermente diverso.

La prima riga è un commento di annotazione che influisce sull'autorizzazione:

/** @OnlyCurrentDoc */ 

La maggior parte degli script chiede all'utente alcune autorizzazioni prima di poter essere eseguiti. Queste autorizzazioni controllano le operazioni che l'utente consente allo script di eseguire. Quando il commento @OnlyCurrentDoc è presente in un progetto di script, Apps Script chiede solo l'autorizzazione per accedere al foglio di lavoro corrente e aggiornarlo. Senza questo commento, Apps Script chiederebbe l'autorizzazione per accedere e aggiornare tutti i fogli di lavoro dell'utente. È sempre consigliabile includere questa annotazione quando lavori con un solo file. Il registratore di macro aggiunge automaticamente questo commento.

Per capire come Apps Script rappresenta le istruzioni della macro, puoi esaminare la funzione:

function Header(){   var spreadsheet = SpreadsheetApp.getActive();   var sheet = spreadsheet.getActiveSheet();   sheet.getRange(     spreadsheet.getCurrentCell().getRow(),     1, 1, sheet.getMaxColumns()).activate();   spreadsheet.getActiveRangeList().setBackground('#4c1130')   .setFontColor('#ffffff')   .setFontWeight('bold');   spreadsheet.getActiveSheet().setFrozenRows(1); }; 

Questo codice viene eseguito quando attivi la macro Header. Dopo function, l'etichetta Header() definisce il nome della funzione e i relativi parametri. Tieni presente che Header() non richiede parametri, in quanto le funzioni macro in Apps Script non necessitano di input. Le parentesi graffe racchiudono sempre il corpo di una funzione in Apps Script.

I codelab successivi di questa playlist spiegano le classi e i concetti coinvolti nella creazione della macro. Per il momento, puoi esaminare le seguenti descrizioni del codice per farti un'idea generale dei suoi componenti e del loro ruolo nella creazione della macro. Considera la prima riga:

var spreadsheet = SpreadsheetApp.getActive(); 

Qui, getActive() restituisce un oggetto che rappresenta il file di Fogli attivo corrente e lo imposta sulla nuova variabile spreadsheet.

var sheet = spreadsheet.getActiveSheet(); sheet.getRange(     spreadsheet.getCurrentCell().getRow(),     1, 1, sheet.getMaxColumns()).activate(); 

Queste righe corrispondono all'azione di fare clic sulla prima riga per evidenziarla. Questa operazione è chiamata attivazione. La prima riga memorizza il foglio corrente nella variabile sheet, mentre la seconda riga recupera l'intera prima riga utilizzando il metodo getRange() e poi chiama activate() per attivarlo. La prima riga viene specificata utilizzando i numeri di riga e colonna specifici. La chiamata spreadsheet.getCurrentCell().getRow() restituisce il numero della riga corrente, mentre sheet.getMaxColumns() restituisce il numero massimo di colonne nel foglio.

spreadsheet.getActiveRangeList().setBackground('#4c1130') .setFontColor('#ffffff') .setFontWeight('bold'); 

Questo frammento di codice diventa più complesso. Per chiamare in modo efficiente i metodi con spreadsheet, il codice impila tre metodi su getActiveRangeList() per evitare che il codice chiami in modo ridondante questo metodo spreadsheet più di una volta. Man mano che scrivi altro codice utilizzando Apps Script, acquisirai maggiore familiarità con questa convenzione di chiamare più metodi su una classe (nota anche come concatenazione di metodi). Per il momento, puoi leggere quanto segue per brevi spiegazioni su ciascun metodo nel blocco di codice:

• getActiveRangeList() restituisce l'RangeList attivo corrente in spreadsheet. In questo caso, si tratta semplicemente della prima riga attivata dalla riga precedente.
• Entrambi i metodi setBackground(color) e setFontColor(color) modificano gli attributi di colore delle celle nell'intervallo attivo.
• setFontWeight(fontWeight) regola lo spessore del carattere per le celle nell'intervallo attivo.

Infine, l'ultima riga blocca la prima riga della macro:

spreadsheet.getActiveSheet().setFrozenRows(1); 

Questo è lo script che hai generato quando hai registrato la macro. Non preoccuparti di termini o metodi sconosciuti menzionati sopra. La descrizione ha lo scopo di farti riflettere su alcune delle idee su cui si concentra Apps Script in una tipica funzione macro e sugli argomenti che verranno approfonditi nei futuri codelab.

La sezione successiva si concentra sulla manipolazione del codice della funzione Header() per mostrare come utilizzare l'editor di script per personalizzare ulteriormente le macro.

Personalizzare le macro con Apps Script

L'editor di Apps Script mostra la macro che hai creato in precedenza in Fogli Google. Modificando i contenuti del corpo della funzione, puoi personalizzare ulteriormente le istruzioni della macro per eseguire azioni diverse o aggiuntive. I seguenti esercizi mostrano vari modi per manipolare le macro con l'editor di script.

Modificare le celle interessate

Supponiamo che tu voglia modificare la macro in modo che influisca solo sulle prime 10 colonne della prima riga anziché sull'intera riga. Puoi eliminare la macro e registrarla di nuovo. Tuttavia, utilizzando l'editor Apps Script, puoi apportare queste modifiche direttamente. Ecco un modo per farlo:

1. Nell'editor di script, sostituisci sheet.getMaxColumns() con 10. Questa modifica cambia l'intervallo di celle interessate dalla macro nel foglio di lavoro.

/** @OnlyCurrentDoc */  function Header(){   var spreadsheet = SpreadsheetApp.getActive();   var sheet = spreadsheet.getActiveSheet();   sheet.getRange(     spreadsheet.getCurrentCell().getRow(),     1, 1, 10).activate();     /* sheet.getMaxColumns() replaced with 10.*/   spreadsheet.getActiveRangeList().setBackground('#4c1130')   .setFontColor('#ffffff')   .setFontWeight('bold');   spreadsheet.getActiveSheet().setFrozenRows(1); } 

2. Per salvare il copione, fai clic su Salva .
3. Per rinominare il progetto, inserisci "Macro e funzioni personalizzate" come nuovo nome del progetto e fai clic su Rinomina.
4. Per creare un foglio, in Fogli, fai clic su Aggiungi foglio .

5. Nell'editor di script, seleziona Header dall'elenco delle funzioni e fai clic su Esegui.

Nel nuovo foglio dovresti vedere il seguente risultato:

Se modifichi l'intervallo attivo o di destinazione, la macro ora influisce solo su una parte della prima riga. Molti metodi Apps Script accettano un intervallo o la notazione A1 come parametro per specificare le celle su cui agire.

Ora scopriamo come personalizzare i colori delle macro.

Modificare i colori della macro

Per aiutarti a progettare la combinazione di colori delle macro o di altri elementi in Fogli, Apps Script può modificare il colore di riempimento o del testo di un intervallo. Segui le istruzioni riportate di seguito per scoprire come personalizzare i colori della macro.

Queste istruzioni si concentrano sulla modifica del colore di sfondo della macro:

1. In Fogli, torna al foglio che contiene i dati originali (Foglio1).
2. Fai clic sulla prima riga per evidenziarla.
3. Nell'editor di script, sostituisci il colore di sfondo #4c1130 con #afeeee. Questi valori rappresentano colori diversi utilizzando la notazione a tre esadecimale.

/** @OnlyCurrentDoc */  function Header(){   var spreadsheet = SpreadsheetApp.getActive();   var sheet = spreadsheet.getActiveSheet();   sheet.getRange(     spreadsheet.getCurrentCell().getRow(),     1, 1, 10).activate();   spreadsheet.getActiveRangeList().setBackground('#afeeee')     /* #4c1130 replaced with #afeeee.*/   .setFontColor('#ffffff')   .setFontWeight('bold');   spreadsheet.getActiveSheet().setFrozenRows(1); } 

4. Per salvare il copione, fai clic su Salva .
5. Dall'elenco delle funzioni, seleziona Header e fai clic su Esegui.

In Fogli, il riempimento dello sfondo delle prime 10 colonne della prima riga viene ricolorato in un colore turchese personalizzato:

Se cambi la notazione del colore esadecimale nei parametri di setBackground(color) da #4c1130 (magenta scuro 3) a #afeeee (turchese chiaro, un'opzione non accessibile nel menu dei colori predefiniti di Fogli), modifichi l'attributo colore del colore di sfondo della macro.

Ora hai modificato il set di colori di sfondo impostato dalla macro. Se vuoi cambiare anche il colore del testo, modifica il secondo codice colore.

1. In Fogli, fai clic sulla prima riga per assicurarti che sia ancora evidenziata.
2. Nell'editor di script, sostituisci il colore del carattere #ffffff con #191970. In questo modo, la macro imposta un colore del carattere blu navy.

/** @OnlyCurrentDoc */  function Header(){   var spreadsheet = SpreadsheetApp.getActive();   var sheet = spreadsheet.getActiveSheet();   sheet.getRange(     spreadsheet.getCurrentCell().getRow(),     1, 1, 10).activate();   spreadsheet.getActiveRangeList().setBackground('#afeeee')   .setFontColor('#191970')/* #ffffff replaced with #191970.*/   .setFontWeight('bold');   spreadsheet.getActiveSheet().setFrozenRows(1); } 

3. Per salvare il copione, fai clic su Salva .
4. Dall'elenco delle funzioni, seleziona Header e fai clic su Esegui.

Torna a Fogli per vedere che il colore del testo della riga di intestazione ora è blu scuro.

Ora hai visto come le macro sono in realtà azioni di Fogli registrate come codice Apps Script. Nella sezione successiva, puoi scoprire un altro modo in cui Apps Script può aiutarti a lavorare con Fogli Google: le funzioni personalizzate.

5. Codifica il tuo primo script: funzioni personalizzate

Come la maggior parte delle applicazioni per fogli di lavoro, Fogli Google dispone di diverse funzioni di formula integrate, ad esempio =SUM(), che consentono di eseguire calcoli rapidi sui dati dei fogli di lavoro. Le funzioni personalizzate sono semplicemente funzioni che specifichi utilizzando Apps Script. Una volta definita una funzione personalizzata, puoi utilizzarla ovunque nel foglio di lavoro, proprio come una funzione integrata.

Questa sezione mostra come creare una funzione personalizzata in Apps Script che esegue una conversione monetaria.

Creare un file di script

Utilizzando lo stesso foglio di lavoro e lo stesso progetto di script della sezione Macro, segui queste istruzioni per scoprire come creare un nuovo script (che potrai utilizzare in un secondo momento per creare la tua prima funzione personalizzata):

1. Per creare un file Apps Script, torna all'editor di script.
2. Accanto a File, fai clic su Aggiungi un file > Script.
3. Assegna al nuovo file di script il nome customFunctions e premi Invio. Apps Script aggiunge automaticamente un'estensione .gs al nome del file di script.

Nell'editor viene visualizzata una nuova scheda denominata customFunctions.gs.

Ora che hai creato uno script specifico per le funzioni personalizzate, puoi riempirlo con il codice.

Converti dollari statunitensi in franchi svizzeri

Supponiamo di voler modificare i dati di "I 10 film con gli incassi più alti del 2018" per mostrare non solo i valori lordi mondiali in dollari statunitensi, ma anche in franchi svizzeri. Con le funzioni personalizzate, puoi farlo facilmente. Il seguente esercizio mostra come creare una funzione personalizzata per convertire matematicamente i valori in dollari in valori in franchi.

Prima di poter scrivere la tua prima funzione personalizzata, modifica il set di dati per consentire alla funzione di mostrare un output corretto. Per:

1. In Fogli, fai clic con il tasto destro del mouse sulla colonna H.
2. Nel menu visualizzato, fai clic su Inserisci 1 a destra.

3. Etichetta la colonna "Worldwide_Gross (Swiss francs)" (Incasso mondiale (franchi svizzeri)) nella cella I1.

Ora hai una colonna in cui puoi memorizzare i risultati della funzione personalizzata di conversione. Successivamente, puoi utilizzare l'editor di script per creare la tua prima funzione personalizzata.

4. In customFunctions.gs, sostituisci il codice per myFunction() con il seguente codice:

/**  * Converts US dollars to Swiss francs.  *  * @param {number} dollars The total number of dollars.  * @return {number} swissFrancs The converted total of Swiss francs.  * @customfunction  */ function USDTOCHF(dollars){   var swissFrancs = dollars * .99;    return swissFrancs; } 

Questo è il codice che convertirà i dollari statunitensi in franchi svizzeri. Prova le istruzioni riportate di seguito e scopri come eseguire una funzione personalizzata nei fogli.

5. Per salvare il copione, fai clic su Salva .
6. In Fogli, seleziona la cella I2.
7. Nella barra delle funzioni, inserisci =USDTOCHF(H2).

Per applicare la formula al resto delle celle della colonna:

8. Sposta il cursore nell'angolo in basso a destra della cella I2 e seleziona il piccolo riquadro blu (il cursore dovrebbe trasformarsi in quando punti al riquadro blu).
9. Trascina la casella blu verso il basso per evidenziare l'intervallo I3:I11.

La colonna I ora elenca le conversioni in franchi svizzeri dei valori in dollari statunitensi nella colonna H.

Congratulazioni, hai creato la tua prima funzione personalizzata. La sezione successiva spiega il codice che compone USDTOCHF().

Analisi di USDTOCHF()

I commenti iniziali descrivono in dettaglio lo scopo del codice:

/**  * Converts US dollars to Swiss francs.  *  * @param {number} dollars The total number of dollars.  * @return {number} swissFrancs The provided value in Swiss francs.  * @customfunction  */ 

Blocchi di commenti come questo vengono utilizzati spesso nella programmazione per spiegare cosa fanno le funzioni.

In questo commento puoi identificare due parti: la descrizione della funzione (per convertire i dollari in franchi) e le annotazioni che descrivono i parametri e il tipo restituito della funzione.

Con le annotazioni, Apps Script utilizza JSDoc per aiutarti a documentare e creare suggerimenti di completamento automatico per il tuo codice. Di seguito puoi leggere in che modo ogni annotazione utilizzata in USDTOCHF() ti aiuta nello sviluppo di Apps Script:

• @param: puoi utilizzare l'annotazione @param per descrivere ogni parametro passato alla funzione.
• @return: puoi utilizzare l'annotazione @return per descrivere cosa restituisce la funzione.
• @customfunction: devi sempre aggiungere @customfunction nel commento del documento di qualsiasi funzione personalizzata. Questa annotazione indica a Fogli di completare automaticamente la tua funzione personalizzata proprio come Fogli completa automaticamente le funzioni integrate quando inserisci il nome di una funzione in una cella, come mostrato di seguito:

Nota che il testo visualizzato nel popup di completamento automatico corrisponde esattamente al testo della descrizione inserito nel blocco di commento. Puoi semplificare l'utilizzo delle funzioni personalizzate assicurandoti che le descrizioni che crei siano ben scritte e complete.

Successivamente, concentrati sul codice nella funzione USDTOCHF():

function USDTOCHF(dollars){   var swissFrancs = dollars * .99;    return swissFrancs; } 

Come accennato in precedenza, USDTOCHF() prende la variabile numerica dollari, la moltiplica per un tasso di cambio fisso e restituisce un valore convertito in franchi svizzeri nella variabile numerica swissFrancs. Il parametro di input è il valore contenuto nella cella specificata quando aggiungi la funzione personalizzata a una cella. In questo esempio, gli importi in dollari inseriti provengono dalla colonna H. Il valore di output swissFrancs viene inserito nella cella della funzione (colonna I in questo esempio).

Le funzioni personalizzate possono funzionare con valori numerici o stringhe, come vedrai nella sezione successiva.

Concatenare un prefisso di stringa

Supponiamo che tu voglia che l'output numerico della funzione USDTOCHF() includa il prefisso del franco svizzero CHF. Puoi farlo con Apps Script utilizzando l'operatore di concatenazione (+),, come mostrato nelle istruzioni riportate di seguito:

1. Nell'editor di script, aggiorna l'annotazione @return in modo che restituisca una stringa anziché un numero.
2. Modifica return swissFrancs in return 'CHF' + swissFrancs.

L'operatore + aggiunge la stringa CHF all'inizio del valore contenuto in swissFrancs. Il codice dovrebbe ora avere il seguente aspetto:

/**  * Converts US dollars to Swiss francs.  *  * @param {number} dollars The total number of dollars.  * @return {string} swissFrancs The provided value in Swiss francs.  * @customfunction  */ function USDTOCHF(dollars){   var swissFrancs = dollars * .99;   return 'CHF' + swissFrancs; } 

3. Per salvare il copione, fai clic su Salva .

La stringa del franco svizzero ora precede i valori della colonna I:

Ora la tua funzione personalizzata non solo converte i dollari statunitensi in franchi svizzeri, ma restituisce anche la valuta con un prefisso di stringa.

Avanzato: recupera dati esterni

Questo è un buon punto di partenza per una funzione personalizzata di base, ma questo esempio presuppone che il tasso di cambio da dollari a franchi svizzeri sia costante. Supponiamo invece di voler utilizzare il tasso di cambio attuale, in modo che ogni volta che il foglio viene ricaricato i valori vengano ricalcolati per rappresentare la conversione attuale. Per farlo, devi scoprire qual è il tasso di cambio attuale. Queste informazioni non sono facilmente disponibili in Fogli Google, ma fortunatamente puoi utilizzare Apps Script per ottenerle.

Puoi utilizzare un codice come quello riportato di seguito per ottenere il tasso di conversione attuale dei franchi svizzeri in dollari statunitensi:

function USDTOCHF(dollars){   // Gets a cache that is common to all users of the script.   var cache = CacheService.getScriptCache();    // Accesses the memory location (rates.CHF) of the script cache.   var rate = cache.get('rates.CHF');    // If a cache miss occurs, the program fetches the current   // CHF rate from an API and stores the rate in the cache   // for later convenience.   if (!rate) {     var response = UrlFetchApp.fetch('https://api.exchangeratesapi.io/latest?base=USD');     var result = JSON.parse(response.getContentText());     rate = result.rates.CHF;     cache.put('rates.CHF', rate);   }   // Converts dollars to CHF according to the latest rate.   var swissFrancs = dollars * rate;   // Returns the CHF value.   return 'CHF' + swissFrancs; } 

Questo codice recupera il tasso di cambio corrente da un server di informazioni finanziarie utilizzando un'API per il tasso di cambio di terze parti. Questa operazione viene eseguita utilizzando servizi Apps Script come UrlFetchApp e CacheService. Questi concetti avanzati non rientrano nell'ambito di questo codelab specifico, ma puoi iniziare a vedere la versatilità di Apps Script per automatizzare attività complesse in Fogli Google.

Linee guida per le funzioni personalizzate

Congratulazioni per aver completato gli esercizi per le funzioni personalizzate. Quando utilizzi le funzioni personalizzate nei tuoi progetti, è importante sapere che sono soggette a determinate limitazioni. Il seguente elenco riassume le limitazioni descritte in dettaglio nella guida Funzioni personalizzate in Fogli Google:

• Non creare funzioni personalizzate che richiedono l'autorizzazione dell'utente. Crea invece le tue funzioni personalizzate per svolgere attività più semplici come calcoli di dati di esempio, modifica del testo e così via. Vai a Utilizzo dei servizi Apps Script.
• Non assegnare a una funzione personalizzata lo stesso nome di un'altra funzione integrata e non terminare il nome con un trattino basso. Consulta le linee guida per l'assegnazione dei nomi.
• Non passare argomenti variabili a funzioni personalizzate. Puoi trasmettere alle funzioni personalizzate solo valori deterministici (fissi) come argomenti. Il passaggio di argomenti variabili, come il risultato di =RAND(), interromperà il funzionamento della funzione personalizzata. Consulta le linee guida per gli argomenti.
• Non creare funzioni che richiedono più di 30 secondi per essere completate. Se l'esecuzione richiede più tempo, si verifica un errore, quindi mantieni il codice della funzione semplice e con un ambito limitato. È meglio mantenere i calcoli eseguiti nelle funzioni personalizzate il più semplici possibile. Consulta le linee guida sui valori restituiti.

Ora puoi migliorare i tuoi fogli di lavoro utilizzando l'editor di script per lavorare con le macro e creare funzioni personalizzate. Nella sezione successiva, puoi rivedere ciò che hai imparato e cosa puoi fare per migliorare le tue competenze di scripting.

6. Conclusione

Hai completato il primo codelab di Nozioni di base di Apps Script con Fogli Google. Creando e modificando macro e funzioni personalizzate di Fogli, hai appreso i concetti di base di Apps Script. Puoi ampliare ulteriormente le tue conoscenze su Apps Script nel prossimo codelab.

Argomenti trattati

• Concetti di base di Apps Script.
• Come navigare nell'editor di script.
• Come creare e aggiornare le macro di Fogli.
• Come creare funzioni personalizzate per Fogli Google.

Passaggi successivi

Il codelab successivo di questa playlist presenta le classi e la terminologia principali del servizio Spreadsheet di Apps Script. Questo servizio ti consente di controllare con precisione i valori e la presentazione dei dati in Fogli Google utilizzando Apps Script.

Trova il prossimo codelab in Spreadsheets, Sheets, and Ranges.