פעולות על רכיבים

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

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

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

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

• עריכה וסגנון של טקסט
• הוספה של צורות וטקסט
• הוספת תרשים

הוספה של רשימה עם תבליטים לתיבת טקסט

דוגמת הקוד הבאה של presentations.batchUpdate מראה איך להשתמש ב-method InsertTextRequest כדי להוסיף טקסט לתיבת טקסט ריקה שצוינה ב-PAGE_ELEMENT_ID. בדוגמה הזאת נשתמש ב-method CreateParagraphBulletsRequest כדי להמיר את כל הטקסט בתיבת הטקסט לרשימה עם תבליטים. הפריטים ברשימה מופרדים באמצעות \n תווים, והכניסה נשלטת באמצעות תווי \t.

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

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

{
  "requests": [
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My List\n\tItem 1\n\t\tItem 2\n\t\t\tItem 3",
        "insertionIndex": 0
      },
      "createParagraphBullets": {
        "objectId": PAGE_ELEMENT_ID,
        "bulletPreset": "BULLET_ARROW_DIAMOND_DISC",
        "textRange": {
          "type": "ALL"
        }
      }
    }
  ]
}

הבקשה הזו יכולה ליצור רשימה עם תבליטים שנראית כך:

הוספת צורה לשקף

דוגמת הקוד הבאה של presentations.batchUpdate מראה איך להשתמש ב-method CreateShapeRequest כדי להוסיף צורת גל לשקף שצוין ב-PAGE_ID. הבקשה הזו מציינת את סוג הצורה, ואז משנה את גודל הצורה וממקמת אותה בשקף. לאחר מכן היא משתמשת ב-method InsertTextRequest כדי להוסיף טקסט לצורה. הבקשה מגדירה את מזהה השורה כ-PAGE_ELEMENT_ID.

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

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

{
  "requests": [
    {
      "createShape": {
        "objectId": PAGE_ELEMENT_ID,
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 0.6807,
            "scaleY": 0.4585,
            "translateX": 6583050,
            "translateY": 1673950,
            "unit": "EMU"
          }
        },
        "shapeType": "WAVE"
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My Wave Shape",
        "insertionIndex": 0
      }
    }
  ]
}

הוספת סרטון לשקף

דוגמת הקוד הבאה של presentations.batchUpdate מראה איך להשתמש בשיטה CreateVideoRequest כדי להטמיע סרטון בשקף שצוין ב-PAGE_ID. הבקשה הזו משנה את גודל הסרטון וממקמת אותו בשקף, ומגדירה את מזהה הסרטון ל-PAGE_ELEMENT_ID. המזהה הייחודי של סרטון המקור מוגדר ל-VIDEO_ID. לדוגמה, המזהה של סרטון YouTube בכתובת https://www.youtube.com/watch?v=7U3axjORYZ0 הוא 7U3axjORYZ0.

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

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

{
  "requests": [
    {
      "createVideo": {
        "objectId": PAGE_ELEMENT_ID,
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 12000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 9000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 381,
            "scaleY": 381,
            "translateX": 152400,
            "translateY": 152400,
            "unit": "EMU"
          }
        },
        "source": "YOUTUBE",
        "id": VIDEO_ID
      }
    }
  ]
}

העתקה ועריכה של רכיב

דוגמת הקוד הבאה presentations.batchUpdate מראה איך להשתמש ב-method DuplicateObjectRequest כדי לקבל צורה קיימת (מצוינת באמצעות PAGE_ELEMENT_ID) וליצור עותק (שצוין על ידי COPY_ELEMENT_ID).

הבקשות הבאות יבצעו את השינויים הבאים באובייקט הכפול:

• הגדרת צבע הרקע לצבע העיצוב LIGHT2.
• העברת העותק למטה (מהמיקום של הצורה המקורית).
• הגדרת גופן הטקסט ל-18 נק' בגאורגיה.
• עורך את הטקסט כך שיופיע 'עותק הצורה שלי'.

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

למידע נוסף על העתקת שקף, ראו העתקת שקף לדוגמה.

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

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

{
  "requests": [
    {
      "duplicateObject": {
        "objectId": PAGE_ELEMENT_ID,
        "objectIds": {
          PAGE_ELEMENT_ID: COPY_ELEMENT_ID
        }
      }
    },
    {
      "updateShapeProperties": {
        "objectId": COPY_ELEMENT_ID,
        "fields": "shapeBackgroundFill.solidFill.color",
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "LIGHT2"
              }
            }
          }
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": COPY_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
          "scaleX": 1,
          "scaleY": 1,
          "translateX": 0,
          "translateY": 1250000,
          "unit": "EMU"
        }
      }
    },
    {
      "updateTextStyle": {
        "objectId": COPY_ELEMENT_ID,
        "fields": "fontFamily,fontSize",
        "textRange": {
          "type": "ALL"
        },
        "style": {
          "fontFamily": "Georgia",
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        }
      }
    },
    {
      "deleteText": {
        "objectId": COPY_ELEMENT_ID,
        "textRange": {
          "type": "ALL"
        }
      }
    },
    {
      "insertText": {
        "objectId": COPY_ELEMENT_ID,
        "text": "My Shape Copy",
        "insertionIndex": 0
      }
    }
  ]
}

כך יכולים להיראות צורה והעותק שלה אחרי העדכונים האלה:

עריכת מתאר של תמונה או סרטון

דוגמת הקוד הבאה של presentations.batchUpdate מראה איך להשתמש ב-method UpdateImagePropertiesRequest כדי לעדכן את מראה המתאר של תמונה שמצוינת על ידי IMAGE_ELEMENT_ID. היא גם משתמשת ב-method UpdateVideoPropertiesRequest כדי לעדכן את קווי המתאר של סרטון מוטמע שצוין על ידי VIDEO_ELEMENT_ID.

הבקשות מבצעות את השינויים הבאים באובייקט:

• הגדרת צבע המתאר של התמונה לצבע העיצוב ACCENT5 עם שקיפות חלקית.
• הגדרת צבע קווי המתאר של הסרטון לצבע העיצוב ACCENT1 ללא שקיפות.
• מגדיר את משקלי המתאר של 3 נק' לשניהם.
• מגדיר את סגנון מתאר התמונה לSOLID.
• הגדרת הסגנון של מתאר הסרטון כDASH_DOT.

גם ה-method UpdateImagePropertiesRequest וגם ה-method UpdateVideoPropertiesRequest יכולות לשנות רק את המראה של קווי המתאר של התמונה ושל הסרטון. כל שאר המאפיינים מוגדרים לקריאה בלבד. הבקשות כאן משתמשות במסכות של שדות כדי לציין שצריך לשנות רק את המתאר כדי להגן על הקוד מפני שינויים עתידיים ב-API. השימוש במסכות שדה משפר גם את הביצועים.

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

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

{
  "requests": [
    {
      "updateImageProperties": {
        "objectId": IMAGE_ELEMENT_ID,
        "fields": "outline",
        "imageProperties": {
          "outline": {
            "dashStyle": "SOLID",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.8,
                "color": {
                  "themeColor": "ACCENT5"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    },
    {
      "updateVideoProperties": {
        "objectId": VIDEO_ELEMENT_ID,
        "fields": "outline",
        "videoProperties": {
          "outline": {
            "dashStyle": "DASH_DOT",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.8,
                "color": {
                  "themeColor": "ACCENT1"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    }
  ]
}

כך יכולים להיראות תמונה וסרטון מוטמע אחרי העדכונים האלה:

עריכת קווי מתאר של צורה

דוגמת הקוד presentations.batchUpdate הבאה מדגימה איך להשתמש ב-method UpdateShapePropertiesRequest כדי לקבל צורה קיימת (מצוינת באמצעות PAGE_ELEMENT_ID) ומעדכנת את המראה של המתאר שלה.

הבקשות מבצעות את השינויים הבאים באובייקט:

• הגדרת צבע המתאר לצבע העיצוב ACCENT5 עם שקיפות חלקית.
• הגדרת משקל המתאר ל-3 נק'
• מגדיר את סגנון המתאר כLONG_DASH.

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

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

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

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": PAGE_ELEMENT_ID,
        "fields": "outline",
        "shapeProperties": {
          "outline": {
            "dashStyle": "LONG_DASH",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.6,
                "color": {
                  "themeColor": "ACCENT5"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    }
  ]
}

כך עשויה להיראות צורה אחרי העדכונים האלה:

עיצוב טקסט בצורה או בתיבת טקסט

דוגמת הקוד presentations.batchUpdate הבאה ממחישה איך להשתמש ב-method UpdateTextStyleRequest כדי לקבל צורה קיימת (מצוינת באמצעות PAGE_ELEMENT_ID) ומעדכנת את המראה של הטקסט.

הבקשות מבצעות את השינויים הבאים באובייקט:

• הגדרת צבע הטקסט לצבע העיצוב ACCENT5.
• הגדרת הגופן למודגש ונטוי 18 נק' של Corsiva.
• מסמן את הטקסט בקו תחתון.

הבקשות כאן משתמשות במסכות של שדות כדי לשמר את מאפייני סגנון הטקסט שלא משתנים (כמו צבע הרקע, קישורים או היסט הבסיס). השימוש במסכות שדה משפר גם את הביצועים.

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

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

{
  "requests": [
    {
      "updateTextStyle": {
        "objectId": PAGE_ELEMENT_ID,
        "fields": "foregroundColor,bold,italic,fontFamily,fontSize,underline",
        "style": {
          "foregroundColor": {
            "opaqueColor": {
              "themeColor": "ACCENT5"
            }
          },
          "bold": true,
          "italic": true,
          "underline": true,
          "fontFamily": "Corsiva",
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        },
        "textRange": {
          "type": "ALL"
        }
      }
    }
  ]
}

כך יכול להיראות הטקסט של הצורה אחרי העדכונים האלה:

ייבוא תרשים מ-Google Sheets

דוגמת הקוד הבאה של presentations.batchUpdate ממחישה איך להשתמש בשיטה CreateSheetsChartRequest כדי לייבא תרשים מגיליון ולמקם אותו בשקף שמצוין ב-PAGE_ID.

בבקשה נדרשים מזהה הגיליון האלקטרוני (שצוין על ידי SPREADSHEET_ID) ומזהה התרשים של הגיליון האלקטרוני (שצוין על ידי SPREADSHEET_CHART_ID). מזהה התרשים במצגת של Slides מצוין על ידי PRESENTATION_CHART_ID.

הבקשה גם מגדירה את LinkingMode של התרשים ב-Slides כ-LINKED, כך שאפשר לעדכן את התרשים המוטמע אם התרשים בגיליון האלקטרוני המקורי מעודכן.

זה פרוטוקול הבקשה לייבוא תרשים מ-Sheets:

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

{
  "requests": [
    {
      "createSheetsChart": {
        "objectId": PRESENTATION_CHART_ID,
        "spreadsheetId": SPREADSHEET_ID,
        "chartId": SPREADSHEET_CHART_ID,
        "linkingMode": "LINKED",
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 4000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 4000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 100000,
            "translateY": 100000,
            "unit": "EMU"
          }
      }
    }
  ]
}

רענון תרשים מ-Sheets

דוגמת הקוד הבאה של presentations.batchUpdate מראה איך להשתמש בשיטה RefreshSheetsChartRequest כדי לרענן תרשים מקושר במצגת, ולהחליף אותו בגרסה העדכנית ביותר של התרשים מהגיליון האלקטרוני המקורי ב-Sheets. בבקשה צריך לציין את מזהה התרשים במצגת של Slides (שצוין על ידי PRESENTATION_CHART_ID).

זה פרוטוקול הבקשה לרענון תרשים מ-Sheets:

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

{
  "requests": [
    {
      "refreshSheetsChart": {
        "objectId": PRESENTATION_CHART_ID
      }
    }
  ]
}