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 dei concetti ti aiuterà a comprendere e utilizzare più facilmente le guide illustrative, la documentazione di riferimento e gli esempi di codice.
Presentazioni, pagine ed elementi di pagina
L'elemento contenitore più esterno in Presentazioni Google è una presentazione. Questa è l'unità che può essere salvata su Google Drive, condivisa con altri utenti e così via.
Ogni presentazione contiene vari tipi di pagine. Un tipo di pagina è una 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 di pagina che, insieme, costituiscono i contenuti della pagina, come mostrato nel seguente diagramma:
Oltre alle slide, esistono altri tipi di pagine che ti consentono di applicare il design a molte slide diverse, creando un aspetto coerente. Questi altri tipi di pagina sono master e layout e le loro proprietà determinano il modo in cui le slide vengono visualizzate, come mostrato nel seguente diagramma:
Pagine master: la pagina master ha due scopi. I segnaposto nello schema contengono le impostazioni predefinite per gli stili di testo utilizzati nella presentazione. Lo sfondo e tutte le altre forme della slide master costituiscono lo sfondo predefinito per tutte le slide basate su quel master. Se hai un logo aziendale che vuoi visualizzare su ogni slide della presentazione, inseriscilo nella slide master.
Layout: i modelli di layout determinano il modo in cui i contenuti vengono disposti su ogni tipo di slide. Ad esempio, se vuoi che tutte le diapositive del titolo abbiano un determinato aspetto, puoi modificare il modello di layout del titolo.
Esistono altri due tipi di pagine, le pagine delle note e le note principali, che sono utili soprattutto per lavorare con le note del relatore.
Tipi e struttura di rappresentazione dell'API
Questa sezione descrive come il modello concettuale di Presentazioni Google, come descritto sopra, è rappresentato nell'API Slides.
Il seguente diagramma mostra la relazione tra presentazioni, pagine ed elementi di pagina come tipi nell'API Slides:
Le sezioni seguenti mostrano come questi tipi sono rappresentati in JSON.
Presentazioni
Una presentazione include una serie di proprietà e contiene le pagine al suo interno:
{
"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 di pagina al suo interno:
{
"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 di 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 in base al 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 di pagina, definiti dal campo di unione element_kind nella definizione precedente. Questi tipi di elementi di pagina sono descritti nella tabella seguente:
| Tipo di elemento | Descrizione |
|---|---|
| Gruppo | Un insieme di elementi di pagina trattati come un'unità singola. Possono essere spostati, ridimensionati e ruotati insieme. |
| Forma | Un oggetto visivo semplice, come rettangoli, ellissi e caselle di testo. Le forme possono contenere testo, quindi sono gli elementi di pagina più comuni per creare slide. |
| Immagine | Un 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 ti consente di leggere e aggiornare l'aspetto delle pagine e degli elementi di pagina della presentazione. Elementi di pagina diversi supportano proprietà diverse che controllano il modo in cui l'elemento di pagina viene visualizzato.
Ogni tipo di elemento di pagina ha un elemento delle proprietà corrispondente e un messaggio di aggiornamento delle proprietà, ad esempio:
- Esiste un tipo di elemento di pagina Shape
- Il campo della proprietà è shapeProperties
- La richiesta di aggiornamento di queste proprietà è UpdateShapePropertiesRequest
Lo stesso insieme di elementi/proprietà/richieste di aggiornamento esiste per ogni tipo di elemento di pagina: Image/imageProperties/UpdateImageProperties e così via.
Puoi leggere l'attributo properties ogni volta che lo incontri durante la lettura di un elemento. Per modificare i valori al suo interno, utilizzalo con il tipo di richiesta con corrispondenza come payload per il metodo batchUpdate, in modo da poter modificare questi valori nella presentazione.
Tipi di proprietà
Esistono alcune proprietà comuni tra 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 la combinazione di colori di una pagina. Questa combinazione di colori viene comunemente aggiornata 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 unico 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 con un riempimento. I chiamanti possono anche regolare la larghezza e lo stile del tratteggio dei contorni. |
| Ombre | L'ombra rappresenta un effetto visivo destinato a imitare 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 Update...Properties appropriata in una chiamata batchUpdate, ad esempio UpdateShapeProperties per le forme. Queste richieste accettano un messaggio di proprietà completo e possono utilizzare le maschere di campo per determinare quali campi del messaggio di proprietà devono essere aggiornati.
Eredità della proprietà
Una pagina o un elemento di pagina può ereditare le proprietà dagli oggetti principali. Le proprietà di un oggetto, incluse quelle che definisce e quelle che eredita, determinano il suo 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à delle forme: una forma può essere contrassegnata come segnaposto, consentendoti di fare riferimento esplicitamente a un'altra forma segnaposto (nel layout principale o nel master della pagina) da cui ereditare le proprietà.
Queste idee sono spiegate in modo più dettagliato nei paragrafi seguenti.
Eredità delle proprietà della pagina
La struttura di slide, layout e schemi definisce una gerarchia di ereditarietà all'interno della presentazione: le slide ereditano dai layout e i layout ereditano dagli schemi. 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 un valore per quella proprietà nel suo messaggio PageProperties. Se non "esegue l'override" del valore definito dall'elemento principale, la pagina accetta il valore ereditato.
Il seguente diagramma mostra una slide che eredita le proprietà da un layout, che a sua volta le eredita da un master:
Le proprietà utilizzate per eseguire il rendering di una slide sono una combinazione di quelle definite dalla slide e di quelle ereditate. In questo esempio, i valori risolti utilizzati per eseguire il rendering della slide 1 sono i seguenti:
- PropertyA è "Red".
- La proprietà B è "Arancia".
Eredità delle proprietà delle forme
Le forme possono ereditare proprietà, come riempimento, contorno o ombra, da altre forme. Una forma è un segnaposto se il relativo campo 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 di quel layout vengono visualizzati come forme secondarie nella nuova slide.
Analogamente, i segnaposto nelle pagine master possono fungere da elementi principali dei segnaposto dei layout.
Una volta definita questa gerarchia di ereditarietà, la pagina secondaria eredita una proprietà non impostando il valore nel messaggio ShapeProperties. Se non esegue l'override del valore definito dalla forma principale, la forma secondaria accetta il valore ereditato.
Il seguente diagramma mostra l'ereditarietà delle proprietà tra tre segnaposto contenuti in una slide, un layout e un modello:
Le proprietà utilizzate per eseguire il rendering di una forma segnaposto sono una combinazione di quelle che definisce e di quelle che eredita. In questo esempio, i valori risolti per queste forme sono i seguenti:
- Placeholder1: propertyA viene visualizzato come "Yellow", propertyB come "Green".
- Placeholder2: propertyA viene visualizzato come "Giallo", propertyB come "Viola".
- Placeholder3: propertyA viene visualizzata come "Giallo", propertyB come "Viola".
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'enumerazione PropertyState controlla se la proprietà di una forma viene effettivamente utilizzata per il rendering o se il valore viene utilizzato solo per l'ereditarietà da parte delle forme secondarie. Una proprietà con stato NOT_RENDERED non verrà utilizzata durante il rendering della forma sulla relativa pagina, ma le proprietà secondarie con uno stato corrispondente di RENDERED possono comunque ereditare questa proprietà.
Il seguente diagramma mostra l'ereditarietà delle proprietà tra tre segnaposto che manipolano il campo PropertyState:
Il rendering delle proprietà delle forme può essere influenzato dal campo PropertyState. In questo esempio, i valori risolti per queste forme sono i seguenti:
- Placeholder1: propertyA viene visualizzato come "Red".
- Placeholder2: propertyA non viene visualizzata. Se si trattasse della proprietà outline, Placeholder2 non avrebbe un contorno.
- Placeholder3: propertyA non viene visualizzata.
Esiste un altro valore possibile dell'enumerazione PropertyState: lo stato della proprietà INHERIT indica che lo stato della proprietà stessa viene ereditato e deve essere utilizzato il valore della proprietà principale. Le forme senza elementi principali non possono avere uno stato della proprietà INHERIT.