Dimensioni e posizione degli elementi della pagina

Questa guida spiega come impostare le dimensioni e la posizione degli elementi della pagina utilizzando le trasformazioni affine con l'API Google Presentazioni. Per un'introduzione concettuale alle trasformazioni affine, consulta la guida ai concetti su Trasformazioni ed elementi di pagina.

Trasformare gli elementi

L'API Slides ti consente di riposizionare e ridimensionare gli elementi di una pagina. Per farlo, determina innanzitutto 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:

• ABSOLUTE trasforma 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 con la matrice di trasformazione esistente dell'elemento (l'ordine di moltiplicazione è importante):

$$A' = BA$$

Le trasformazioni relative spostano o scalano l'elemento della pagina da dove si trova. 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 lo spostamento di una forma al centro della pagina o la sua ridimensionamento in base a una larghezza specifica.

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

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

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 traduzione è l'azione di spostare un elemento di pagina in una nuova posizione nella stessa pagina. Le traslazioni assolute spostano l'elemento in un punto specifico, mentre quelle relative lo spostano 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 della traduzione ha la forma:

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

Quando utilizzi un UpdatePageElementTransformRequest per tradurre un elemento (senza modificarne le dimensioni, la distorsione 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

La scalatura è l'azione di allungamento o compressione di un elemento lungo la dimensione X o Y per modificarne le dimensioni. Una matrice di trasformazione di scala di base ha la forma:

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

Puoi utilizzare questa forma di matrice direttamente come trasformazione RELATIVE per ridimensionare un elemento, ma questo può influire anche sulla distorsione e sulla traslazione visualizzate dell'elemento. Per ridimensionare l'elemento senza influire sulla sua inclinazione o traslazione, passa al suo frame di riferimento dell'elemento.

Rotazione

Le trasformazioni di rotazione ruotano un elemento della pagina attorno a un punto utilizzando i parametri di scala e inclinazione. La matrice di trasformazione di rotazione di base ha la seguente forma, dove l'angolo di rotazione (in radianti) viene misurato dall'asse X, muovendosi 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 forma di matrice direttamente come RELATIVE trasformazione per ruotare un elemento, ma questo 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, passa al frame di riferimento dell'elemento.

Riflessione

La riflessione riflette un elemento lungo una linea o un asse specifici. La matrice di trasformazione di base per la riflessione sull'asse x e sull'asse 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 scalatura, puoi utilizzare questa forma di matrice direttamente come trasformazione RELATIVE per riflettere un elemento, ma questo fa sì che l'elemento venga tradotto. Per riflettere l'elemento senza alcuna traduzione, passa al relativo frame di riferimento dell'elemento.

Frame di riferimento degli elementi

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

Per trasformare un elemento all'interno del proprio sistema di riferimento, racchiudilo tra due altre traslazioni: una precedente T1 che sposta il centro dell'elemento all'origine della pagina e una successiva T2 che riporta l'elemento alla sua posizione originale. L'operazione completa 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 frame di riferimento.

È possibile eseguire ciascuna di queste trasformazioni singolarmente come richieste di trasformazione RELATIVE sequenziali. Idealmente, dovresti precalcolare A' sopra con le moltiplicazioni di matrici e applicare il risultato come singola trasformazione ABSOLUTE. In alternativa, precompila il prodotto T2 * B * T1 e applicalo come una singola trasformazione RELATIVE. Entrambe 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	Shape	Video	Tabella
Traduzioni	✔	✔	✔
Scala	✔	✔	No**
Cisare	✔	No	No

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

Tutti i campi di dimensionamento e posizionamento potrebbero dare risultati imprevisti se l'elemento della pagina ha una distorsione. 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 per ottenere un determinato risultato visivo. Tuttavia, l'API Slides potrebbe sostituire i valori forniti con altri che hanno la stessa rappresentazione visiva. In genere, se scrivi una dimensione utilizzando l'API, non è garantito che ti venga restituita la stessa dimensione. Tuttavia, dovresti ottenere gli stessi risultati se prendi in considerazione la trasformazione.