Pagine, elementi di pagina e proprietà

Per utilizzare l'API Presentazioni in modo efficace, devi comprendere l'architettura delle presentazioni e i loro 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à degli stili dei componenti

La lettura di questa panoramica e degli altri concetti semplifica la comprensione e l'utilizzo delle guide illustrative, della documentazione di riferimento e degli esempi di ricette.

Presentazioni, pagine ed elementi di pagina

L'elemento contenitore più esterno in Presentazioni Google è una presentazione. È 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 diapositiva, ovvero le pagine visualizzate dagli utenti che passano da una pagina all'altra quando la presentazione viene visualizzata su uno schermo.

Ogni pagina contiene una serie di elementi di pagina, che insieme costituiscono il contenuto della pagina, come illustrato nel seguente diagramma:

Oltre alle diapositive, esistono altri tipi di pagine che consentono di applicare un design a molte slide diverse, creando un aspetto coerente. Questi altri tipi di pagine sono master e layout e le loro proprietà determinano le modalità di rendering delle slide, come mostrato nel seguente diagramma:

Master: la pagina principale ha due scopi. I segnaposto nello schema contengono i valori predefiniti per gli stili di testo utilizzati nella presentazione. Lo sfondo e qualsiasi altra forma sulla slide dello schema costituiscono lo sfondo predefinito per tutte le slide basate sullo schema in questione. Se vuoi che appaia un logo aziendale su ogni slide della presentazione, inseriscilo nello schema.

Layout: i modelli di layout determinano il modo in cui i contenuti sono disposti su ogni tipo di slide. Ad esempio, se vuoi che tutte le slide 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 gli schemi delle note, che sono per lo più pertinenti per la gestione delle note del relatore.

Tipi di rappresentazione e struttura delle API

Questa sezione descrive come il modello concettuale di Presentazioni Google, come descritto sopra, viene rappresentato nell'API Presentazioni.

Il seguente diagramma mostra la relazione tra presentazioni, pagine ed elementi di pagina come tipi nell'API Presentazioni:

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

Presentazioni

Una presentazione include una serie di proprietà e 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,
}

Pages

Una pagina include un insieme di proprietà e 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 nelle 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 di pagina, come definiti dal campo di unione element_kind nella definizione riportata sopra. Questi tipi di elementi di pagina sono descritti nella seguente tabella:

Tipo di elemento	Descrizione
Gruppo	Un insieme di elementi di pagina trattati come una singola unità. Possono essere spostati, ridimensionati e ruotati insieme.
Shape	Un oggetto visivo semplice, ad esempio rettangoli, ellissi e caselle di testo. Le forme possono contenere testo, quindi sono gli elementi di pagina più comuni per la creazione di slide.
Immagine	Un'immagine importata in Presentazioni.
Video	Un video importato in Presentazioni.
A linee	Una linea visiva, una curva o un connettore.
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à degli elementi di pagina e di pagina

L'API Presentazioni consente di leggere e aggiornare l'aspetto delle pagine e degli elementi di pagina nella presentazione. I diversi elementi di pagina supportano proprietà diverse che controllano il modo in cui viene visualizzato l'elemento.

A ogni tipo di elemento di pagina corrisponde un elemento delle proprietà e un messaggio di aggiornamento delle proprietà, ad esempio:

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

Esiste lo stesso insieme di richieste di elementi/proprietà/aggiornamento per ogni tipo di elemento di pagina: Image/imageProperties/UpdateImageProperties e così via.

Puoi leggere l'attributo delle proprietà ogni volta che lo incontri durante la lettura di un elemento. Per modificare i valori al suo interno, 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 Presentazioni:

Proprietà	Descrizione
Colore	I colori nell'API Presentazioni possono essere un valore RGB o un riferimento a un colore del tema. I colori del tema vengono definiti per nome (ad esempio "DARK1") e possono essere mappati ai valori RGB utilizzando una combinazione di colori della pagina. Questa combinazione di colori viene solitamente aggiornata quando modifichi il tema della presentazione nell'editor di Presentazioni.
Riempimento	Il riempimento rappresenta il rendering di uno 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 della pagina. Il colore delle linee viene controllato con un riempimento. I chiamanti possono anche regolare la larghezza e lo stile del trattino dei contorni.
Ombra	L'ombra rappresenta un effetto visivo che riproduce un'ombra fisica proiettata dall'oggetto. Attualmente, le ombre nell'API Presentazioni 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 Shapes. Queste richieste accettano un messaggio completo sulle proprietà e possono utilizzare mascherine di campo per determinare quali campi del messaggio sulle proprietà devono essere aggiornati.

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

Eredità della proprietà

Un elemento di pagina o 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 nello schema su cui è basata.
• Proprietà forma: una forma può essere contrassegnata come placeholder, consentendoti di fare riferimento esplicito a un'altra forma segnaposto (sul layout principale o nello schema principale della pagina) da cui ereditare le proprietà.

Queste idee vengono spiegate in modo più approfondito nei seguenti paragrafi.

Ereditarietà 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, mentre i layout ereditano dagli schemi. Il layout e lo schema principali di una slide sono specificati nel campo slideProperties della slide.

Una pagina può ereditare proprietà come sfondo e schema di colori da una pagina principale. Per ereditare una proprietà, la pagina secondaria semplicemente non imposta un valore per quella proprietà nel messaggio PageProperties. Se non esegui l'"override" del valore definito dall'elemento padre, 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 visualizzare una slide sono una combinazione di quelle che definisce e quelle che eredita. In questo esempio, i valori risolti utilizzati per il rendering della diapositiva 1 sono i seguenti:

• La proprietà A è "Rosso".
• ProprietàB è "Arancia".

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

Ereditarietà delle proprietà delle forme

Le forme possono ereditare proprietà come riempimento, contorno o ombreggiatura da altre forme. Una forma è un placeholder se è impostato il campo Shape.placeholder. Il campo Shape.placeholder.parentObjectId del segnaposto figlio identifica il segnaposto principale. Quando crei una nuova slide basata su un layout, tutti i segnaposto in quel layout appaiono come forme secondarie nella nuova slide. Analogamente, i segnaposto sulle pagine master possono fungere da elementi padre dei segnaposto dei layout.

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

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

Le proprietà utilizzate per visualizzare 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: la proprietà A viene visualizzata come "Giallo", la proprietàB come "Verde".
• Placeholder2: la proprietàA viene visualizzata come "Giallo", la proprietàB come "Viola".
• Placeholder3: la proprietàA viene visualizzata come "Giallo", la proprietàB come "Viola".

Le forme sono l'unico tipo di elemento di pagina che può avere elementi padre. Altri tipi, ad esempio immagini, tabelle e grafici, non possono essere segnaposto né avere elementi padre.

Quando una forma non ha un elemento padre, tutti i valori che non imposta vengono completati 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 forme figlio. Una proprietà con stato di proprietà NOT_RENDERED non verrà utilizzata durante il rendering della forma nella relativa pagina, ma i bambini con uno stato di proprietà corrispondente pari a RENDERED possono comunque ereditare questa proprietà.

L'aggiornamento di una proprietà ne imposta implicitamente lo stato su "RENDERED", a meno che 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à delle forme può essere influenzato dal campo PropertyState. In questo esempio, i valori risolti per queste forme sono i seguenti:

• Segnaposto1: la proprietàA viene visualizzata come "Rosso".
• Segnaposto2: la proprietàA non viene visualizzata. Se fosse la proprietà Outline, Placeholder2 non avrebbe alcun contorno.
• Segnaposto3: la proprietàA 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 della proprietà principale. Le forme senza principali non possono avere uno stato di proprietà INHERIT.