Dimensioni e posizione degli elementi della pagina

Questa guida spiega come dimensionare e posizionare gli elementi della pagina utilizzando le trasformazioni affini con l'API Google Slides. Per un'introduzione concettuale alle trasformazioni affini, consulta la guida concettuale Trasformazioni ed elementi della pagina.

Trasformare gli elementi

L'API Slides consente di riposizionare e ridimensionare gli elementi di una pagina. Per farlo, determina prima il tipo di trasformazione da applicare, quindi applicala utilizzando il metodo presentations.batchUpdate() contenente uno o più elementi UpdatePageElementTransformRequest.

Le trasformazioni possono essere eseguite utilizzando un ApplyMode:

• La trasformazione ABSOLUTE replace sostituisce la matrice di trasformazione esistente dell'elemento. Tutti i parametri omessi dalla richiesta di aggiornamento della trasformazione vengono impostati su zero.

• Le trasformazioni RELATIVE vengono moltiplicate per la matrice di trasformazione esistente dell'elemento (l'ordine di moltiplicazione è importante):

$$A' = BA$$

Le trasformazioni relative spostano o scalano l'elemento della pagina dalla sua posizione. Ad esempio, spostando una forma di 100 punti a sinistra o ruotandola di 40 gradi. Le trasformazioni assolute ignorano le informazioni esistenti su posizione e scala. Ad esempio, spostano una forma al centro della pagina o la scalano a una larghezza specifica.

Le trasformazioni complesse possono in genere essere espresse come una sequenza di trasformazioni più semplici. Il precalcolo di una trasformazione, ovvero la combinazione di più trasformazioni mediante la moltiplicazione di matrici, può spesso ridurre l'overhead.

L'ordine delle operazioni di trasformazione è importante: nella maggior parte dei casi, la rotazione di un elemento attorno a un punto e poi la traslazione produce risultati diversi rispetto alla traslazione iniziale.

Per alcune operazioni, devi conoscere i parametri di trasformazione esistenti di un elemento. Se non disponi di questi valori, puoi recuperarli utilizzando il metodo presentations.pages.get().

Traduzione

La traslazione è l'azione di spostare un elemento della pagina in una nuova posizione nella stessa pagina. Le traslazioni assolute spostano l'elemento in un punto specifico, mentre le traslazioni relative spostano l'elemento di una distanza specifica.

Ricorda che i parametri di traslazione specificano la posizione dell'angolo in alto a sinistra dell'elemento, non il suo centro.

Una matrice di trasformazione di base ha la forma:

$$T=\begin{bmatrix} 1 & 0 & translate\_x\\ 0 & 1 & translate\_y\\ 0 & 0 & 1 \end{bmatrix}$$

Quando utilizzi una UpdatePageElementTransformRequest per traslare un elemento (senza modificarne le dimensioni, il taglio o l'orientamento), puoi utilizzare una delle seguenti strutture AffineTransform:

// Absolute translation:
{
  'transform': {
    'scaleX':  current scaleX value,
    'scaleY':  current scaleY value,
    'shearX':  current shearX value,
    'shearY':  current shearY value,
    'translateX': X coordinate to move to,
    'translateY': Y coordinate to move to,
    'unit': 'EMU' // or 'PT'
  }
}

// Relative translation (scaling must also be provided to avoid a matrix multiplication error):
{
  'transform': {
    'scaleX':  1,
    'scaleY':  1,
    'translateX': X coordinate to move by,
    'translateY': Y coordinate to move by,
    'unit': 'EMU' // or 'PT'
  }
}

Scala

Il ridimensionamento è l'azione di allungare o comprimere un elemento lungo la dimensione X o Y per modificarne le dimensioni. Una matrice di trasformazione di base per la scalabilità ha la forma:

$$S=\begin{bmatrix} scale\_x & 0 & 0\\ 0 & scale\_y & 0\\ 0 & 0 & 1 \end{bmatrix}$$

Puoi utilizzare questo modulo di matrice direttamente come trasformazione RELATIVE per ridimensionare un elemento, ma ciò può influire anche sul taglio e sulla traslazione di rendering dell'elemento. Per scalare l'elemento senza influire sul taglio o sulla traslazione, passa al sistema di riferimento dell'elemento.

Rotazione

Le trasformazioni di rotazione ruotano un elemento della pagina attorno a un punto, utilizzando i parametri di ridimensionamento e distorsione. La matrice di trasformazione di rotazione di base ha la seguente forma, dove l'angolo di rotazione (in radianti) viene misurato dall'asse X, in senso antiorario:

$$R=\begin{bmatrix} cos(\theta) & sin(\theta) & 0\\ -sin(\theta) & cos(\theta) & 0\\ 0 & 0 & 1 \end{bmatrix}$$

Come per il ridimensionamento, puoi utilizzare questo modulo di matrice direttamente come trasformazione RELATIVE per ruotare un elemento, ma ciò fa sì che l'elemento venga ruotato attorno all'origine della pagina. Per ruotare l'elemento attorno al suo centro o a un punto diverso, sposta il cursore sul frame di riferimento dell'elemento.

Riflessione

Il riflesso specchia un elemento su una linea o un asse specifico. La matrice di trasformazione di riflessione degli assi x e y di base ha le seguenti forme:

$$F_x=\begin{bmatrix} 1 & 0 & 0\\ 0 & -1 & 0\\ 0 & 0 & 1\\ \end{bmatrix}\qquad\qquad F_y=\begin{bmatrix} -1 & 0 & 0\\ 0 & 1 & 0\\ 0 & 0 & 1\\ \end{bmatrix}$$

Come per il ridimensionamento, puoi utilizzare questo modulo della matrice direttamente come trasformazione RELATIVE per riflettere un elemento, ma questo fa sì che l'elemento venga anche traslato. Per riflettere l'elemento senza alcuna traduzione, sposta il cursore sul frame di riferimento dell'elemento.

Frame di riferimento degli elementi

L'applicazione di una trasformazione di scala, rotazione o riflessione di base direttamente a un elemento della pagina produce una trasformazione nel sistema di riferimento della pagina. Ad esempio, una rotazione di base ruota l'elemento intorno all'origine della pagina (l'angolo in alto a sinistra). Tuttavia, puoi operare nel sistema di riferimento dell'elemento, ad esempio per ruotarlo attorno al suo punto centrale.

Per trasformare un elemento all'interno del proprio sistema di riferimento, racchiudilo tra due altre trasformazioni: una trasformazione precedente T1 che sposta il centro dell'elemento all'origine della pagina e una trasformazione successiva T2 che riporta l'elemento nella posizione originale. L'intera operazione può essere espressa come prodotto di matrici:

$$A' = T2 \times B \times T1 \times A$$

Puoi anche passare ad altri sistemi di riferimento traslando punti diversi all'origine. Questi punti diventano il centro del nuovo sistema di riferimento.

È possibile eseguire ciascuna di queste trasformazioni singolarmente come richieste di trasformazione RELATIVE sequenziali. Idealmente, dovresti precalcolare A' sopra con moltiplicazioni di matrici e applicare il risultato come una singola trasformazione ABSOLUTE. In alternativa, precalcola il prodotto T2 * B * T1 e applicalo come una singola trasformazione RELATIVE. Entrambi sono più efficienti, in termini di operazioni API, rispetto all'invio delle richieste di trasformazione singolarmente.

Limitazioni

Alcuni campi di dimensionamento e posizionamento non sono compatibili con alcuni tipi di elementi della pagina. La tabella seguente riassume la compatibilità di determinati elementi della pagina con i campi di dimensionamento e posizionamento:

Campo	Forma	Video	Tabella
Traduzioni	✔	✔	✔
Scala	✔	✔	No**
Cesoie	✔	No	No

Per aggiornare le dimensioni di righe e colonne della tabella, utilizza UpdateTableRowPropertiesRequest e UpdateTableColumnPropertiesRequest.

Tutti i campi di dimensionamento e posizionamento potrebbero dare risultati imprevisti se l'elemento della pagina è inclinato. Tutte le limitazioni sono soggette a modifica. Per informazioni aggiornate, consulta l'API Google Slides.

Valori sottoposti a refactoring

Quando crei un elemento della pagina, puoi specificare una dimensione e una trasformazione che forniscono un determinato risultato visivo. Tuttavia, l'API Slides potrebbe sostituire i valori forniti con altri che producono lo stesso aspetto visivo. In generale, se scrivi una dimensione utilizzando l'API, non è garantito che ti venga restituita la stessa dimensione. Tuttavia, dovresti ottenere gli stessi risultati se tieni conto della trasformazione.