Concetti fondamentali di Apps Script con Fogli Google n. 1: Macro e amp; Funzioni personalizzate

1. Ti diamo il benvenuto in Apps Script

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 snellindo le attività gravose o complesse in Google Workspace.

Le funzionalità di Apps Script includono:

• I servizi integrati di Apps Script ti consentono di leggere, aggiornare e manipolare i dati dell'applicazione Google Workspace con script.
• Puoi creare script utilizzando l'editor di codice integrato nel browser di Apps Script, senza dover installare o eseguire software di sviluppo di codice.
• Puoi progettare interfacce utente per gli editor di Google Workspace che ti consentono di attivare gli script direttamente da tali editor utilizzando voci di menu, finestre di dialogo e barre laterali.

Questa playlist del codelab su Nozioni di base di Apps Script con Fogli Google illustra le nozioni di base di Apps Script e su come utilizzarlo per migliorare l'esperienza in Fogli Google. Questo codelab è incentrato sull'insegnamento delle nozioni di base di Apps Script.

Il servizio Fogli di lavoro

Puoi utilizzare Apps Script per estendere i fogli Google in modo da risparmiare tempo e fatica. Apps Script fornisce il servizio di foglio di lavoro che consente agli script di interagire con i tuoi file di Fogli Google e con i dati che contengono. Puoi utilizzare questo servizio per automatizzare le seguenti attività comuni relative ai fogli di lavoro:

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

Obiettivi didattici

Questa playlist tratta tutti gli argomenti necessari per iniziare a utilizzare Apps Script con Fogli Google:

1. Macro e funzioni personalizzate
2. Fogli di lavoro, Fogli e intervalli
3. Utilizzo dei dati
4. Formattazione dei dati
5. Grafico e presentazione di dati in Presentazioni

I codelab in questa playlist sono pensati per essere letti in ordine, quindi inizia con 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 nel primo codelab di questa playlist. In questo codelab scoprirai le nozioni di base sull'utilizzo di Apps Script con Fogli Google. In particolare, questo codelab si concentra su due concetti chiave: macro e funzioni personalizzate.

Una macro è una serie di azioni registrate in Fogli Google. Dopo la registrazione, puoi attivare una macro per ripetere tali azioni in un secondo momento con un elemento del menu o una scorciatoia da tastiera. Puoi creare e aggiornare le tue macro in Fogli Google e nell'editor di codice Apps Script.

Nell'editor di codice di Apps Script puoi anche creare funzioni personalizzate. Come per le funzioni integrate in Fogli (come SUM o AVERAGE), puoi utilizzare Apps Script per scrivere funzioni personalizzate per operazioni semplici e di nicchia (come le conversioni o la 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.

Di seguito sono descritti i concetti e i requisiti di questo codelab.

Obiettivi didattici

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

Che cosa ti serve

• Familiarità con JavaScript
• Familiarità con Fogli Google
• Possibilità di leggere la notazione A1 di Fogli

Nota:Apps Script si basa su JavaScript. Se non hai mai utilizzato JavaScript, Codecademy offre un corso JavaScript introduttivo senza costi aggiuntivi. Sebbene questo corso non sia stato creato da Google, il corso dovrebbe coprire tutto ciò che devi sapere.

Hai completato le presentazioni. Vai alla sezione successiva per iniziare a utilizzare le macro.

3. Creare una macro in Fogli

In genere, quando lavori in fogli di lavoro, puoi entrare in un ciclo di azioni ripetitive, come copiare valori delle celle, formattare, creare formule e così via, il che può diventare noioso e generare errori. Per automatizzare le azioni ripetute, Fogli Google fornisce le macro. Le macro 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 rapida.

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

Prima di iniziare

Prima di continuare, ti servirà un foglio di lavoro con alcuni dati. Ne abbiamo fornito uno per te: fai clic su questo link per copiare la scheda tecnica, quindi su Crea una copia.

Una copia del foglio di lavoro di esempio che puoi utilizzare viene inserita nella cartella di Google Drive e denominata "Copia dei 10 film più redditizi" (2018)."

Creare una macro

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

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

Una volta avviata la registrazione, Fogli Google memorizza ogni azione eseguita all'interno del foglio di lavoro, ad esempio l'evidenziazione delle celle, l'aggiunta di dati, il passaggio a diversi fogli, la formattazione e così via. Queste azioni diventano lo "script' che viene ripetuto una volta salvata e attivata dalla macro in un secondo momento.

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

Termini chiave. Le macro possono utilizzare due tipi di riferimenti in Fogli per fare riferimento a celle specifiche. I riferimenti assoluti sono fissi nelle posizioni esatte registrate (ad esempio, cella A5), mentre i riferimenti relativi vengono applicati utilizzando la selezione corrente dell'utente come punto di partenza (ad esempio, la quarta cella in basso rispetto alla selezione corrente).

Questo codelab ti chiede di utilizzare riferimenti relativi per le macro.

4. Seleziona riga 1.

5. Cambia il colore del colore di riempimento della riga superiore da bianco a magenta scuro 3.

6. Cambia il colore del testo della riga superiore da nero a bianco.

7. Per formattare il testo in grassetto, premi Ctrl + B (o Cmd + B su macOS).
8. Per bloccare la riga superiore, 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 nella formattazione delle intestazioni.

Attiva 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. Segui gli esempi di input 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.

Nota: se utilizzi un account gmail.com, quando apri per la prima volta lo script potresti visualizzare anche una finestra di dialogo dell'app non verificata. Google lo utilizza per avvisare gli utenti che potrebbero utilizzare il codice di autori sconosciuti o non attendibili. Se vedi questa finestra di dialogo, puoi procedere poiché sei l'autore dello script. Segui le istruzioni sullo schermo per continuare ad autorizzare lo script. La procedura per ottenere questa autorizzazione è denominata autorizzazione.

6. Ripeti il Passaggio 4 per eseguire di nuovo la macro (autorizzando l'interruzione della prima esecuzione).

Complimenti, hai imparato ad applicare le macro in Fogli. Il foglio di lavoro deve 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 rendere le tue macro ancora più efficaci. Ecco il segreto: quando registri una macro, quello che stai davvero facendo è scrivere un 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 nel browser di Apps Script.

4. Macro nell'editor di script

Quando 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 le azioni nello stesso ordine.

Editor di script

Ora che hai creato una macro, puoi guardare il relativo 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 consente di scrivere il codice in Apps Script e di eseguire questi script sui server di Google.

Nota: le macro e gli script che stai creando in questo codelab sono allegati al file di Fogli Google su cui operano e sono accessibili in qualsiasi momento dal menu Estensioni > Fogli di Apps Script. Gli script allegati a un foglio Google come questo vengono chiamati contenitori dei container.

Analisi di macro.gs

Esamina lo script corrente. Fogli ha creato il file dello script macros.gs quando hai registrato la macro Header, inserendolo con una funzione Apps Script corrispondente denominata Header. Quando attivi la macro Header, Fogli esegue questa funzione.

Guarda l'immagine seguente per acquisire familiarità 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 sull'annotazione che influisce sull'autorizzazione:

/** @OnlyCurrentDoc */

La maggior parte degli script richiede all'utente alcune autorizzazioni prima di poter essere eseguite. Queste autorizzazioni controllano ciò che l'utente consente all'esecuzione dello script. Se il commento di @OnlyCurrentDoc è presente in un progetto di script, Apps Script richiede l'autorizzazione solo per accedere al foglio di lavoro corrente e aggiornarlo. Senza questo commento, Apps Script chiedeva l'autorizzazione ad accedere e ad aggiornare tutti i fogli di lavoro dell'utente. È sempre consigliabile includere questa annotazione quando si lavora con un solo file. Il macro recorder aggiunge automaticamente questo commento.

Per capire come Apps Script rappresenta le istruzioni della macro, osserva 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. Seguendo function, l'etichetta Header() definisce il nome della funzione e i relativi parametri. Tieni presente che Header() non richiede parametri poiché le funzioni delle macro in Apps Script non richiedono input. Le parentesi graffe racchiudono sempre il corpo di una funzione in Apps Script.

I codelab più successivi in questa playlist spiegano le classi e i concetti coinvolti nella creazione della macro. Per il momento, attieniti alle descrizioni del codice riportate di seguito per farti un'idea generale dei componenti e del ruolo che hanno nella creazione della macro. Prendi in considerazione la prima riga:

var spreadsheet = SpreadsheetApp.getActive();

In questo caso, getActive() restituisce un oggetto che rappresenta il file di foglio di lavoro attivo corrente in Fogli 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. denominato attivazione. La prima riga memorizza il foglio corrente nella variabile sheet, mentre la seconda occupa 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 di righe correnti, 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 i metodi in modo efficiente con spreadsheet, il codice impila tre metodi in getActiveRangeList() per evitare che il codice chiami in modo ridondante questo metodo spreadsheet più di una volta. Man mano che utilizzi il codice tramite Apps Script, acquisirai familiarità con questa convenzione per chiamare più metodi in un corso (noto anche come concatenamento di metodi). Per il momento, puoi leggere quanto segue per brevi spiegazioni su ciascun metodo nel blocco di codice:

• getActiveRangeList() restituisce l'attuale RangeList attivo in spreadsheet. In questo caso, è semplicemente la 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, la riga finale blocca la prima riga della macro:

spreadsheet.getActiveSheet().setFrozenRows(1);

E questo è lo script che hai generato quando hai registrato la tua macro. Non preoccuparti per i termini o i metodi sconosciuti che hai menzionato sopra. La descrizione ha lo scopo di farti riflettere su alcune delle idee su cui Apps Script si concentra in una tipica funzione macro e sugli argomenti che verranno trattati in futuro nei codelab.

La sezione seguente illustra come manipolare il codice della funzione Header() per mostrare come puoi utilizzare l'editor di script per personalizzare ulteriormente le macro.

Personalizzare le macro con Apps Script

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

Modificare le celle interessate

Supponi di voler modificare la tua macro in modo che abbia effetto solo sulle prime 10 colonne della prima riga anziché dell'intera riga. Puoi eliminare la macro e registrarla di nuovo. ma puoi utilizzare l'editor Apps Script direttamente. Ecco un modo per farlo:

1. Nell'editor di script, sostituisci sheet.getMaxColumns() con 10. Questa modifica modifica 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 lo script, 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 nell'elenco delle funzioni e fai clic su Esegui.

Nel nuovo foglio, dovresti vedere il seguente risultato:

Modificando l'intervallo attivo o target, la macro ora interessa solo parte della prima riga. Molti metodi Apps Script utilizzano un intervallo o una notazione A1 come parametro per specificare le celle su cui agire.

Ora impariamo a personalizzare i colori delle tue macro.

Modificare i colori della macro

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

Queste istruzioni sono incentrate sulla modifica del colore di sfondo della macro:

1. In Fogli, torna al foglio che contiene i dati originali (Foglio 1).
2. Fai clic sulla prima riga per evidenziarla.
3. Nell'editor di script, sostituisci il colore #4c1130 con #afeeee. Questi valori rappresentano colori diversi utilizzando la notazione 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 lo script, fai clic su Salva .
5. Nell'elenco delle funzioni, seleziona Header e fai clic su Esegui.

In Fogli, il colore di sfondo delle prime 10 colonne della prima riga diventa di colore turchese personalizzato:

Passando alla notazione colore esadecimale nei parametri di setBackground(color) da #4c1130 (magenta scuro 3) a #afeeee (turchese, un'opzione non accessibile in Fogli, menu colore predefinito), modifichi l'attributo colore del colore dello sfondo della macro.

Hai modificato il colore di sfondo impostato dalla tua macro. Se vuoi modificare 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 il colore del carattere blu scuro.

/** @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 lo script, fai clic su Salva .
4. Nell'elenco delle funzioni, seleziona Header e fai clic su Esegui.

Torna a Fogli per verificare che il colore del testo della riga di intestazione sia ora blu marino.

Ora hai visto come le macro sono effettivamente le azioni di Fogli registrate come codice Apps Script. Nella sezione successiva puoi vedere in che modo Apps Script può aiutarti a lavorare con Fogli Google: funzioni personalizzate.

5. Codifica il tuo primo script: funzioni personalizzate

Come per la maggior parte delle applicazioni per fogli di lavoro, Fogli Google offre diverse funzioni di formula integrate, come =SUM(), che consentono calcoli rapidi sui dati dei fogli di lavoro. Le funzioni personalizzate sono semplicemente funzioni che specifichi utilizzando Apps Script. Dopo aver definito una funzione personalizzata, puoi utilizzarla in qualsiasi punto del foglio di lavoro, proprio come una funzione integrata.

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

Crea un file dello script

Utilizzando lo stesso foglio di lavoro e progetto di script della sezione Macro, segui queste istruzioni per imparare a creare un nuovo script (che puoi utilizzare per creare la tua prima funzione personalizzata):

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

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

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

Converti dollari statunitensi in franchi svizzeri

Supponiamo di voler modificare i dati di "I 10 migliori film lordi 2018' per mostrare non solo i valori lordi in tutto il mondo, ma anche in franchi svizzeri. Le funzioni personalizzate ti consentono di farlo facilmente. Il seguente esercizio mostra come creare una funzione personalizzata per convertire matematicamente i valori in dollari in valori di franchi.

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

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

3. Etichetta la colonna "Worldwide_Gross (Swiss francs)" nella cella I1.

Ora disponi di una colonna per 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 codice seguente:

/**
 * 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 converte i dollari USA in franchi svizzeri. Prova a seguire le istruzioni riportate di seguito e scopri come eseguire una funzione personalizzata nei fogli.

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

Per applicare la formula alle altre celle della colonna:

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

Nella colonna I ora sono elencate le conversioni in franchi svizzeri dei valori in dollari USA nella colonna H.

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

Analisi di USDTOCHF()

I commenti iniziali indicano dettagliatamente la finalità 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
 */

I blocchi dei commenti come questo vengono utilizzati di frequente nella programmazione per spiegare le funzioni che svolgono.

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

Con le annotazioni, Apps Script utilizza JSDoc per aiutarti a documentare e creare suggerimenti di completamento automatico per il codice. Di seguito puoi trovare informazioni su come ogni annotazione utilizzata in USDTOCHF() ti aiuta a sviluppare app Apps Script:

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

Il testo visualizzato nel popup di completamento automatico corrisponde esattamente al testo descrittivo inserito nel blocco dei commenti. Puoi semplificare l'utilizzo delle funzioni personalizzate assicurandoti che le descrizioni create siano ben scritte e complete.

Quindi, concentrati sul codice nella funzione USDTOCHF():

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

Come accennato in precedenza, USDTOCHF() prende la variabile numerica in 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 si aggiunge la funzione personalizzata a una cella. In questo esempio, gli importi in dollari di input provengono dalla colonna H. Il valore di output swissFrancs viene posizionato nella cella della funzione (colonna I in questo esempio).

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

Concatena un prefisso di stringa

Supponi di volere che l'output numerico della funzione USDTOCHF() includa il prefisso franchi svizzero CHF. Puoi farlo con Apps Script utilizzando l'operatore di concatenazione (+), come mostrato nelle seguenti istruzioni:

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

L'operatore + aggiunge la stringa CHF all'inizio del valore contenuto in swissFrancs. Il tuo codice dovrebbe 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 lo script, fai clic su Salva .

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

La funzione personalizzata ora non solo converte i dollari USA in franchi svizzeri, ma restituisce anche una valuta con un prefisso di stringa.

Avanzata: recupera i dati esterni

Questo è un buon inizio per una funzione personalizzata di base, ma questo esempio presuppone che il tasso di cambio dai dollari ai franchi svizzeri sia costante. Supponiamo che tu voglia utilizzare il tasso di cambio corrente, in modo che ogni volta che il foglio viene ricaricato, i valori vengono ricalcolati per rappresentare la conversione corrente? Per farlo, avrai bisogno di un mezzo per scoprire qual è il tasso di cambio attuale. Queste informazioni non sono immediatamente disponibili in Fogli Google, ma fortunatamente puoi farlo utilizzando Apps Script.

Puoi utilizzare il codice riportato di seguito per ottenere l'attuale tasso di conversione 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 attuale da un server di informazioni finanziarie utilizzando un'API Rate di terze parti di terze parti. tramite l'utilizzo di servizi Apps Script come UrlFetchApp e CacheService. I concetti avanzati non rientrano in 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, hai completato gli esercizi per le funzioni personalizzate. Quando utilizzi le funzioni personalizzate nei progetti, è importante capire che hanno delle limitazioni. Il seguente elenco riepiloga le limitazioni descritte 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 di 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 o termina con il trattino basso. Consulta le Linee guida per i nomi.
• Non comunicare argomenti della variabile alle funzioni personalizzate. Puoi trasmettere valori deterministici (fissi) solo alle funzioni personalizzate come argomenti. Il passaggio di argomenti con variabili, come il risultato di =RAND(), comporterà l'interruzione della funzione personalizzata. Vedi le Linee guida per gli argomenti.
• Non creare funzioni il cui completamento richiede più di 30 secondi. Se l'errore è più lungo, mantieni il codice funzione semplice e limitato nell'ambito. È preferibile che i calcoli condotti in funzioni personalizzate siano il più semplici possibile. Visualizza 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 le conoscenze che hai appreso e le azioni da intraprendere per migliorare le tue competenze di scripting.

6. Conclusione

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

Hai trovato utile questo codelab?

Sì No

Cosa abbiamo trattato

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

Termini chiave

• Riferimento assoluto: alle celle esatte della registrazione viene applicata un'impostazione di registrazione delle macro che specifica le azioni macro registrate.
• Attivo (stato): indica il foglio di lavoro, il foglio, l'intervallo o la cella specificato che è l'utente del foglio di lavoro attualmente visualizzato o evidenziato.
• Apps Script: una piattaforma di sviluppo rapido di applicazioni basata su JavaScript, che consente di estendere le applicazioni Google Workspace e di automatizzare il lavoro in modo semplice e veloce.
• Autorizzazione: il processo con cui l'utente concede le autorizzazioni per consentire ad Apps Script di accedere ai dati dell'utente nei servizi Google pertinenti o che esegue altre azioni per conto dell'utente.
• Script associato a un contenitore: qualsiasi script associato e creato a partire da un documento Google Workspace, ad esempio un foglio Google o un documento Google.
• Funzioni personalizzate: formule semplici definite dall'utente in Apps Script utilizzate nei fogli di lavoro per operazioni semplici.
• JSDoc: linguaggio di markup utilizzato per scrivere note esplicative sui file di origine basati su JavaScript.
• Macro: abbreviazione di &macroinstruction". Una serie di azioni registrate in Fogli Google che puoi ripetere utilizzando una voce di menu o una scorciatoia da tastiera.
• Catene di metodi: un linguaggio di programmazione per richiamare più metodi su un oggetto, facendo affidamento sul fatto che ogni chiamata del metodo restituisce l'oggetto.
• Intervallo: un gruppo di una o più celle adiacenti all'interno di un foglio.
• Riferimento relativo: un'impostazione di registrazione delle macro che specifica le azioni macro registrate viene applicata alle celle in relazione alla selezione della cella corrente.
• Editor di script: l'editor di codice nel browser per Apps Script.
• Foglio. Una singola pagina di un foglio di lavoro (simile ai fogli di lavoro di Microsoft Excel). Talvolta utilizzato per fare riferimento a un file di Fogli Google su Google Drive.
• SpreadsheetApp: questa classe funge da classe principale per il servizio Foglio di lavoro e fornisce un punto di partenza per il codice che legge o manipola i dati di Fogli Google.
• Foglio di lavoro: un file di Fogli Google che si trova all'interno di Google Drive.
• Servizio Fogli di lavoro: un servizio Apps Script che consente agli script di creare, accedere e modificare i file di Fogli Google.

Scopri di più su Apps Script nella documentazione relativa ad Apps Script.

Passaggi successivi

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

Trova il prossimo codelab su Fogli di lavoro, Fogli e Intervalli.