Pagine, elementi di pagina e proprietà

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 pratiche, la documentazione di riferimento e gli esempi di ricette.

Presentazioni, pagine ed elementi della 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 della pagina, che insieme compongono il contenuto 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 pagine 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 i valori predefiniti per gli stili di testo utilizzati in tutta la presentazione. Lo sfondo e qualsiasi altra forma nello schema costituiscono lo sfondo predefinito per tutte le slide basate su quello schema. Se hai un logo aziendale che vuoi visualizzare in ogni slide della presentazione, inseriscilo nella slide master.

Layout: i modelli di layout determinano la disposizione dei contenuti in ogni tipo di slide. Se vuoi che tutte le slide del titolo abbiano un determinato aspetto, 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 rilevanti soprattutto per l'utilizzo delle note del relatore.

Tipi e struttura di rappresentazione delle API

Questa sezione descrive in che modo il modello concettuale di Presentazioni Google, come descritto sopra, è rappresentato nell'API Slides.

Il seguente diagramma mostra la relazione tra presentazioni, pagine e elementi della pagina come tipi nell'API Slides:

Le sezioni seguenti mostrano come vengono rappresentati questi tipi in JSON.

Presentazioni

Una presentazione include un numero 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 della pagina:

{
  "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 della 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 della pagina, come definito dal campo unione element_kind nella definizione precedente. Questi tipi di elementi della pagina sono descritti nella tabella seguente:

Tipo di elemento	Descrizione
Gruppo	Un insieme di elementi della 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 della pagina più comuni per creare slide.
Immagine	Un'immagine importata 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à della pagina e degli elementi della pagina

L'API Slides consente di leggere e aggiornare l'aspetto delle pagine e degli elementi della pagina nella presentazione. I diversi elementi della pagina supportano proprietà diverse che controllano il rendering dell'elemento della pagina.

Ogni tipo di elemento della pagina ha un elemento proprietà corrispondente e un messaggio di aggiornamento delle proprietà, ad esempio:

• Esiste un tipo di elemento pagina Forma
• Il relativo campo della proprietà è shapeProperties
• La richiesta di aggiornamento di queste proprietà è UpdateShapePropertiesRequest

Esiste lo stesso insieme di elementi/proprietà/richiesta di aggiornamento per ogni tipo di elemento della 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 metodo 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 cambia 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 è il riempimento solido, in cui l'interno di un oggetto viene riempito con un unico colore solido. I riempimenti possono essere utilizzati anche per gli sfondi delle pagine.
Contorno	Il contorno rappresenta l'insieme di linee che circondano l'elemento della pagina. Il colore delle linee è controllato da un riempimento. Le persone che chiamano possono anche regolare la larghezza e lo stile dei trattini dei contorni.
Ombre	L'ombra rappresenta un effetto visivo che ha lo scopo di 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 completo delle proprietà e possono utilizzare maschere di campo per determinare quali campi del messaggio delle proprietà devono essere aggiornati.

Una maschera di campo * viene trattata come un carattere jolly ed è una notazione abbreviata per specificare ogni campo di un messaggio. La sintassi con caratteri jolly può produrre risultati indesiderati se l'API viene aggiornata in futuro, poiché i campi di sola lettura e i campi appena aggiunti potrebbero causare errori. Per le applicazioni di produzione, elenca sempre i campi specifici da aggiornare nelle maschere dei campi ed evita di utilizzare caratteri jolly *.

Eredità della proprietà

Una pagina o un elemento della pagina può ereditare le proprietà dai relativi 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 nella pagina master su cui si basa.
• Proprietà forma: una forma può essere contrassegnata come segnaposto, consentendoti di fare riferimento esplicito a un'altra forma segnaposto (nel layout principale o nella pagina master) da cui ereditare le proprietà.

Queste idee sono spiegate più nel dettaglio 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 la slide master di una slide sono specificati nel campo slideProperties della slide.

Una pagina può ereditare proprietà come sfondo e combinazione di colori da una pagina padre. Per ereditare una proprietà, la pagina secondaria non imposta un valore per quella proprietà nel messaggio PageProperties. Se non "override" il 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 eredita da una slide master:

Le proprietà utilizzate per il rendering di una slide sono una combinazione di quelle che definisce e di quelle che eredita. In questo esempio, i valori risolti utilizzati per il rendering della slide 1 sono i seguenti:

• PropertyA è "Red".
• PropertyB è "Arancia".

Una pagina senza elemento principale eredita i valori predefiniti da Google Slides per tutte le proprietà che non definisce.

Eredità delle proprietà della forma

Le forme possono ereditare proprietà, come riempimento, contorno o ombra, da altre forme. Una forma è un segnaposto se il 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 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.

Puoi creare segnaposto utilizzando l'editor di Presentazioni, ma non utilizzando l'API Slides.

Con questa gerarchia di ereditarietà definita, la pagina secondaria eredita una proprietà non impostando il valore nel messaggio ShapeProperties. Se non sostituisci il valore definito dall'elemento 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 una slide master:

Le proprietà utilizzate per 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:

• Segnaposto 1: la proprietà A viene visualizzata come "Giallo", la proprietà B come "Verde".
• Segnaposto2: la proprietà A viene visualizzata come "Giallo", la proprietà B come "Viola".
• Segnaposto3: la proprietàA viene visualizzata come "Giallo", la proprietàB come "Viola".

Le forme sono l'unico tipo di elemento della pagina che può avere elementi principali. Altri tipi, come immagini, tabelle e grafici, non possono essere segnaposto e non possono avere elementi principali.

Quando una forma non ha un elemento padre, tutti i valori che non imposta vengono compilati automaticamente con i valori predefiniti dell'applicazione.

"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 per il rendering della forma nella relativa pagina, ma i figli con uno stato corrispondente RENDERED possono comunque ereditare questa proprietà.

L'aggiornamento di una proprietà imposta implicitamente il relativo stato su `RENDERED`, a meno che tu non imposti lo stato su un altro valore nella stessa richiesta.

Il seguente diagramma mostra l'ereditarietà 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:

• Segnaposto 1: propertyA viene visualizzata come "Rosso".
• Placeholder2: propertyA is not rendered. Se questa fosse la proprietà del contorno, Placeholder2 non avrebbe contorno.
• Placeholder3: propertyA is not rendered.

Esiste un altro valore possibile dell'enumerazione PropertyState: lo stato della proprietà INHERIT indica che lo stato della proprietà stesso è ereditato e deve essere utilizzato il valore della proprietà principale. Le forme senza genitori non possono avere uno stato di proprietà INHERIT.