Google Slides API מאפשר לכם לשנות את המיקום, הגודל והכיוון של PageElement (תיבות טקסט, תמונות, טבלאות וצורות בסיסיות) בדף, תוך שמירה על קווים ישרים ועל נקודות וקווים מקבילים. הן נקראות טרנספורמציות אפיניות. בדוגמאות שבהמשך מוצגות כמה פעולות נפוצות של שינוי רכיבי דף באמצעות השיטה presentations.batchUpdate.
בדוגמאות האלה נעשה שימוש במשתנים הבאים:
- PRESENTATION_ID— מציין איפה צריך לספק את מזהה המצגת. אפשר למצוא את הערך של המזהה הזה בכתובת ה-URL של המצגת.
- PAGE_ID – מציין איפה מציינים את המזהה של אובייקט הדף. אפשר לאחזר את הערך של המאפיין הזה מכתובת ה-URL או באמצעות בקשת קריאה של API.
- PAGE_ELEMENT_ID – מציין את המקום שבו צריך לספק את מזהה אובייקט רכיב הדף. אפשר לציין את המזהה הזה לרכיבים שיוצרים (עם הגבלות מסוימות) או לאפשר ל-Slides API ליצור אותו באופן אוטומטי. אפשר לאחזר מזהי רכיבים באמצעות בקשת קריאה של API.
הדוגמאות האלה מוצגות כבקשות HTTP כדי שלא יהיו תלויות בשפה. מידע על הטמעה של חבילת עדכונים בשפות שונות באמצעות ספריות לקוח של Google API מופיע במאמר הוספת צורות וטקסט.
דוגמה לצורת חץ
בדוגמאות הבאות, נניח שקיים מרכיב דף של צורת חץ לדוגמה עם נתוני הגודל והטרנספורמציה הבאים (שאפשר למצוא באמצעות בקשת שיטת presentations.pages.get). הצורה לדוגמה משתמשת במידה unit EMU (יחידה מטרית אנגלית) וב-pt (נקודה).
{
"objectId": PAGE_ELEMENT_ID,
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 0.3,
"scaleY": 0.12,
"shearX": 0,
"shearY": 0,
"translateX": 2000000,
"translateY": 550000,
"unit": "EMU"
},
"shape": {
"shapeType": "RIGHT_ARROW"
}
}איך מיישרים רכיב עם רכיב אחר
בדוגמת הקוד הבאה presentations.batchUpdate אפשר לראות איך משתמשים בשיטה CreateShapeRequest כדי ליצור צורות חדשות במיקומים הנכונים, שמוצבות בהתאמה לצורת החץ לדוגמה בדף. בשני המקרים, צריך לחשב את קואורדינטות X ו-Y של הפינה הימנית העליונה של הצורה החדשה.
הבקשה הראשונה יוצרת מלבן בגודל 100 על 50 נקודות, שמוצב בהתאמה לגבול השמאלי של צורת החץ, אבל במרחק של 50 נקודות (50 * 12,700 = 635,000 EMU) מתחת לקצה העליון של החץ. קואורדינטת ה-X של המלבן החדש צריכה להיות זהה לקואורדינטת ה-X של החץ כדי שהגבול השמאלי שלו יהיה מיושר. הקואורדינטה Y זהה לקואורדינטה Y של החץ בתוספת 50 נקודות, כי המרחק נמדד מהחלק העליון של החץ. לכן, הקואורדינטות של המלבן הן:
x" = 2000000 EMU y" = 550000 + (50 * 12700) = 1185000 EMU
הבקשה השנייה יוצרת עיגול ברוחב 40 נקודות, עם אותו קו מרכז אופקי כמו החץ בדוגמה, אבל הוא ממוקם 100 נקודות (1,270,000 EMU) מימין לקצה הימני של החץ. קואורדינטת ה-X של העיגול היא הסכום של קואורדינטת ה-X של החץ, רוחב החץ ו-100 נקודות. כדי לאכוף יישור של המעגל החדש לקו האמצע, צריך לקחת בחשבון את הגובה של החץ ושל המעגל. הקואורדינטה Y של העיגול היא הקואורדינטה Y של החץ בתוספת חצי מגובה החץ פחות חצי מגובה העיגול. בשני המקרים, צריך לקחת בחשבון גם את גורמי קנה המידה שמשויכים לחץ, כי הם משפיעים על הרוחב והגובה של החץ שמוצג. לכן הקואורדינטות של העיגול הן:
x = 2000000 + (0.3 * 3000000) + (100 * 12700) = 4170000 EMU y = 550000 + (0.5 * 0.12 * 3000000) - (0.5 * 40 * 12700) = 476000 EMU
הפרוטוקול הבא הוא פרוטוקול הבקשה ליישור רכיב עם רכיב אחר:
POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
"requests": [
{
"createShape": {
"shapeType": "RECTANGLE",
"elementProperties": {
"pageObjectId": PAGE_ID,
"size": {
"width": {
"magnitude": 100,
"unit": "PT"
},
"height": {
"magnitude": 50,
"unit": "PT"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": 2000000,
"translateY": 1185000,
"unit": "EMU"
}
}
}
},
{
"createShape": {
"shapeType": "ELLIPSE",
"elementProperties": {
"pageObjectId": PAGE_ID,
"size": {
"width": {
"magnitude": 40,
"unit": "PT"
},
"height": {
"magnitude": 40,
"unit": "PT"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": 4170000,
"translateY": 476000,
"unit": "EMU"
}
}
}
}
]
}העברת רכיב
בדוגמת הקוד הבאה של presentations.batchUpdate אפשר לראות איך להשתמש בשיטה UpdatePageElementTransformRequest כדי לתרגם את רכיב הדף example arrow shape בשתי דרכים שונות.
הבקשה הראשונה באצווה מעבירה את החץ לקואורדינטות (X,Y) = (2000000, 150000) EMU (באמצעות absolute translation
applyMode). הבקשה השנייה באצווה מעבירה את החץ משם, הפעם 40,000 EMU ימינה ו-35,000 EMU למעלה (באמצעות relative translation applyMode). מטריצות transformation1 שבהן נעשה שימוש בנויות כך שהן לא ישנו את הגודל והכיוון של הרכיב.
אחרי שמבצעים את שתי הבקשות, הפינה הימנית העליונה של החץ נמצאת בקואורדינטה (X,Y) = (2040000, 115000) EMU.
הפרוטוקול לבקשה להעברת רכיב:
POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
"requests": [
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "ABSOLUTE",
"transform": {
"scaleX": 0.3,
"scaleY": 0.12,
"translateX": 2000000,
"translateY": 150000,
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": 40000,
"translateY": -35000,
"unit": "EMU"
}
}
}
]
}שיקוף של רכיב
בדוגמת הקוד הבאה של presentations.batchUpdate אפשר לראות איך משתמשים בשיטה UpdatePageElementTransformRequest כדי לשקף אופקית את רכיב הדף example arrow shape לאורך המרכז שלו, בלי לשנות את המיקום שלו בדף או את קנה המידה שלו.
הפעולה הזו מתבצעת באמצעות טרנספורמציה של השתקפות בסיסית במסגרת ההפניה של הרכיב. לשם הבהרה, ההזזה והשיקוף של מסגרת הייחוס מוצגים באמצעות שלוש קריאות נפרדות לשיטה UpdatePageElementTransformRequest, אבל יעיל יותר לחשב מראש את המכפלה של מטריצות הטרנספורמציה האלה ואז להחיל את המכפלה הזו כבקשה אחת.
בטרנספורמציות של תרגום, מרכז הצורה של החץ מוזז אל נקודת האפס וממנה. ערכי הפרמטרים מוצגים כחישובים לשם הבהרה.
הפרוטוקול לבקשה להצגת רכיב:
POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
"requests": [
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": -2000000 - 0.5 * 0.3 * 3000000,
"translateY": -550000 - 0.5 * 0.12 * 3000000,
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": -1,
"scaleY": 1,
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": 2000000 + 0.5 * 0.3 * 3000000,
"translateY": 550000 + 0.5 * 0.12 * 3000000,
"unit": "EMU"
}
}
}
]
}שינוי הגודל של רכיב
בדוגמה הבאה של דוגמת קוד presentations.batchUpdate אפשר לראות איך משתמשים בשיטה UpdatePageElementTransformRequest כדי לשנות את גודל מרכיב הדף example arrow shape כך שיהיה רחב ב-50% וגובהו יהיה רק 80% מהגובה הנוכחי, תוך שמירה על המיקום של מרכז החץ ועל הכיוון שלו.
הפעולה הזו מתבצעת באמצעות טרנספורמציה בסיסית של שינוי גודל במסגרת ההפניה של הרכיב. לשם הבהרה, ההזזה והשינוי של מסגרת ההתייחסות מוצגים באמצעות שלוש קריאות נפרדות לשיטה UpdatePageElementTransformRequest, אבל יעיל יותר לחשב מראש את המכפלה של מטריצות הטרנספורמציה האלה ואז להחיל את המכפלה הזו כבקשה אחת.
בטרנספורמציות של תרגום, מרכז הצורה של החץ מוזז אל נקודת האפס וממנה. ערכי הפרמטרים מוצגים כחישובים לשם הבהרה.
פרוטוקול הבקשה לשינוי הגודל של רכיב:
POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
"requests": [
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": -2000000 - 0.5 * 0.3 * 3000000,
"translateY": -550000 - 0.5 * 0.12 * 3000000,
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1.5,
"scaleY": 0.8,
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": 2000000 + 0.5 * 0.3 * 3000000,
"translateY": 550000 + 0.5 * 0.12 * 3000000,
"unit": "EMU"
}
}
}
]
}סיבוב של רכיב סביב המרכז שלו
בדוגמת הקוד הבאה של presentations.batchUpdate אפשר לראות איך משתמשים בשיטה UpdatePageElementTransformRequest כדי לסובב את רכיב הדף example arrow shape ב-35 מעלות נגד כיוון השעון, תוך שמירה על המיקום של מרכז החץ ועל הגודל שלו.
כדי לעשות את זה, משתמשים בטרנספורמציה של סיבוב בסיסי במסגרת ההפניה של הרכיב. לשם הבהרה, ההזזה והסיבוב של מסגרת ההתייחסות מוצגים באמצעות שלוש קריאות נפרדות לשיטה UpdatePageElementTransformRequest, אבל יעיל יותר לחשב מראש את המכפלה של מטריצות הטרנספורמציה האלה ואז להחיל את המכפלה הזו כבקשה אחת.
בטרנספורמציות של תרגום, מרכז הצורה של החץ מוזז אל נקודת האפס וממנה. ערכי הפרמטרים מוצגים כחישובים לשם הבהרה.
הפרוטוקול הבא משמש לסיבוב של רכיב סביב המרכז שלו:
POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
"requests": [
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": -2000000 - 0.5 * 0.3 * 3000000,
"translateY": -550000 - 0.5 * 0.12 * 3000000,
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": cos(35 * (pi/180)),
"scaleY": cos(35 * (pi/180)),
"shearX": sin(35 * (pi/180)),
"shearY": -sin(35 * (pi/180)),
"unit": "EMU"
}
}
},
{
"updatePageElementTransform": {
"objectId": PAGE_ELEMENT_ID,
"applyMode": "RELATIVE",
"transform": {
"scaleX": 1,
"scaleY": 1,
"translateX": 2000000 + 0.5 * 0.3 * 3000000,
"translateY": 550000 + 0.5 * 0.12 * 3000000,
"unit": "EMU"
}
}
}
]
}