שינוי פעולות

‫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 מוצגות שתי דרכים שונות לתרגום של רכיב הדף example arrow shape באמצעות השיטה UpdatePageElementTransformRequest.

הבקשה הראשונה באצווה מעבירה את החץ לקואורדינטות (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% מהגובה הנוכחי, תוך שמירה על המיקום של מרכז החץ ועל הכיוון שלו.

הפעולה הזו מתבצעת באמצעות טרנספורמציה של שינוי גודל בסיסי במסגרת ההפניה של הרכיב. לצורך הבהרה, ההזזה והשינוי של מסגרת ההתייחסות מוצגים באמצעות שלוש קריאות נפרדות ל-method‏ 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"
        }
      }
    }
  ]
}