Dimensionnement et positionnement des éléments d'une page

Ce guide explique comment définir la taille et la position des éléments de page à l'aide de transformations affines. Pour une introduction conceptuelle aux transformations affines, consultez le guide des concepts sur les transformations.

Transformer des éléments

L'API Slides vous permet de repositionner et de redimensionner des éléments sur une page. Pour ce faire, commencez par déterminer le type de transformation à appliquer, puis appliquez-la à l'aide de la méthode presentations.batchUpdate contenant un ou plusieurs éléments UpdatePageElementTransformRequest.

Les transformations peuvent être effectuées dans l'un des deux applyModes suivants:

• Les transformations ABSOLUTE remplacent la matrice de transformation existante de l'élément. Tous les paramètres que vous omettez de la requête de mise à jour de la transformation sont définis sur zéro.

• Les transformations RELATIVE sont multipliées par la matrice de transformation existante de l'élément (l'ordre de multiplication est important):

$$A' = BA$$

Les transformations relatives déplacent ou évaluent l'élément de page à partir de son emplacement actuel. Par exemple, vous pouvez déplacer une forme de 100 points vers la gauche ou la faire pivoter de 40 degrés. Les transformations absolues ignorent les informations de position et d'échelle existantes (par exemple, déplacer une forme au centre de la page ou la mettre à l'échelle pour qu'elle ait une largeur spécifique).

Les transformations complexes peuvent généralement être exprimées sous la forme d'une séquence de transformations plus simples. Le précalcul d'une transformation (combinaison de plusieurs transformations à l'aide de la multiplication matricielle) peut souvent réduire les frais généraux.

L'ordre des opérations de transformation est important. Dans la plupart des cas, faire pivoter un élément autour d'un point, puis le traduire produit des résultats différents que de le traduire d'abord.

Pour certaines opérations, vous devez connaître les paramètres de transformation existants d'un élément. Si vous ne disposez pas de ces valeurs, vous pouvez les récupérer à l'aide d'une requête presentations.pages.get.

Traduction

La traduction consiste simplement à déplacer un élément de page vers un nouvel emplacement sur la même page. Les translations absolues déplacent l'élément vers un point spécifique, tandis que les translations relatives déplacent l'élément d'une distance spécifique.

N'oubliez pas que les paramètres de translation spécifient la position du coin supérieur gauche de l'élément, et non son centre.

Une matrice de transformation de translation de base se présente sous la forme suivante:

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

Lorsque vous utilisez une UpdatePageElementTransformRequest pour traduire un élément (sans modifier sa taille, son cisaillement ni son orientation), vous pouvez utiliser l'une des structures AffineTransform suivantes:

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

Scaling

Le redimensionnement consiste à étirer ou à réduire un élément selon les dimensions X et/ou Y pour en modifier la taille. Une matrice de transformation de mise à l'échelle de base se présente sous la forme suivante:

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

Vous pouvez utiliser ce format de matrice directement en tant que transformation RELATIVE pour redimensionner un élément, mais cela peut également affecter le cisaillement et la translation affichés de l'élément. Pour redimensionner l'élément sans affecter son cisaillement ni sa translation, passez à son frame de référence.

Rotation

Les transformations de rotation font pivoter un élément de page autour d'un point, à l'aide des paramètres de mise à l'échelle et de distorsion. La matrice de transformation de rotation de base a la forme suivante, où l'angle de rotation (en radians) est mesuré à partir de l'axe X, en tournant dans le sens antihoraire:

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

Comme pour la mise à l'échelle, vous pouvez utiliser cette forme de matrice directement comme transformation RELATIVE pour faire pivoter un élément, mais l'élément est alors pivoté autour de l'origine de la page. Pour faire pivoter l'élément autour de son centre ou d'un autre point, passez à ce frame de référence.

Commentaire

La réflexion reflète un élément sur une ligne ou une axe spécifique. La matrice de transformation de base de réflexion sur les axes X et Y se présente sous les formes suivantes:

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

Comme pour la mise à l'échelle, vous pouvez utiliser cette forme de matrice directement comme une transformation RELATIVE pour refléter un élément, mais cela entraîne également la traduction de l'élément. Pour refléter l'élément sans aucune traduction, passez à son frame de référence.

Cadres de référence des éléments

Appliquer une transformation de base échelle, réflexion ou rotation directement à un élément de page produit une transformation dans le frame de référence de la page. Par exemple, une rotation de base fait pivoter l'élément autour de l'origine de la page (coin supérieur gauche). Toutefois, vous pouvez travailler dans le repère de l'élément lui-même, par exemple pour faire pivoter un élément autour de son point central.

Pour transformer un élément dans son propre frame de référence, encapsulez-le entre deux autres translations: une translation T1 précédente qui déplace le centre de l'élément vers l'origine de la page et une translation T2 suivante qui ramène l'élément à sa position d'origine. L'opération complète peut être exprimée sous forme de produit matriciel:

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

Vous pouvez également passer à d'autres repères en traduisant différents points vers l'origine. Ces points deviennent le centre du nouveau frame de référence.

Vous pouvez effectuer chacune de ces transformations individuellement en tant que requêtes de transformation RELATIVE séquentielles. Idéalement, vous devez précalculer A' ci-dessus avec des multiplications de matrices et appliquer le résultat en tant que transformation ABSOLUTE unique. Vous pouvez également précalculer le produit T2 * B * T1 et l'appliquer en tant que transformation RELATIVE unique. Ces deux méthodes sont plus efficaces, en termes d'opérations d'API, que d'envoyer les requêtes de transformation individuellement.

Limites

Certains champs de dimensionnement et de positionnement ne sont pas compatibles avec certains types d'éléments de page. Le tableau ci-dessous récapitule la compatibilité de certains éléments de page avec les champs de dimensionnement et de positionnement.

Champ	Forme	Vidéo	Tableau
Translation	✔	✔	✔
Scale	✔	✔	Non**
Coupe	✔	Non	Non

** Pour mettre à jour les dimensions des lignes et des colonnes de la table, utilisez UpdateTableRowPropertiesRequest et UpdateTableColumnPropertiesRequest.

Tous les champs de dimensionnement et de positionnement peuvent donner des résultats inattendus si l'élément de page est déformé. Toutes les restrictions sont susceptibles d'être modifiées. Pour obtenir des informations à jour, consultez la page API Google Slides.

L'API Slides peut refactoriser vos valeurs

Lorsque vous créez un élément de page, vous pouvez spécifier une taille et une transformation qui fournissent un certain résultat visuel. Toutefois, l'API peut remplacer les valeurs que vous avez fournies par d'autres qui donnent la même apparence visuelle. En général, si vous écrivez une taille à l'aide de l'API, vous n'êtes pas assuré de recevoir la même taille en retour. Toutefois, vous devriez obtenir les mêmes résultats si vous tenez compte de la transformation.