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

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

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

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

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

• ‫ABSOLUTE transforms replace the element's existing transformation matrix. כל הפרמטרים שלא נכללים בבקשה לעדכון השינוי מוגדרים לאפס.

• טרנספורמציות 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 מאשר שליחת בקשות ההמרה בנפרד.

מגבלות

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

שדה	צורה	וידאו	טבלה
תרגום	✔	✔	✔
קנה מידה	✔	✔	לא**
Shear	✔	לא	לא

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

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

ערכים שעברו רפקטורינג

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