כתיבה בסיסית

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

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

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

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

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

דוגמת הקוד presentations.batchUpdate הבאה ממחישה איך להשתמש בשיטה CreateShapeRequest כדי להוסיף תיבת טקסט חדשה (שכוללת את המחרוזת My added Text Box) לשקף שצוין ב-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 מראה איך להשתמש בשיטה 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.

הבקשה הזו משפיעה רק על טקסט בצורה שצוינה. כדי להחליף טקסט בכל מקום במצגת, משתמשים בשיטה 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, ממחישה איך להשתמש ב-method CreateImageRequest כדי להחליף מופע יחיד של תג צורה בתמונה, תוך שמירה על אותו המיקום והתאמה לעומס (scaling) כך שיתאים לגודל התג תוך שמירה על יחס הגובה-רוחב של התמונה.

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

ה-method 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
      }
    }
  ]
}