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

Ce guide explique comment dimensionner et positionner les éléments de page à l'aide de transformations affines. Pour une présentation des concepts de transformation affine, consultez le guide conceptuel des transformations.

Transformer des éléments

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

Les transformations peuvent être effectuées dans l'une des deux méthodes suivantes : applyModes :

• Les transformations ABSOLUTE remplacent la matrice de transformation existante de l'élément. Tous les paramètres que vous omettez dans la requête de mise à jour de 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 mettent à l'échelle l'élément de page à partir de son emplacement actuel, par exemple en déplaçant une forme de 100 points vers la gauche ou en la faisant pivoter de 40 degrés. Les transformations absolues suppriment les informations de position et d'échelle existantes (par exemple, déplacement d'une forme au centre de la page ou mise à l'échelle en fonction d'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 (combinant plusieurs transformations par multiplication de matrices) permet souvent de réduire les frais généraux.

L'ordre des opérations de transformation est important. Dans la plupart des cas, la rotation d'un élément autour d'un point, puis la traduction produit des résultats différents de ceux de la première traduction.

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 une nouvelle position sur la même page. Les traductions absolues déplacent l'élément vers un point spécifique, tandis que les traductions relatives le déplacent sur une distance spécifique.

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

Une matrice de transformation de traduction de base se présente comme suit:

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

Lorsque vous utilisez 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'
  }
}

Mise à l'échelle

La mise à l'échelle est l'action qui consiste à étirer ou à presser un élément le long des dimensions X et/ou Y pour en modifier la taille. Une matrice de transformation de scaling de base se présente comme suit:

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

Vous pouvez utiliser cette forme matricielle directement en tant que transformation RELATIVE pour redimensionner un élément, mais cela peut également affecter le cisaillement et la translation de l'élément. Pour mettre à l'échelle l'élément sans modifier son cisaillement ou sa translation, passez à son image 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 découpage. La matrice de transformation de rotation de base se présente comme suit, où l'angle de rotation (en radians) est mesuré à partir de l'axe X, se déplaçant dans le sens inverse des aiguilles d'une montre:

$$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 matricielle directement en tant que transformation RELATIVE pour faire pivoter un élément, mais cela entraîne une rotation de l'élément par rapport à l'origine de la page. Pour faire pivoter l'élément vers son centre ou vers un point différent, passez à ce cadre de référence.

Commentaire

La réflexion met en miroir un élément sur une ligne ou un axe spécifique. La matrice de transformation de base de la réflexion des 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 le scaling, vous pouvez utiliser cette forme matricielle directement en tant que transformation RELATIVE pour refléter un élément, mais celui-ci se traduit également. Pour refléter l'élément sans aucune translation, passez à son cadre de référence.

Cadres de référence d'éléments

L'application directe d'une transformation d'échelle, de réflexion ou de rotation de base à un élément de page entraîne une transformation dans le cadre 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 (angle supérieur gauche). Toutefois, vous pouvez effectuer des opérations dans le cadre de référence 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 cadre de référence, placez-le entre deux autres traductions: une traduction précédente T1 qui déplace le centre de l'élément vers le point d'origine de la page, et une traduction T2 suivante qui remet l'élément à sa position d'origine. L'opération complète peut être exprimée sous la forme d'un produit matriciel:

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

Vous pouvez également basculer vers d'autres frames de référence en traduisant différents points vers l'origine. Ces points deviennent le centre du nouveau cadre de référence.

Il est possible d'effectuer chacune de ces transformations individuellement sous forme de requêtes de transformation RELATIVE séquentielles. Idéalement, vous devez précalculer A' ci-dessus avec des multiplications matricielles et appliquer le résultat sous la forme d'une seule transformation ABSOLUTE. Vous pouvez également précalculer le produit T2 * B * T1 et l'appliquer en une seule transformation RELATIVE. Ces deux méthodes sont plus efficaces en termes d'opérations d'API, car elles envoient 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 la page avec les champs de dimensionnement et de positionnement.

Champ	Forme	Vidéo	Table
Traduction	✔	✔	✔
Scale	✔	✔	Non**
Citrage	✔	Non	Non

** Pour mettre à jour les dimensions des lignes et des colonnes d'un tableau, utilisez UpdateTableRowPropertiesRequest et UpdateTableColumnPropertiesRequest.

Tous les champs de dimensionnement et de positionnement peuvent donner des résultats inattendus si l'élément de la page est cisaillé. Toutes les limitations sont susceptibles d'être modifiées. Pour obtenir les 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. Cependant, l'API peut remplacer les valeurs 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, il n'est pas garanti que la même taille s'affiche. Cependant, vous devriez obtenir les mêmes résultats si vous prenez la transformation en compte.