Per utilizzare l'API Slides in modo efficace, devi comprendere l'architettura delle presentazioni e dei relativi componenti, nonché le interazioni tra questi componenti. Questa pagina fornisce una panoramica dettagliata di questi argomenti:
- Modello concettuale dei componenti della presentazione
- Come l'API rappresenta questi componenti
- Proprietà di stile dei componenti
La lettura di questa e delle altre panoramiche concettuali semplificherà la comprensione e l'utilizzo delle guide pratiche, della documentazione di riferimento e degli esempi di codice.
Presentazioni, pagine ed elementi pagina
L'elemento contenitore più esterno in Presentazioni Google è una presentazione. Questa è l'unità che può essere salvata in Google Drive, condivisa con altri utenti e così via.
Ogni presentazione contiene vari tipi di pagine. Un tipo di pagina è una a slide, ovvero le pagine che gli utenti vedono e sfogliano quando la presentazione viene visualizzata su uno schermo.
Ogni pagina contiene una serie di elementi pagina che, insieme, costituiscono il contenuto della pagina, come mostrato nel seguente diagramma:
Oltre alle slide, esistono altri tipi di pagine che consentono di applicare il design a molte slide diverse, creando un aspetto coerente. Questi altri tipi di pagina sono master e layout e le relative proprietà determinano la modalità di rendering delle slide , come mostrato nel seguente diagramma:
Master : la pagina master ha due scopi. I segnaposto sul master contengono i valori predefiniti per gli stili di testo utilizzati in tutta la presentazione. Lo sfondo e le altre forme sulla slide master costituiscono lo sfondo predefinito per tutte le slide basate su quel master. Se hai un logo aziendale che vuoi che venga visualizzato su ogni slide della presentazione, inseriscilo nel master.
Layout : i modelli di layout determinano la disposizione dei contenuti su ogni tipo di slide. Se vuoi che tutte le slide del titolo abbiano un aspetto specifico, ad esempio, puoi modificare il modello di layout del titolo.
Esistono altri due tipi di pagine, le pagine delle note e i master delle note, che sono principalmente pertinenti per l'utilizzo delle note del relatore.
Tipi e struttura della rappresentazione dell'API
Questa sezione descrive come il modello concettuale di Presentazioni Google, come descritto sopra, è rappresentato nell'API Slides.
Il seguente diagramma illustra la relazione tra presentazioni, pagine ed elementi pagina come tipi nell'API Slides:
Nelle sezioni seguenti viene illustrato come questi tipi sono rappresentati in JSON.
Presentazioni
Una presentazione include una serie di proprietà e contiene le pagine che la compongono:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Pagine
Una pagina include un insieme di proprietà e contiene gli elementi pagina che la compongono:
{
"objectId": string,
"pageType": enum(PageType),
"pageElements": [ { object(PageElement) } ],
"pageProperties": { object(PageProperties) },
// Union field properties can be only one of the following:
"slideProperties": { object(SlideProperties) },
"layoutProperties": { object(LayoutProperties) },
"notesProperties": { object(NotesProperties) },
// End of list of possible types for union field properties.
}
Elementi pagina
Gli elementi pagina sono i componenti visivi posizionati sulle pagine. Un elemento di pagina nell'API contiene una serie di proprietà, tra cui un campo che varia a seconda del tipo di elemento di pagina:
{
"objectId": string,
"size": { object(Size) },
"transform": { object(AffineTransform) },
"title": string,
"description": string,
// Union field element_kind can be only one of the following:
"elementGroup": { object(Group) },
"shape": { object(Shape) },
"image": { object(Image) },
"video": { object(Video) },
"line": { object(Line) },
"table": { object(Table) },
"wordArt": { object(WordArt) },
"sheetsChart": { object(SheetsChart) },
// End of list of possible types for union field element_kind.
}
Esistono diversi tipi di elementi pagina, come definito dal campo di unione element_kind nella definizione sopra. Questi tipi di elementi pagina sono descritti nella tabella seguente:
| Tipo di elemento | Descrizione |
|---|---|
| Gruppo | Un insieme di elementi pagina trattati come una singola unità. Possono essere spostati, scalati e ruotati insieme. |
| Forma | Un oggetto visivo semplice, come rettangoli, ellissi e caselle di testo. Le forme possono contenere testo, quindi sono gli elementi pagina più comuni per creare slide. |
| Immagine | Un elemento grafico importato in Presentazioni. |
| Video | Un video importato in Presentazioni. |
| Linea | Una linea, una curva o un connettore visivo. |
| Tabella | Una griglia di contenuti. |
| WordArt | Un elemento di testo visivo che si comporta più come una forma. |
| SheetsChart | Un grafico importato in Presentazioni da Fogli Google. |
Proprietà di pagine ed elementi di pagina
L'API Slides consente di leggere e aggiornare l'aspetto delle pagine e degli elementi pagina della presentazione. Diversi elementi di pagina supportano proprietà diverse che controllano la modalità di rendering dell'elemento di pagina.
Ogni tipo di elemento di pagina ha un elemento di proprietà corrispondente e un messaggio di aggiornamento delle proprietà, ad esempio:
- Esiste un tipo di elemento di pagina Forma
- Il relativo campo delle proprietà è shapeProperties
- La richiesta di aggiornamento di queste proprietà è UpdateShapePropertiesRequest
Lo stesso insieme di elemento/proprietà/richiesta di aggiornamento esiste per ogni tipo di elemento di pagina: Image/imageProperties/UpdateImageProperties, e così via.
Puoi leggere l'attributo delle proprietà ovunque lo incontri durante la lettura di un elemento; per modificarne i valori, utilizzalo con il tipo di richiesta corrispondente come payload per il batchUpdate, che ti consente di modificare questi valori nella presentazione.
Tipi di proprietà
Esistono alcune proprietà comuni a diversi tipi di oggetti nell'API Slides:
| Proprietà | Descrizione |
|---|---|
| Colore | I colori nell'API Slides possono essere un valore RGB o un riferimento a un colore del tema. I colori del tema sono indicati per nome (ad esempio "DARK1") e possono essere mappati ai valori RGB utilizzando una combinazione di colori della pagina. Questa combinazione di colori viene aggiornata di solito quando si modifica il tema della presentazione nell'editor di Presentazioni. |
| Riempi | Il riempimento rappresenta il rendering dello spazio vuoto all'interno di un oggetto. Il riempimento più comunemente supportato in Presentazioni è un riempimento a tinta unita, in cui l'interno di un oggetto viene riempito con un singolo colore a tinta unita. I riempimenti possono essere utilizzati anche per gli sfondi delle pagine. |
| Contorno | Il contorno rappresenta l'insieme di linee che circondano l'elemento di pagina. Il colore delle linee è controllato da un riempimento. I chiamanti possono anche regolare la larghezza e lo stile del trattino dei contorni. |
| Ombre | L'ombra rappresenta un effetto visivo che imita un'ombra fisica proiettata dall'oggetto. Al momento, le ombre nell'API Slides sono di sola lettura. |
Aggiornamento delle proprietà
Per aggiornare una proprietà, utilizza la richiesta appropriata
Update...Properties in una
batchUpdate
chiamata, ad esempio UpdateShapeProperties per le forme. Queste richieste
accettano un messaggio di proprietà completo e possono utilizzare
maschere di campo per determinare quali campi nel messaggio delle
proprietà devono essere aggiornati.
Eredità della proprietà
Una pagina o un elemento di pagina può ereditare le proprietà dai relativi oggetti principali. Le proprietà di un oggetto, incluse quelle che definisce e quelle che eredita, determinano l'aspetto visivo finale.
- Proprietà della pagina : una pagina eredita tutte le proprietà che non definisce, ma che sono definite nel layout o nel master su cui si basa.
- Proprietà della forma : una forma può essere contrassegnata come segnaposto, consentendoti di fare riferimento in modo esplicito a un'altra forma segnaposto (nel layout principale o nello schema principale della pagina) da cui ereditare le proprietà.
Questi concetti sono spiegati ulteriormente nei paragrafi seguenti.
Eredità delle proprietà della pagina
La struttura di slide, layout e master definisce una gerarchia di ereditarietà all'interno della presentazione: le slide ereditano dai layout e i layout ereditano dai master. Il layout principale e lo schema di una slide sono specificati nel campo slideProperties della slide.
Una pagina può ereditare proprietà, come lo sfondo e la combinazione di colori, da una pagina principale. Per ereditare una proprietà, la pagina secondaria non imposta semplicemente un valore per quella proprietà nel suo PageProperties PageProperties. Se non "sovrascrivi" il valore definito dal genitore, la pagina accetta il valore ereditato.
Il seguente diagramma mostra una slide che eredita le proprietà da un layout, che eredita da un master:
Le proprietà utilizzate per il rendering di una slide sono una combinazione di quelle che definisce e quelle che eredita. In questo esempio, i valori risolti utilizzati per il rendering della slide 1 sono i seguenti:
- PropertyA è "Red".
- PropertyB è "Orange".
Eredità delle proprietà della forma
Le forme possono ereditare proprietà, come riempimento, contorno o ombra, da altre forme. Una forma è un segnaposto se il relativo
Shape.placeholder
è impostato. Il campo Shape.placeholder.parentObjectId del segnaposto secondario identifica il segnaposto principale. Quando crei una nuova slide basata su un layout, tutti i segnaposto in quel layout vengono visualizzati come forme secondarie nella nuova slide.
Allo stesso modo, i segnaposto nelle pagine master possono fungere da genitori dei segnaposto dei layout.
Con questa gerarchia di ereditarietà definita, la pagina secondaria eredita una proprietà non impostando quel valore nel suo ShapeProperties ShapeProperties. Se non sovrascrivi il valore definito dal genitore, la forma secondaria accetta il valore ereditato.
Il seguente diagramma mostra l'eredità delle proprietà tra tre segnaposto contenuti in una slide, un layout e un master:
Le proprietà utilizzate per il rendering di una forma segnaposto sono una combinazione di quelle che definisce e quelle che eredita. In questo esempio, i valori risolti per queste forme sono i seguenti:
- Segnaposto1: propertyA viene visualizzata come "Yellow", propertyB come "Green".
- Segnaposto2: propertyA viene visualizzata come "Yellow", propertyB come "Purple".
- Segnaposto3: propertyA viene visualizzata come "Yellow", propertyB come "Purple".
Le forme sono l'unico tipo di elemento di pagina che può avere elementi principali. Altri tipi, come immagini, tabelle e grafici, non possono essere segnaposto e non possono avere elementi principali.
"Nascondere" le proprietà utilizzando PropertyState
L'
PropertyState
PropertyState controlla se la proprietà di una forma viene effettivamente utilizzata per il rendering,
o se il valore viene utilizzato solo per l'eredità dalle forme secondarie. Una proprietà con
stato della proprietà NOT_RENDERED non verrà utilizzata per il rendering della forma nella relativa
pagina, tuttavia i figli che hanno uno stato della proprietà corrispondente di RENDERED
possono comunque ereditare questa proprietà.
Il seguente diagramma mostra l'eredità delle proprietà tra tre segnaposto che manipolano il campo PropertyState:
Il rendering delle proprietà della forma può essere influenzato dal campo PropertyState. In questo esempio, i valori risolti per queste forme sono i seguenti:
- Segnaposto1: propertyA viene visualizzata come "Red".
- Segnaposto2: propertyA non viene visualizzata. Se si trattasse della proprietà del contorno, il segnaposto2 non avrebbe alcun contorno.
- Segnaposto3: propertyA non viene visualizzata.
Esiste un altro valore possibile dell'enumerazione
PropertyState: lo stato della proprietà INHERIT indica che lo stato della proprietà stesso
viene ereditato e deve essere utilizzato il valore dell'elemento principale. Le forme senza elementi principali non possono avere uno stato della proprietà INHERIT.