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 scalare gli elementi di una pagina. Per farlo, determina prima il tipo di trasformazione da applicare e poi applicala utilizzando il metodo contenente uno o più elementi.presentations.batchUpdate()UpdatePageElementTransformRequest

Le trasformazioni possono essere eseguite utilizzando un ApplyMode:

• 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 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 di pagina dalla sua posizione attuale. Ad esempio, spostare una forma di 100 punti a sinistra o ruotarla di 40 gradi. Le trasformazioni assolute ignorano le informazioni esistenti su posizione e scala; ad esempio, spostare una forma al centro della pagina o scalarla 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 utilizzando la moltiplicazione di matrici, può spesso ridurre il sovraccarico.

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 dell'elemento e poi alla rotazione.

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

Traslazione

La traslazione è 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 traslazioni relative spostano l'elemento di una distanza specifica.

Tieni presente 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 formato:

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

Quando utilizzi un 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

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

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

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

Rotazione

Le trasformazioni di rotazione ruotano un elemento di pagina attorno a un punto, utilizzando i parametri di scalatura e taglio. La matrice di trasformazione di rotazione di base ha il seguente formato, in cui 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 la scalatura, puoi utilizzare direttamente questo formato di matrice come trasformazione RELATIVE per ruotare un elemento, ma in questo modo l'elemento viene ruotato attorno all'origine della pagina. Per ruotare l'elemento attorno al suo centro o a un punto diverso, passa al relativo frame di riferimento.

Riflessione

La riflessione riflette un elemento su una linea o un asse specifico. La matrice di trasformazione di riflessione di base dell'asse X e dell'asse Y ha i seguenti formati:

$$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 direttamente questo formato di matrice come trasformazione RELATIVE per riflettere un elemento, ma in questo modo l'elemento viene anche traslato. Per riflettere l'elemento senza alcuna traslazione, passa al relativo frame di riferimento elemento.

Frame di riferimento degli elementi

L'applicazione di una trasformazione di scalatura di base , 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 (l'angolo in alto a sinistra). Tuttavia, puoi operare nel frame di riferimento dell'elemento, 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 traslazioni: una traslazione precedente T1 che sposta il centro dell'elemento all'origine della pagina e una traslazione successiva T2 che riporta l'elemento nella sua posizione originale. L'operazione completa può essere espressa come un prodotto di matrici:

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

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

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

Limitazioni

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

Campo	Forma	Video	Tabella
Traslazione	✔	✔	✔
Scala	✔	✔	No**
Taglio	✔	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 fornire risultati imprevisti se l'elemento della pagina è tagliato. Tutte le limitazioni sono soggette a modifiche. Per informazioni aggiornate, consulta 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 hai la garanzia di ricevere la stessa dimensione. Tuttavia, dovresti ottenere gli stessi risultati se tieni conto della trasformazione.