Un'applicazione utile dell'API Google Slides è l'unione delle informazioni di una o più origini dati in un file di Presentazioni basato su un modello.
Questa pagina descrive come prendere i dati da un'origine esterna e inserirli in un file di presentazione modello esistente. Il concetto è simile a quello di una stampa unione che utilizza un elaboratore di testi e un foglio di lavoro.
Esistono diversi motivi per cui questo approccio è utile:
I designer possono perfezionare facilmente il design di una presentazione utilizzando l'editor di Presentazioni Google. È molto più semplice che ottimizzare i parametri dell'app per impostare il design della slide visualizzata.
La separazione dei contenuti dalla presentazione è un principio di progettazione ben noto con molti vantaggi.
Una ricetta di base
Ecco un esempio di come utilizzare l'API Slides per unire i dati in una presentazione:
Crea la presentazione nel modo in cui vuoi che venga visualizzata utilizzando contenuti segnaposto per aiutarti con il design.
Per ogni elemento di contenuti che inserirai, sostituisci i contenuti segnaposto con un tag. I tag sono caselle di testo o forme con una stringa univoca. Assicurati di utilizzare stringhe che è improbabile che si verifichino normalmente. Ad esempio,
{{account-holder-name}}
potrebbe essere un buon tag.Nel codice, utilizza l'API Google Drive per creare una copia della presentazione.
Nel codice, utilizza il metodo
batchUpdate
dell'API Slides, con un insieme di richiestereplaceAllText
, per eseguire tutte le sostituzioni di testo nella presentazione. Utilizza le richiestereplaceAllShapesWithImage
per eseguire sostituzioni di immagini in tutta la presentazione.
Dopo aver creato un mazzo con i tag, assicurati di farne una copia e di utilizzare l'API Slides per manipolarla. Non utilizzare l'API Slides per manipolare la copia "modello" principale.
Le sezioni seguenti includono snippet di codice che illustrano parte di questa procedura. Puoi anche guardare il video sopra per vedere un esempio completo (Python) che combina diversi concetti delle singole sezioni seguenti.
Unire il testo
Puoi utilizzare una richiesta replaceAllText
per sostituire tutte le istanze di una determinata stringa di testo in una
presentazione con un nuovo testo. Per le unioni, questa operazione è più semplice
rispetto alla ricerca e alla sostituzione di ogni istanza di testo singolarmente. Uno dei motivi per cui questo è l'approccio più sofisticato è che gli ID degli elementi della pagina sono difficili da prevedere, soprattutto quando i collaboratori perfezionano e gestiscono la presentazione del modello.
Esempio
Questo esempio utilizza l'API Drive per copiare un file di presentazione modello, creando una nuova istanza della presentazione. Quindi, utilizza l'API Google Sheets per leggere i dati da un foglio di lavoro e infine utilizza l'API Slides per aggiornare la nuova presentazione.
L'esempio prende i dati da tre celle di una riga di un intervallo denominato nel
foglio di lavoro. e lo sostituisce nella presentazione ovunque si trovino le stringhe {{customer-name}}
, {{case-description}}
o {{total-portfolio}}
.
Apps Script
Vai
Java
JavaScript
Node.js
PHP
Python
Ruby
Unire immagini
Puoi anche unire le immagini alla presentazione utilizzando una
richiesta replaceAllShapesWithImage
. Questa richiesta sostituisce tutte le istanze di forme contenenti la
stringa di testo fornita con l'immagine fornita. La richiesta posiziona e ridimensiona automaticamente l'immagine in modo che rientri nei limiti della forma del tag, mantenendo le proporzioni dell'immagine.
Esempio
Questo esempio utilizza l'API Google Drive per copiare un modello di presentazione, creando
una nuova istanza della presentazione. Poi utilizza l'API Slides per trovare
qualsiasi forma con il testo {{company-logo}}
e sostituirla con un'immagine del logo aziendale. La richiesta sostituisce anche qualsiasi
forma con il testo {{customer-graphic}}
con un'immagine diversa.
Apps Script
Vai
Java
JavaScript
Node.js
PHP
Python
Ruby
Sostituire istanze specifiche di caselle di testo o immagini
Le richieste replaceAllText
e replaceAllShapesWithImage
sono utili per sostituire i tag in una presentazione, ma a volte è necessario sostituire gli elementi solo in base a un altro criterio, ad esempio la posizione in una slide specifica.
In questi casi, devi recuperare gli ID delle forme dei tag che vuoi sostituire. Per le sostituzioni di testo, elimina il testo esistente nelle forme e poi inserisci il nuovo testo (vedi l'esempio Modificare il testo in una forma specifica).
Le sostituzioni delle immagini sono più complesse. Per unire un'immagine, devi:
- Recupera l'ID della forma del tag.
- Copia le informazioni su dimensioni e trasformazione dal tag.
- Aggiungi l'immagine alla pagina utilizzando le informazioni su dimensioni e trasformazione.
- Elimina la forma del tag.
Mantenere le proporzioni dell'immagine durante il ridimensionamento alle dimensioni desiderate potrebbe richiedere un po' di attenzione, come descritto nella sezione seguente. Vedi anche questo esempio: Sostituisci un tag di forma con un'immagine.
Mantieni le proporzioni
Quando crei immagini utilizzando l'API Slides, gli adattamenti delle proporzioni si basano solo sulle dimensioni dell'immagine, non sulle dimensioni e sui dati di trasformazione. I dati sulle dimensioni che fornisci
nella richiesta createImage
sono considerati le dimensioni desiderate dell'immagine. L'API adatta le proporzioni dell'immagine a queste dimensioni desiderate, poi applica la trasformazione fornita.
Quando sostituisci un tag con un'immagine, mantieni le proporzioni dell'immagine impostando le dimensioni e la scalabilità dell'immagine nel seguente modo:
- width: impostato sul prodotto di
width
escaleX
del tag - height: impostato sul prodotto di
height
escaleY
del tag - scale_x: impostato su
1
- scale_y: impostato su
1
In questo modo, l'API Slides adatta le proporzioni dell'immagine in base alle dimensioni visive del tag, anziché alle dimensioni non scalate (vedi Sostituire un tag forma con un'immagine).
Se imposti i parametri di scalabilità su 1
, l'immagine non viene scalata
due volte.
Questa disposizione garantisce che le proporzioni dell'immagine vengano mantenute e impedisce che l'immagine superi le dimensioni della forma del tag. L'immagine ha lo stesso punto centrale della forma del tag.
Gestisci modelli
Per le presentazioni modello definite e di proprietà dell'applicazione, crea il modello utilizzando un account dedicato che rappresenta l'applicazione. I service account sono una buona scelta ed evitano complicazioni con le norme di Google Workspace che limitano la condivisione.
Quando crei istanze di presentazioni dai modelli, utilizza sempre le credenziali dell'utente finale. In questo modo gli utenti hanno il pieno controllo della presentazione risultante e si evitano problemi di scalabilità correlati ai limiti per utente in Google Drive.
Per creare un modello utilizzando un service account, esegui i seguenti passaggi con le credenziali dell'applicazione:
- Crea una presentazione utilizzando presentations.create nell'API Slides.
- Aggiorna le autorizzazioni per consentire ai destinatari della presentazione di leggerla utilizzando permissions.create nell'API Drive.
- Aggiorna le autorizzazioni per consentire agli autori dei modelli di scrivere al suo interno utilizzando permissions.create nell'API Drive.
- Modifica il modello in base alle esigenze.
Per creare un'istanza della presentazione, segui questi passaggi con le credenziali utente:
- Crea una copia del modello utilizzando files.copy nell'API Drive.
- Sostituisci i valori utilizzando presentation.batchUpdate nell'API Slides.