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 (באמצעות הזזה אבסולוטית
applyMode). הבקשה השנייה באצווה מעבירה את החץ משם, הפעם 40,000 EMU ימינה ו-35,000 EMU למעלה (באמצעות הזזה יחסית applyMode). מטריצות הטרנספורמציה1 שבהן נעשה שימוש בנויות כך שהן לא משנות את הגודל והכיוון של הרכיב.
אחרי שמבצעים את שתי הבקשות, הפינה הימנית העליונה של החץ נמצאת בקואורדינטה (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 כדי לסובב את צורת החץ לדוגמה של רכיב הדף ב-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"
}
}
}
]
}