כתיבה בסיסית

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

בדוגמאות האלה נעשה שימוש במשתנים הבאים:

• PRESENTATION_ID – כאן מציינים את מזהה המצגת. אפשר למצוא את הערך של המזהה הזה מכתובת ה-URL של המצגת.
• PAGE_ID – מציין איפה מספקים את מזהה האובייקט של הדף. אפשר לאחזר את הערך הזה מכתובת ה-URL או באמצעות בקשת קריאה ל-API.
• PAGE_ELEMENT_ID – מציין את המיקום שבו מציינים את מזהה האובייקט של רכיב הדף. אפשר לציין את המזהה הזה לאלמנטים שאתם יוצרים (עם מגבלות מסוימות) או לאפשר ל-Slides API ליצור אותו באופן אוטומטי. אפשר לאחזר את מזהי הרכיבים באמצעות בקשת קריאה ל-API.

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

הוספת תיבת טקסט לשקף

בדוגמת הקוד הבאה של presentations.batchUpdate מוסבר איך להשתמש בשיטה CreateShapeRequest כדי להוסיף תיבת טקסט חדשה (שמכילה את המחרוזת 'תיבת הטקסט שנוספה') לשקופית שצוינה על ידי PAGE_ID. בגוף הבקשה מצוינות שתי בקשות – אחת ליצירת הצורה של תיבת הטקסט (בגודל ובמיקום נתונים) והשנייה כדי להוסיף אליה טקסט.

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

זהו פרוטוקול הבקשה להוספת תיבת טקסט לשקף:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createShape": {
        "objectId": PAGE_ELEMENT_ID,
        "shapeType": "TEXT_BOX",
        "elementProperties": {
          "pageObjectId":  PAGE_ID,
          "size": {
            "width": {
              "magnitude": 150,
              "unit": "PT"
            },
            "height": {
              "magnitude": 50,
              "unit": "PT"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 200,
            "translateY": 100,
            "unit": "PT"
          }
        }
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My Added Text Box",
        "insertionIndex": 0
      }
    }
  ]
}

הוספת תמונה לשקף

בדוגמת הקוד הבאה של presentations.batchUpdate מוסבר איך להשתמש ב-method‏ CreateImageRequest כדי להוסיף תמונה לשקף שמצוין על ידי PAGE_ID. ה-API מאחזר את התמונה באמצעות IMAGE_URL. הבקשה הזו גם מגדילה את התמונה וממקמת אותה בשקף.

זהו פרוטוקול הבקשה להוספת תמונה לשקף:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createImage": {
        "url": IMAGE_URL,
        "elementProperties": {
          "pageObjectId":  PAGE_ID,
          "size": {
            "width": {
              "magnitude": 30,
              "unit": "PT"
            },
            "height": {
              "magnitude": 30,
              "unit": "PT"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 200,
            "translateY": 100,
            "unit": "PT"
          }
        }
      }
    }
  ]
}

מחיקת רכיב של דף או של דף

בדוגמת הקוד הבאה של presentations.batchUpdate מוסבר איך להשתמש ב-method‏ DeleteObjectRequest כדי למחוק את אלמנט הדף שצוין על ידי PAGE_ELEMENT_ID ואת השקופית שצוינה על ידי PAGE_ID באמצעות שתי בקשות נפרדות.

זהו פרוטוקול הבקשה למחיקה של דף או אלמנט בדף:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "deleteObject": {
        "objectId": PAGE_ELEMENT_ID
      },
      "deleteObject": {
        "objectId":  PAGE_ID
      }
    }
  ]
}

עריכת טקסט בצורה מסוימת

דוגמת הקוד הבאה של presentations.batchUpdate מראה איך להשתמש בשיטה DeleteTextRequest כדי להחליף חלק מהטקסט שנמצא בצורה שצוינה על ידי PAGE_ELEMENT_ID. כדי לעשות זאת, קודם מוחקים טקסט באמצעות startIndex שמתחיל בספרה אפס, ואז מוסיפים טקסט חדש במיקום הזה. בדוגמה הזו, מחרוזת הטקסט המקורית 'My Form Text: ...? ' מוחלפת ב-My Form Text: Trapezoid.

הבקשה הזו משפיעה רק על טקסט בצורה מסוימת. כדי להחליף טקסט בכל מקום במצגת, משתמשים ב-method‏ ReplaceAllTextRequest.

זהו פרוטוקול הבקשה לעריכת טקסט בצורה מסוימת:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "deleteText": {
        "objectId": PAGE_ELEMENT_ID,
        "textRange": {
          "type": "FROM_START_INDEX",
          "startIndex": 15
        }
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "Trapezoid",
        "insertionIndex": 15
      }
    }
  ]
}

החלפת תג של צורה בתמונה

תגים הם תיבות טקסט או צורות עם שם מחרוזת ייחודי, כמו "account-holder-name".

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

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

השיטה CreateImageRequest מחליפה רק צורה שצוינה. כדי להחליף את הצורות של התגים בכל מקום במצגת, משתמשים ב-method‏ ReplaceAllShapesWithImageRequest.

לתג הצורה יש את המאפיינים הבאים של PageElement (אפשר למצוא אותם באמצעות בקשה מסוג presentations.pages.get):

{
  "objectId": PAGE_ELEMENT_ID,
  "size": {
    "width": {
      "magnitude": 3000000,
      "unit": "EMU"
    },
    "height": {
      "magnitude": 3000000,
      "unit": "EMU"
    }
  },
  "transform": {
    "scaleX": 1.13,
    "scaleY": 0.62,
    "translateX": 4800000,
    "translateY":  450000,
    "unit": "EMU"
  },
  "shape": {
    "shapeType": "RECTANGLE"
  }
}

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

זהו פרוטוקול הבקשה להחליף תג צורה בתמונה:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createImage": {
        "url": IMAGE_URL,
        "elementProperties": {
          "pageObjectId":  PAGE_ID,
          "size": {
            "width": {
              "magnitude": 3000000 * 1.13,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000 * 0.62,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 4800000,
            "translateY": 450000,
            "unit": "PT"
          }
        }
      }
    },
    {
      "deleteObject": {
        "objectId": PAGE_ELEMENT_ID
      }
    }
  ]
}