שינוי הגודל והמיקום של רכיבי הדף

במדריך הזה נסביר איך לשנות את הגודל והמיקום של רכיבי דף באמצעות טרנספורמציות אליפטיות באמצעות Google Slides API. מבוא מושגי לטרנספורמציות אליפטיות זמין במדריך המושגים טרנספורמציות ואלמנטי דף.

שינוי אלמנטים

באמצעות Slides API אפשר לשנות את המיקום והגודל של רכיבים בדף. כדי לעשות זאת, קודם צריך לקבוע איזה סוג טרנספורמציה צריך להחיל, ואז להחיל את הטרנספורמציה באמצעות השיטה presentations.batchUpdate() שמכילה רכיב UpdatePageElementTransformRequest אחד או יותר.

אפשר לבצע טרנספורמציות באמצעות ApplyMode:

• טרנספורמציות ABSOLUTE מחליפות את מטריצת הטרנספורמציה הקיימת של האלמנט. פרמטרים שתשמטו מהבקשה לעדכון הטרנספורמציה יוגדרו לאפס.

• מכפילים את הטרנספורמציות של RELATIVE במטריית הטרנספורמציה הקיימת של הרכיב (סדר המכפלה חשוב):

$$A' = BA$$

טרנספורמציות יחסיות מעבירות או משנות את קנה המידה של רכיב הדף מהמיקום שלו. לדוגמה, העברת צורה 100 נקודות שמאלה או סיבוב שלה ב-40 מעלות. טרנספורמציות אבסולוטיות מבטלות את המידע הקיים על המיקום והגודל. לדוגמה, העברת צורה למרכז הדף או שינוי הגודל שלה לרוחב ספציפי.

בדרך כלל אפשר לבטא טרנספורמציות מורכבות כרצף של טרנספורמציות פשוטות יותר. לרוב, חישוב מראש של טרנספורמציה – שילוב של כמה טרנספורמציות באמצעות כפל מטריצות – יכול לצמצם את התקורה.

סדר פעולות הטרנספורמציה חשוב – ברוב המקרים, סיבוב של רכיב סביב נקודה ואז תרגום שלו מניב תוצאות שונות מאשר תרגום קודם.

בחלק מהפעולות, צריך לדעת מהם הפרמטרים הקיימים של הטרנספורמציה של האלמנט. אם אין לכם את הערכים האלה, תוכלו לאחזר אותם באמצעות השיטה presentations.pages.get().

תרגום

העברה היא פעולה של העברת רכיב דף למיקום חדש באותו דף. בתרגומים מוחלטים, הרכיב מועבר לנקודה ספציפית, ובתרגומים יחסיים הוא מועבר למרחק ספציפי.

חשוב לזכור שפרמטרים של תרגום מציינים את המיקום של הפינה הימנית העליונה של הרכיב, ולא את מרכזו.

מטריצת טרנספורמציה בסיסית של תרגום נראית כך:

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

כשמשתמשים ב-UpdatePageElementTransformRequest כדי לתרגם רכיב (בלי לשנות את הגודל, הטיה או הכיוון שלו), אפשר להשתמש באחת מהמבנים הבאים של 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'
  }
}

קנה מידה

שינוי קנה מידה הוא פעולה של מתיחה או כיווץ של רכיב לאורך המאפיין X או Y כדי לשנות את הגודל שלו. מטריצת שינוי בסיסית של שינוי קנה מידה היא בפורמט:

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

אפשר להשתמש בפורמט המטריצה הזה ישירות כטרנספורמציה של RELATIVE כדי לשנות את הגודל של רכיב, אבל זה יכול להשפיע גם על ההזזה וההטיה של הרכיב ברינדור. כדי לשנות את קנה המידה של הרכיב בלי להשפיע על הזזה או על הטיה שלו, עוברים למסגרת העזר של הרכיב.

סיבוב

טרנספורמציות של סיבוב מסובבות רכיב בדף סביב נקודה, באמצעות הפרמטרים של שינוי קנה המידה וההזזה. המטריצה הבסיסית של טרנספורמציית הסיבוב היא בפורמט הבא, כאשר זווית הסיבוב (ברדיאנים) נמדדת מצייר X, ומתקדמת בכיוון השעון:

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

בדומה לשינוי קנה המידה, אפשר להשתמש בפורמט המטריצה הזה ישירות כטרנספורמציה RELATIVE כדי לסובב אלמנט, אבל הפעולה הזו גורמת לסיבוב של האלמנט סביב המקור של הדף. כדי לסובב את הרכיב סביב מרכזו או סביב נקודה אחרת, צריך לעבור למסגרת העזר של הרכיב.

השתקפות

השתקפות משקפת רכיב לאורך קו או ציר ספציפיים. המטריצה הבסיסית של טרנספורמציית ההשתקפות של ציר x ושל ציר y היא בפורמטים הבאים:

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

בדומה לשינוי קנה המידה, אפשר להשתמש בפורמט המטריצה הזה ישירות כטרנספורמציה RELATIVE כדי לשקף רכיב, אבל הפעולה הזו גורמת גם לתרגום של הרכיב. כדי לשקף את הרכיב ללא תרגום, עוברים למסגרת העזר של הרכיב.

מסגרות עזר של רכיבים

החלת טרנספורמציה בסיסית של שינוי קנה מידה, סיבוב או השתקפות ישירות על רכיב בדף יוצרת טרנספורמציה במסגרת העזר של הדף. לדוגמה, בכיוון יסודי הרכיב מסתובב סביב מקור הדף (הפינה הימנית העליונה). עם זאת, אפשר לפעול במסגרת העזר של הרכיב, למשל כדי לסובב רכיב סביב נקודת המרכז שלו.

כדי לבצע טרנספורמציה של רכיב בתוך מסגרת העזר שלו, צריך להקיף אותו בשתי תרגומים אחרים: תרגום מקדים T1 שנעביר את מרכז הרכיב למקור הדף, ותרגום עוקב T2 שיעביר את הרכיב חזרה למיקום המקורי שלו. אפשר לבטא את הפעולה המלאה כמכפלת מטריצות:

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

אפשר גם לעבור למסגרות עזר אחרות, על ידי תרגום של נקודות שונות למקור. הנקודות האלה הופכות למרכז של מסגרת העזרה החדשה.

אפשר לבצע כל אחד מהטרנספורמציות האלה בנפרד, כבקשות טרנספורמציה של RELATIVE ברצף. באופן אידיאלי, כדאי לחשב מראש את A' שלמעלה באמצעות כפל מטריצות ולהחיל את התוצאה כטרנספורמציה יחידה של ABSOLUTE. לחלופין, אפשר לחשב מראש את המכפלה T2 * B * T1 ולהחיל אותה כטרנספורמציה יחידה של RELATIVE. שתי האפשרויות האלה יעילות יותר מבחינת פעולות ה-API, בהשוואה לשליחת בקשות הטרנספורמציה בנפרד.

מגבלות

חלק משדות הגודל והמיקום לא תואמים לסוגים מסוימים של רכיבי דף. בטבלה הבאה מפורטת התאימות של רכיבי דף מסוימים לשדות של הגדרת גודל ומיקום:

שדה	צורה	וידאו	טבלה
תרגום	✔	✔	✔
התאמה לעומס (scale)	✔	✔	לא**
שינוי כיוון	✔	לא	לא

כדי לעדכן את המאפיינים של השורות והעמודות בטבלה, משתמשים ב-UpdateTableRowPropertiesRequest וב-UpdateTableColumnPropertiesRequest.

אם יש שינוי בזווית של רכיב הדף, כל השדות של הגודל והמיקום עשויים להניב תוצאות בלתי צפויות. כל המגבלות עשויות להשתנות. למידע עדכני, אפשר לעיין במאמר Google Slides API.

ערכים שעברו פיתוח מחדש

כשיוצרים רכיב דף, אפשר לציין גודל וטרנספורמציה שיספקו תוצאה חזותית מסוימת. עם זאת, יכול להיות ש-Slides API יחליף את הערכים שסיפקתם בערכים אחרים שיוצרים את אותו מראה חזותי. באופן כללי, אם כותבים גודל באמצעות ה-API, אין ערובה לכך שהגודל שיוחזר יהיה זהה. עם זאת, אם מביאים בחשבון את הטרנספורמציה, התוצאות אמורות להיות זהות.