Ridimensionamento e posizionamento degli elementi di pagina

Questa guida descrive come ridimensionare e posizionare gli elementi della pagina utilizzando le trasformazioni affine. Per un'introduzione concettuale alle trasformazioni affine, consulta la guida concettuale Trasformazioni.

Trasformare gli elementi

L'API Presentazioni ti consente di riposizionare e ridimensionare gli elementi su una pagina. Per farlo, determina prima il tipo di trasformazione da applicare, quindi applicala utilizzando il metodo presentations.batchUpdate che contiene uno o più elementi UpdatePageElementTransformRequest.

Le trasformazioni possono essere effettuate in uno dei due seguenti valori applyModes:

• ABSOLUTE trasforma sostituisce la matrice di trasformazione esistente dell'elemento. Gli eventuali parametri omessi dalla richiesta di aggiornamento della trasformazione sono impostati su zero.

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

$$A' = BA$$

Le trasformazioni relative spostano o ridimensionano l'elemento della pagina da dove si trova attualmente, ad esempio spostando una forma di 100 punti verso sinistra o ruotandola di 40 gradi. Le trasformazioni assolute ignorano le informazioni sulla posizione e sulla scala esistenti; ad esempio, lo spostamento di una forma al centro della pagina o la scalabilità in modo che abbia una larghezza specifica.

In genere, le trasformazioni complesse possono essere espresse come una sequenza di trasformazioni più semplici. Spesso il precalcolo di una trasformazione, combinando più trasformazioni mediante la moltiplicazione matriciale, può ridurre l'overhead.

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

Per alcune operazioni, devi sapere quali sono i parametri di trasformazione esistenti di un elemento. Se non hai questi valori, puoi recuperarli con una richiesta presentations.pages.get.

Traduzione

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

Ricorda che i parametri di traslazione specificano la posizione dell'angolo superiore sinistro dell'elemento, non il suo centro.

Una matrice di trasformazione di base della traduzione ha il seguente formato:

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

Quando utilizzi un oggetto UpdatePageElementTransformRequest per tradurre 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'
  }
}

Scalabilità

La scalabilità è l'azione di allungare o comprimere un elemento lungo la dimensione X e/o Y per modificarne le dimensioni. Una matrice di trasformazione di scalabilità di base ha il seguente formato:

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

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

Rotazione

La rotazione trasforma la rotazione di un elemento di pagina attorno a un punto utilizzando i parametri di scalabilità e taglio. La matrice di trasformazione della rotazione base ha la seguente forma, in cui l'angolo di rotazione (in radianti) viene misurato dall'asse X, spostandosi in senso antiorario:

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

Come per la scalabilità, puoi utilizzare questa matrice direttamente come una trasformazione RELATIVE per ruotare un elemento, che però ne comporta la rotazione attorno all'origine della pagina. Per ruotare l'elemento attorno al suo centro o a un punto diverso, passa al frame di riferimento.

Riflessione

La riflessione riflette un elemento su una linea o un asse specifici. La matrice di trasformazione della riflessione di base degli assi x e y 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 la scalabilità, puoi utilizzare questa matrice direttamente come una trasformazione RELATIVE per riflettere un elemento, ma questo comporta la traduzione anche dell'elemento. Per riflettere l'elemento senza alcuna traduzione, passa al frame di riferimento.

Frame di riferimento degli elementi

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

Per trasformare un elemento all'interno del suo frame di riferimento, racchiudilo tra due altre traduzioni: una precedente traslazione T1 che sposta il centro dell'elemento sull'origine della pagina e una successiva traslazione T2 che riporta l'elemento nella posizione originale. L'operazione completa può essere espressa come prodotto matriciale:

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

Puoi anche passare ad altri sistemi di riferimento traducendo i punti nell'origine. Questi punti diventano il centro del nuovo frame di riferimento.

È possibile eseguire ciascuna di queste trasformazioni singolarmente come richieste di trasformazione RELATIVE sequenziali. Idealmente, dovresti precalcolare A' con moltiplicazioni matriciali e applicare il risultato come una singola trasformazione ABSOLUTE. In alternativa, precalcola il prodotto T2 * B * T1 e applicalo come singola trasformazione RELATIVE. Sono entrambe più efficienti in termini di operazioni API, ma inviano le richieste di trasformazione singolarmente.

Limitazioni

Alcuni campi relativi a dimensioni e posizionamento non sono compatibili con alcuni tipi di elementi della pagina. La tabella riportata di seguito riassume la compatibilità di alcuni elementi della pagina con i campi relativi alle dimensioni e al posizionamento.

Campo	Shape	Video	Tabella
Traduzioni	✔	✔	✔
Scala	✔	✔	No**
Taglio	✔	No	No

** Per aggiornare le dimensioni di riga e colonna della tabella, utilizza UpdateTableRowPropertiesRequest e UpdateTableColumnPropertiesRequest.

Tutti i campi relativi a dimensioni e posizionamento potrebbero restituire risultati imprevisti se l'elemento della pagina presenta un taglio. Tutte le limitazioni sono soggette a modifica. Per informazioni aggiornate, vedi API Presentazioni Google.

L'API Presentazioni potrebbe eseguire il refactoring dei valori

Quando crei un elemento di pagina, puoi specificare una dimensione e una trasformazione che forniscano un determinato risultato visivo. Tuttavia, l'API 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, se prendi in considerazione la trasformazione, dovresti ottenere gli stessi risultati.