כתיבה בסיסית

באמצעות 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 מוסבר איך להשתמש ב-method‏ DeleteTextRequest כדי להחליף חלק מהטקסט שנמצא בתוך הצורה שצוינה על ידי PAGE_ELEMENT_ID. כדי לעשות זאת, קודם מוחקים טקסט באמצעות startIndex שמתחיל בספרה אפס, ואז מוסיפים טקסט חדש במיקום הזה. בדוגמה הזו, מחרוזת הטקסט המקורית 'My Shape Text: ????' מוחלפת ב-'My Shape 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
      }
    }
  ]
}