1. Introduzione
Ti diamo il benvenuto nella quinta parte della playlist di codelab Fundamentals of Apps Script con Fogli Google. Questo codelab ti insegna a utilizzare il servizio Fogli di lavoro in Apps Script per creare un grafico di un set di dati. Scoprirai anche come utilizzare il servizio Presentazioni per esportare il grafico in una nuova presentazione in Presentazioni Google.
Obiettivi didattici
- Come creare un grafico a linee con Apps Script.
- Come esportare i grafici in un nuovo file di Presentazioni.
- Come presentare le finestre di dialogo all'utente in Fogli.
Prima di iniziare
Questo è il quinto codelab della playlist Nozioni di base di Apps Script con Fogli Google. Prima di iniziare questo codelab, assicurati di completare i precedenti:
- Macro e funzioni personalizzate
- Fogli di lavoro, fogli e intervalli
- Utilizzare i dati
- Formattazione dei dati
Che cosa ti serve
- Una conoscenza degli argomenti di base di Apps Script esplorati nei codelab precedenti di questa playlist.
- Familiarità di base con l'editor di Apps Script
- Familiarità di base con Fogli Google
- Possibilità di leggere i fogli Notazione A1
- Familiarità di base con JavaScript e la relativa classe
String
2. Configura
Prima di continuare, devi avere un foglio di lavoro con alcuni dati. Come in precedenza, abbiamo fornito un foglio dati che puoi copiare per questi esercizi. Procedi in questo modo:
- Fai clic su questo link per copiare il foglio dati, quindi su Crea una copia. Il nuovo foglio di lavoro viene inserito nella cartella Google Drive e denominato "Copia di Date e tassi di cambio in USD".
- Fai clic sul titolo del foglio di lavoro e modificalo da "Copia di Date e tassi di cambio in USD" a "Date e tassi di cambio in USD". Il foglio dovrebbe avere questo aspetto, con alcune informazioni di base sui diversi tassi di cambio del dollaro statunitense in date diverse:
- Per aprire l'editor di script, fai clic su Estensioni > Apps Script.
Per farti risparmiare tempo, abbiamo incluso un po' di codice per configurare un menu personalizzato in questo foglio di lavoro. Potresti aver visto il menu quando hai aperto la copia del foglio di lavoro:
Con questo foglio di lavoro e questo progetto, puoi iniziare il codelab. Passa alla sezione successiva per iniziare a scoprire i grafici e i trigger basati sul tempo.
3. Creare un grafico in Fogli con Apps Script
Supponiamo che tu voglia progettare un grafico specifico per visualizzare un set di dati. Puoi utilizzare Apps Script per creare, modificare e inserire grafici in Fogli Google. Quando un grafico è contenuto in un foglio di lavoro, viene chiamato grafico incorporato.
I grafici vengono utilizzati per visualizzare una o più serie di dati. Per i grafici incorporati, i dati presentati provengono in genere dal foglio di lavoro. In genere, l'aggiornamento dei dati nel foglio di lavoro comporta l'aggiornamento automatico anche del grafico.
Puoi utilizzare Apps Script per creare grafici personalizzati incorporati da zero o per aggiornare i grafici esistenti. Questa sezione introduce le nozioni di base per la creazione di grafici incorporati in Fogli con Apps Script e il servizio Spreadsheet.
Implementazione
Nella tua copia del foglio di lavoro dei dati, il set di dati "Date e tassi di cambio" mostra i tassi di cambio (per 1 dollaro statunitense) di diverse valute in date diverse. Implementerai una funzione Apps Script che crea un grafico per visualizzare una parte di questi dati.
Procedi in questo modo:
- Nell'editor di Apps Script, aggiungi la seguente funzione alla fine dello script
Code.gsdel progetto di script, dopo la funzioneonOpen():
/**
* Creates and inserts an embedded
* line chart into the active sheet.
*/
function createEmbeddedLineChart() {
var sheet = SpreadsheetApp.getActiveSheet();
var chartDataRange = sheet.getRange(
'Dates and USD Exchange Rates dataset!A2:F102');
var hAxisOptions = {
slantedText: true,
slantedTextAngle: 60,
gridlines: {
count: 12
}
};
var lineChartBuilder = sheet.newChart().asLineChart();
var chart = lineChartBuilder
.addRange(chartDataRange)
.setPosition(5, 8, 0, 0)
.setTitle('USD Exchange rates')
.setNumHeaders(1)
.setLegendPosition(Charts.Position.RIGHT)
.setOption('hAxis', hAxisOptions)
.setOption("useFirstColumnAsDomain", true)
.build();
sheet.insertChart(chart);
}
- Salva il progetto di script.
Revisione del codice
Il codice che hai aggiunto implementa la funzione chiamata dalla voce di menu Grafico "Set di dati Tassi di cambio USD e date" per creare un grafico a linee di base. Esaminiamo il codice.
Le prime righe configurano le seguenti tre variabili:
sheet: un riferimento al foglio attivo corrente.chartDataRange: l'intervallo di dati che vogliamo visualizzare. Il codice utilizza la notazione A1 per specificare che l'intervallo copre le celle da A2 a F102 nel foglio denominato Set di dati Tassi di cambio USD e date. Assegnando un nome specifico al foglio, ci assicuriamo che la voce di menu funzioni anche se è attivo un altro foglio, poiché l'intervallo copre sempre la posizione dei dati. A partire dalla riga 2, includiamo le intestazioni di colonna e rappresentiamo graficamente solo le 100 date (righe) più recenti.hAxisOptions: un oggetto JavaScript di base che include alcune informazioni sulle impostazioni utilizzate dal codice per configurare l'aspetto dell'asse orizzontale. Nello specifico, imposta le etichette di testo dell'asse orizzontale con un'inclinazione di 60 gradi e il numero di linee della griglia verticale a 12.
La riga successiva crea un oggetto generatore di grafici a linee. I grafici incorporati in Apps Script vengono creati utilizzando un pattern di progettazione Builder. Una spiegazione completa di questo pattern di progettazione non rientra nell'ambito di questo codelab, quindi per ora ti basta sapere che il servizio Spreadsheet fornisce diverse classi EmbeddedChartBuilder. Per creare un grafico, il codice crea prima un oggetto generatore di grafici incorporato, utilizza i relativi metodi per definire le impostazioni del grafico e poi chiama un metodo build() per creare l'oggetto EmbeddedChart finale. Il codice non modifica mai direttamente l'oggetto EmbeddedChart, poiché tutta la configurazione del grafico viene gestita tramite le classi del builder.
Il servizio Fogli fornisce una classe EmbeddedChartBuilder padre e più classi builder secondarie (ad esempio EmbeddedLineChartBuilder) che ereditano da essa. Le classi secondarie consentono ad Apps Script di fornire i metodi di configurazione dei grafici dei builder applicabili solo a determinati tipi di grafici. Ad esempio, la classe EmbeddedPieChartBuilder fornisce un metodo set3D() applicabile solo ai grafici a torta.
Nel codice, questa riga crea la variabile dell'oggetto builder lineChartBuilder:
var lineChartBuilder = sheet.newChart().asLineChart();
Il codice chiama il metodo Sheet.newChart() per creare un oggetto EmbeddedChartBuilder, quindi utilizza EmbeddedChartBuilder.asLineChart() per impostare il tipo di builder su EmbeddedLineChartBuilder.
Il codice crea quindi il grafico utilizzando lineChartBuilder. Questa parte del codice è solo una serie di chiamate di metodi per definire le impostazioni del grafico, seguita da una chiamata build() per creare il grafico. Come hai visto nei codelab precedenti, il codice utilizza l'incatenamento dei metodi per mantenere il codice leggibile. Ecco cosa fanno le chiamate al metodo:
addRange(range): definisce l'intervallo di dati visualizzato nel grafico.setPosition(anchorRowPos, anchorColPos, offsetX, offsetY): determina dove viene posizionato il grafico nel foglio. Qui, il codice inserisce l'angolo in alto a sinistra del grafico nella cella H5.setTitle(title): imposta il titolo del grafico.setNumHeaders(headers): determina quante righe o colonne nell'intervallo di dati devono essere trattate come intestazioni. In questo caso, il codice utilizza la prima riga dell'intervallo di dati come intestazioni, il che significa che il testo di questa riga viene utilizzato come etichette per le singole serie di dati nel grafico.setLegendPosition(position): sposta la legenda del grafico sul lato destro del grafico. Questo metodo utilizza l'enumerazione Charts.Position come parametro.setOption(option, value): imposta le opzioni del grafico complesso. In questo caso, il codice imposta l'opzionehAxissull'oggettohAxisOptions. Esistono diverse opzioni che puoi impostare utilizzando questo metodo. Le opzioni e i valori possibili per ogni tipo di grafico sono documentati nella raccolta di grafici dell'API Charts. Ad esempio, le opzioni che puoi impostare per i grafici a linee sono documentate in Opzioni di configurazione del grafico a linee. Il metodosetOption(option, value)è un argomento avanzato, quindi ti consigliamo di non utilizzarlo finché non avrai più familiarità con la creazione di grafici in Apps Script.build(): crea e restituisce un oggettoEmbeddedChartutilizzando le impostazioni precedenti.
Infine, il codice chiama Sheet.insertChart(chart) per inserire il grafico creato nel foglio attivo.
Risultati
Per vedere la funzione di formattazione in azione:
- Se non l'hai ancora fatto, salva il progetto di script nell'editor di Apps Script.
- Fai clic sulla voce di menu Presenta set di dati > Grafico "Set di dati Tassi di cambio USD e date".
Lo script ora posiziona un nuovo grafico a destra dei dati:
Congratulazioni, hai creato un grafico a linee incorporato con Apps Script. La sezione successiva ti insegna come esportare il grafico in Presentazioni Google.
4. Esportare i grafici in Presentazioni
Uno dei grandi punti di forza di Apps Script è che consente di spostare facilmente i dati da un'applicazione Google Workspace a un'altra. La maggior parte di queste applicazioni dispone di un servizio Apps Script dedicato, simile al servizio fogli di lavoro. Ad esempio, Gmail ha il servizio Gmail, Documenti Google ha il servizio Documenti e Presentazioni Google ha il servizio Presentazioni. Con tutti questi servizi integrati, puoi estrarre i dati da un'applicazione, elaborarli e scrivere il risultato in un'altra.
In questa sezione imparerai a esportare ogni grafico incorporato in un foglio di lavoro Google in un nuovo file di Presentazioni Google. Vedrai anche due modi per mostrare i messaggi personalizzati degli utenti in Fogli.
Implementazione
Qui implementerai la funzione chiamata dalla voce di menu Presenta set di dati > Esporta grafici in Presentazioni. Procedi in questo modo:
- Nell'editor di Apps Script, aggiungi la seguente funzione alla fine dello script
Code.gsdel progetto di script, dopo la funzionecreateEmbeddedLineChart():
/**
* Create a Slides presentation and export
* all the embedded charts in this spreadsheet
* to it, one chart per slide.
*/
function exportChartsToSlides() {
var ss = SpreadsheetApp.getActiveSpreadsheet();
// Fetch a list of all embedded charts in this
// spreadsheet.
var charts = [];
var sheets = ss.getSheets();
for (var i = 0; i < sheets.length; i++) {
charts = charts.concat(sheets[i].getCharts());
}
// If there aren't any charts, display a toast
// message and return without doing anything
// else.
if (charts.length == 0) {
ss.toast('No charts to export!');
return;
}
// Create a Slides presentation, removing the default
// title slide.
var presentationTitle =
ss.getName() + " Presentation";
var slides = SlidesApp.create(presentationTitle);
slides.getSlides()[0].remove();
// Add charts to the presentation, one chart per slide.
var position = {left: 40, top: 30};
var size = {height: 340, width: 430};
for (var i = 0; i < charts.length; i++) {
var newSlide = slides.appendSlide();
newSlide.insertSheetsChart(
charts[i],
position.left,
position.top,
size.width,
size.height);
}
// Create and display a dialog telling the user where to
// find the new presentation.
var slidesUrl = slides.getUrl();
var html = "<p>Find it in your home Drive folder:</p>"
+ "<p><a href=\"" + slidesUrl + "\" target=\"_blank\">"
+ presentationTitle + "</a></p>";
SpreadsheetApp.getUi().showModalDialog(
HtmlService.createHtmlOutput(html)
.setHeight(120)
.setWidth(350),
"Created a presentation!"
);
}
- Salva il progetto di script.
Revisione del codice
Questo codice potrebbe essere più breve del previsto. Esaminiamo il suo funzionamento suddividendo il codice in cinque sezioni:
1: Ottieni le classifiche
Le prime righe cercano nel foglio di lavoro attivo tutti i grafici incorporati e li raccolgono nell'array charts. Queste righe utilizzano il metodo Spreadsheet.getSheets() e il metodo Sheet.getCharts() per ottenere elenchi di fogli e grafici. Il metodo JavaScript Array.concat() viene utilizzato per aggiungere l'elenco dei grafici di ogni foglio a charts.
2. Controlla che siano presenti grafici da esportare
Il codice verifica se ci sono grafici da esportare. Vogliamo evitare di creare una presentazione vuota, quindi se non ci sono grafici, il codice crea un messaggio di notifica utilizzando Spreadsheet.toast(message). Si tratta di una piccola finestra di dialogo "sbirciata" che viene visualizzata nell'angolo in basso a destra di Fogli, rimane per alcuni secondi e poi scompare:
Se non ci sono grafici da esportare, il codice crea il messaggio di notifica e termina senza fare altro. Se ci sono grafici da esportare, il codice continua a creare una presentazione nelle righe successive.
3. Crea una presentazione
La variabile presentationTitle viene creata per contenere il nome del file della nuova presentazione. È impostato come nome del foglio di lavoro, con " Presentation" concatenato alla fine. Il codice chiama quindi il metodo del servizio Presentazioni SlidesApp.create(name) per creare una presentazione.
Le nuove presentazioni vengono create con una sola slide vuota. Non vogliamo che compaia nella presentazione, quindi il codice lo rimuove con Presentation.getSlides() e Slide.remove().
4. Esportare i grafici
Nella sezione successiva, il codice definisce position e size degli oggetti JavaScript per impostare la posizione dei grafici importati nella slide e le dimensioni del grafico (in pixel).
Il codice scorre ogni grafico nell'elenco dei grafici. Per ogni grafico, viene creato un newSlide con Presentation.appendSlide(), aggiungendo la slide alla fine della presentazione. Il metodo Slide.insertSheetsChart(sourceChart, left, top, width, height) viene utilizzato per importare il grafico nella slide con i valori position e size specificati.
5. Condividi la posizione della presentazione
Infine, il codice deve indicare all'utente la posizione del nuovo file di presentazione, preferibilmente con un link su cui può fare clic per aprirlo. A questo scopo, il codice utilizza il servizio HTML di Apps Script per creare una finestra di dialogo modale personalizzata. Le finestre di dialogo modali (note anche come finestre di dialogo personalizzate in Apps Script) sono finestre che vengono visualizzate sopra l'interfaccia di Fogli. Quando vengono visualizzate, le finestre di dialogo personalizzate impediscono all'utente di interagire con Fogli.
Per creare una finestra di dialogo personalizzata, il codice deve contenere l'HTML che ne definisce i contenuti. Questo valore viene fornito nella variabile html. I contenuti includono un breve paragrafo e un collegamento ipertestuale. Il link ipertestuale è la variabile presentationTitle, collegata all'URL della presentazione fornito da Presentation.getUrl(). L'hyperlink utilizza anche l'attributo target="_blank", in modo che la presentazione venga aperta in una nuova scheda del browser anziché all'interno della finestra di dialogo.
Il codice HTML viene analizzato in un oggetto HtmlOutput dal metodo HtmlService.createHtmlOutput(html). L'oggetto HtmlOutput consente al codice di impostare le dimensioni della finestra di dialogo personalizzata con HtmlOutput.setHeight(height) e HtmlOutput.setWidth(width).
Una volta creato htmlOutput, il codice utilizza il metodo Ui.showModalDialog(htmlOutput, title) per visualizzare la finestra di dialogo con il titolo specificato.
Risultati
Ora che hai implementato la seconda voce di menu, puoi vederla in azione. Per testare la funzione exportChartsToSlides():
- Se non l'hai ancora fatto, salva il progetto di script nell'editor di Apps Script.
- Apri il foglio di lavoro e fai clic sulla voce di menu Presenta set di dati > Grafico "Set di dati Tassi di cambio USD e date" per creare un grafico da esportare. Verrà visualizzato ancorato alla cella H5 nel foglio attivo.
- Fai clic sulla voce di menu Presenta set di dati > Esporta grafici in Presentazioni. Potrebbe essere necessario autorizzare nuovamente lo script.
- Dovresti vedere lo script elaborare la richiesta e visualizzare la finestra di dialogo personalizzata.
- Per aprire il nuovo file di Presentazioni, fai clic sul link Presentazione con date e tassi di cambio in dollari statunitensi:
Se vuoi, puoi anche aggiungere altri grafici al foglio di lavoro e selezionare di nuovo la voce di menu per creare una presentazione con più slide.
Ora puoi esportare i grafici creati in Fogli in un file di Presentazioni. Puoi anche scrivere codice per creare una finestra di dialogo personalizzata.
Hai completato l'ultimo esercizio di questo codelab. Passa alla sezione successiva per rivedere ciò che hai imparato.
5. Conclusione
Congratulazioni, hai completato questo codelab e l'intera playlist del codelab Fundamentals of Apps Script with Google Sheets. Puoi utilizzare i principi insegnati in questa playlist per ampliare la tua esperienza con Fogli e per esplorare le funzionalità di Apps Script.
Hai trovato utile questo codelab?
Cosa hai imparato
- Come creare un grafico a linee incorporato con Apps Script.
- Come presentare messaggi di notifica e finestre di dialogo personalizzate a un utente in Fogli.
- Come esportare un grafico in una nuova presentazione.
Passaggi successivi
Hai completato questa playlist. Tuttavia, c'è ancora molto da imparare su Apps Script.
Consulta queste risorse:
- Documentazione per sviluppatori di Apps Script
- Guide di Apps Script
- Documentazione di riferimento di Apps Script
- Domande su Apps Script su Stack Overflow
- Esempi di codice Apps Script su GitHub
Buona creazione di script!