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 ai concetti sulle trasformazioni.

Trasformare gli elementi

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

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

  • 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 dalla posizione corrente, 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.

Per alcune operazioni, devi conoscere 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 è semplicemente l'azione di spostare un elemento di pagina in una nuova posizione all'interno della stessa pagina. Le traslazioni assolute spostano l'elemento in un punto specifico, mentre le traslazioni relative lo spostano di una distanza specifica.

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'
  }
}

Scalabilità

La scalatura è l'azione di allungamento o compressione di un elemento lungo la dimensione X e/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 sistema di riferimento.

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 intorno all'origine della pagina. Per ruotare l'elemento attorno al suo centro o a un altro punto, passa a quel sistema di riferimento.

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 scalabilità, puoi utilizzare questa forma di matrice direttamente come trasformazione RELATIVE per riflettere un elemento, ma questo fa sì che l'elemento venga tradotto anche. Per riflettere l'elemento senza alcuna traduzione, passa al suo sistema 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 attorno all'origine della pagina (l'angolo in alto a sinistra). Tuttavia, puoi operare nel sistema di riferimento dell'elemento stesso, ad esempio per ruotarlo 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, traducendo punti diversi in 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 ABSOLUTE trasformazione. In alternativa, precompila il prodotto T2 * B * T1 e applicalo come 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 restituire risultati imprevisti se l'elemento della pagina presenta una distorsione. Tutte le limitazioni sono soggette a modifica. Per informazioni aggiornate, consulta l'API Google Slides.

L'API Slides potrebbe eseguire il refactoring dei valori

Quando crei un elemento della pagina, puoi specificare una dimensione e una trasformazione per ottenere un determinato risultato visivo. Tuttavia, l'API potrebbe sostituire i valori forniti con altri che hanno la stessa rappresentazione visiva. 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 prendi in considerazione la trasformazione.