Tailler et positionner les éléments de la page

Ce guide explique comment dimensionner et positionner les éléments d'une page à l'aide de transformations affines avec l'API Google Slides. Pour une introduction conceptuelle aux transformations affines, consultez le guide conceptuel Transformations et éléments de page.

Transformer des éléments

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

Les transformations peuvent être effectuées à l'aide d'un ApplyMode :

• ABSOLUTE transforme replace la matrice de transformation existante de l'élément. Tous les paramètres que vous omettez dans 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 mettent à l'échelle l'élément de page à partir de son emplacement actuel. Par exemple, déplacer une forme de 100 points vers la gauche ou la faire pivoter de 40 degrés. Les transformations absolues suppriment les informations de position et d'échelle existantes. Par exemple, elles permettent de déplacer une forme au centre de la page ou de la redimensionner pour qu'elle ait une largeur spécifique.

Les transformations complexes peuvent généralement être exprimées sous forme de 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, la rotation d'un élément autour d'un point, puis sa translation, produisent des résultats différents de ceux obtenus en le traduisant 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 de la méthode presentations.pages.get().

Traduction

La translation consiste à déplacer un élément de page vers un nouvel emplacement 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 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 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 un 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'
  }
}

Échelle

La mise à l'échelle consiste à étirer ou à comprimer un élément le long de la dimension X ou Y pour modifier sa 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 comme transformation RELATIVE pour redimensionner un élément, mais cela peut également affecter la déformation et la translation de l'élément rendu. Pour mettre à l'échelle l'élément sans affecter son cisaillement ni sa translation, passez à son cadre de référence d'élément.

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 cisaillement. 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, 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 comme transformation RELATIVE pour faire pivoter un élément, mais cela entraîne la rotation de l'élément autour de l'origine de la page. Pour faire pivoter l'élément autour de son centre ou d'un autre point, passez à ce repère d'élément.

Commentaire

La réflexion reflète un élément sur une ligne ou un axe spécifique. Les matrices de transformation de réflexion de base des axes X et Y se présentent comme suit :

$$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 matricielle directement comme transformation RELATIVE pour refléter un élément, mais cela entraîne également la translation de l'élément. Pour refléter l'élément sans aucune traduction, passez à son frame de référence d'élément.

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

L'application d'une transformation de mise à l'échelle, de rotation ou de symétrie de base directement à un élément de page produit 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 (l'angle supérieur gauche). Toutefois, vous pouvez opérer dans le cadre de référence de l'élément, 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 translations : une translation précédente T1 qui déplace le centre de l'élément vers l'origine de la page, et une translation suivante T2 qui replace 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 passer à d'autres cadres de référence en traduisant différents points à l'origine. Ces points deviennent le centre du nouveau repère.

Il est possible d'effectuer chacune de ces transformations individuellement sous forme de requêtes de transformation RELATIVE séquentielles. Dans l'idéal, vous devez précalculer A' ci-dessus avec des multiplications matricielles 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 l'envoi individuel des requêtes de transformation.

Limites

Certains champs de dimensionnement et de positionnement ne sont pas compatibles avec certains types d'éléments de page. Le tableau suivant 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**
Cisaillement	✔	Non	Non

Pour mettre à jour les dimensions des lignes et des colonnes du 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 limites sont susceptibles d'être modifiées. Pour obtenir des informations à jour, consultez la page API Google Slides.

Valeurs refactorisées

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 Slides peut remplacer les valeurs que vous avez fournies par d'autres qui produisent le même aspect visuel. En général, si vous spécifiez une taille à l'aide de l'API, vous n'êtes pas sûr d'obtenir la même taille. Toutefois, vous devriez obtenir les mêmes résultats si vous tenez compte de la transformation.