Ridimensionamento e posizionamento degli elementi di pagina

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

Trasformare gli elementi

L'API Presentazioni consente di riposizionare e ridimensionare gli elementi di una pagina. A questo scopo, determina innanzitutto il tipo di trasformazione da applicare, quindi applica quella trasformazione utilizzando il metodo presentations.batchUpdate contenente uno o più elementi UpdatePageElementTransformRequest.

Le trasformazioni possono essere eseguite in uno dei due seguenti modi applyModes:

• Le trasformazioni ABSOLUTE sostituiscono la matrice di trasformazione esistente dell'elemento. Tutti i parametri omessi dalla richiesta di aggiornamento della trasformazione vengono impostati su zero.

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

$$A' = BA$$

Le trasformazioni relative spostano o ridimensionano l'elemento di pagina rispetto a dove si trova attualmente, ad esempio spostando una forma di 100 punti a sinistra o ruotandola di 40 gradi. Le trasformazioni assolute ignorano le informazioni esistenti sulla posizione e sulla scala; ad esempio, sposta una forma al centro della pagina o scalala per ottenere una larghezza specifica.

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

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

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

Traduzione

La traduzione non è altro che l'azione di spostare un elemento di pagina in una nuova posizione sulla stessa pagina. Le traduzioni assolute spostano l'elemento in un punto specifico, mentre le traduzioni relative spostano l'elemento a 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 il seguente aspetto:

$$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 di 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à

Il ridimensionamento è l'azione di allungare o stringere 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 questa matrice direttamente come una trasformazione RELATIVE per ridimensionare un elemento, ma ciò può anche influire sul taglio e sulla traslazione dell'elemento visualizzato. Per ridimensionare l'elemento senza influire sul taglio o sulla traslazione, spostati al frame di riferimento.

Rotazione

Le trasformazioni di rotazione ruotano un elemento di pagina intorno a un punto, utilizzando i parametri di scalabilità e shear. La matrice della trasformazione di rotazione di base ha la seguente forma, in cui l'angolo di rotazione (in radianti) viene misurato a partire dall'asse X, in movimento 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, ma questo determina la rotazione dell'elemento rispetto all'origine della pagina. Per ruotare l'elemento attorno al suo centro o a un punto diverso, vai al frame di riferimento.

Riflessione

Il riflesso esegue il mirroring di un elemento lungo una linea o un asse specifico. La matrice di trasformazione della 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 la scalabilità, puoi utilizzare questa forma di matrice direttamente come una trasformazione RELATIVE per riflettere un elemento, ma questo fa sì che anche l'elemento traduca. Per riflettere l'elemento senza traslazione, vai al suo frame di riferimento.

Frame di riferimento degli elementi

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

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

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

Puoi anche passare ad altri frame di riferimento, traducendo invece punti diversi 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' sopra con le moltiplicazioni delle matrici 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 e 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 di pagina con i campi relativi a dimensioni e posizionamento.

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

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

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

L'API Presentazioni potrebbe ridefinire i tuoi valori

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