דפים, רכיבי דף ונכסים

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

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

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

מצגות, דפים ורכיבי דפים

רכיב המאגר החיצוני ביותר ב-Google Slides הוא מצגת. זו היחידה שאפשר לשמור ב-Google Drive, לשתף עם משתמשים אחרים וכו'.

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

כל דף מכיל מספר רכיבי דף, שביחד מרכיבים את תוכן הדף, כמו שמוצג בתרשים הבא:

חוץ משקפים, יש סוגים אחרים של דפים שמאפשרים להחיל עיצוב על הרבה שקפים שונים, כדי ליצור מראה עקבי. סוגי הדפים האחרים הם תבניות בסיס ופריסות, והמאפיינים שלהם קובעים את האופן שבו השקפים מוצגים, כפי שמוצג בתרשים הבא:

דפי מאסטר – לדף המאסטר יש שתי מטרות. ה-placeholders בשקף הראשי מכילים את ברירות המחדל של סגנונות הטקסט שבהם משתמשים במצגת. הרקע וכל הצורות האחרות בשקף הראשי מהווים את רקע ברירת המחדל לכל השקפים שמבוססים על השקף הראשי הזה. אם יש לכם לוגו של החברה שאתם רוצים שיופיע בכל שקף במצגת, שימו אותו בשקף הראשי.

פריסות – תבניות פריסה קובעות איך התוכן מסודר בכל סוג של שקף. לדוגמה, אם אתם רוצים שכל שקפי הכותרת ייראו בצורה מסוימת, אתם יכולים לערוך את תבנית הפריסה של הכותרת.

יש עוד שני סוגים של דפים – דפי הערות ותבניות בסיס להערות – שרלוונטיים בעיקר לעבודה עם הערות דובר.

סוגים ומבנה של ייצוגי API

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

התרשים הבא מתאר את הקשר בין מצגות, דפים ורכיבי דף כסוגים ב-Slides API:

בקטעים הבאים מוסבר איך הסוגים האלה מיוצגים ב-JSON.

מצגות

מצגת כוללת מספר מאפיינים, ומכילה את הדפים שבה:

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

iWork Pages

דף כולל קבוצה של מאפיינים, ומכיל את רכיבי הדף שנמצאים בו:

{
  "objectId": string,
  "pageType": enum(PageType),
  "pageElements": [ { object(PageElement) } ],
  "pageProperties": { object(PageProperties) },

  // Union field properties can be only one of the following:
  "slideProperties": { object(SlideProperties) },
  "layoutProperties": { object(LayoutProperties) },
  "notesProperties": { object(NotesProperties) },
  // End of list of possible types for union field properties.
}

מרכיבי דף

רכיבי דף הם הרכיבים החזותיים שמופיעים בדפים. מרכיב דף ב-API מכיל כמה מאפיינים, כולל שדה שמשתנה בהתאם לסוג של מרכיב הדף:

{
  "objectId": string,
  "size": { object(Size) },
  "transform": { object(AffineTransform) },
  "title": string,
  "description": string,

  // Union field element_kind can be only one of the following:
  "elementGroup": { object(Group) },
  "shape": { object(Shape) },
  "image": { object(Image) },
  "video": { object(Video) },
  "line": { object(Line) },
  "table": { object(Table) },
  "wordArt": { object(WordArt) },
  "sheetsChart": { object(SheetsChart) },
  // End of list of possible types for union field element_kind.
}

יש כמה סוגים של רכיבי דף, שמוגדרים על ידי שדה האיחוד element_kind בהגדרה שלמעלה. סוגי מרכיבי הדף האלה מתוארים בטבלה הבאה:

סוג הרכיב	תיאור
קבוצה	קבוצה של רכיבי דף שמתייחסים אליהם כיחידה אחת. אפשר להזיז, לשנות את הגודל ולסובב אותם ביחד.
צורה	אובייקט חזותי פשוט, כמו מלבנים, אליפסות ותיבות טקסט. צורות יכולות להכיל טקסט, ולכן הן מרכיבי הדף הנפוצים ביותר ליצירת שקפים.
תמונה	גרפיקה שיובאה ל-Slides.
וידאו	סרטון שיובא ל-Slides.
קו	קו, עקומה או מחבר חזותיים.
טבלה	רשת של תוכן.
WordArt	רכיב טקסט חזותי שמתנהג יותר כמו צורה.
SheetsChart	תרשים שיובא ל-Slides מ-Google Sheets.

מאפיינים של דפים ושל מרכיבי דפים

באמצעות Slides API אתם יכולים לקרוא ולעדכן את המראה של דפים ומרכיבי דפים במצגת. רכיבי דף שונים תומכים במאפיינים שונים שקובעים איך רכיב הדף מוצג.

לכל סוג של רכיב דף יש רכיב מאפיינים תואם והודעת עדכון מאפיינים, לדוגמה:

• יש רכיב דף מסוג צורה
• שדה המאפיין שלו הוא shapeProperties
• הבקשה לעדכון המאפיינים האלה היא UpdateShapePropertiesRequest

אותה קבוצה של רכיבים/מאפיינים/בקשות עדכון קיימת לכל סוג של רכיב דף: Image/imageProperties/UpdateImageProperties וכן הלאה.

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

סוגי נכסים

יש כמה מאפיינים שמשותפים לכמה סוגים של אובייקטים ב-Slides API:

נכס	תיאור
צבע	הצבעים ב-Slides API יכולים להיות ערך RGB או הפניה לצבע של עיצוב. צבעי העיצוב נקראים לפי שם (לדוגמה, "DARK1") ואפשר למפות אותם לערכי RGB באמצעות ערכת הצבעים של הדף. ערכת הצבעים הזו מתעדכנת בדרך כלל כשמשנים את העיצוב של המצגת בכלי העריכה של Slides.
מילוי	המילוי מייצג את העיבוד של השטח הריק בתוך אובייקט. סוג המילוי הנפוץ ביותר ב-Slides הוא מילוי אחיד, שבו החלק הפנימי של האובייקט ממולא בצבע אחיד אחד. אפשר להשתמש במילויים גם לרקעים של דפים.
מתאר	המתאר מייצג את קבוצת הקווים שמקיפים את רכיב הדף. הצבע של הקווים נשלט באמצעות מילוי. אפשר גם לשנות את הרוחב ואת סגנון המקפים של קווי המתאר.
צל	הצל מייצג אפקט חזותי שנועד לחקות צל פיזי שמוטל על ידי האובייקט. נכון לעכשיו, הצללות ב-Slides API הן לקריאה בלבד.

מתבצע עדכון של המאפיינים

כדי לעדכן מאפיין, משתמשים בבקשת Update...Properties המתאימה בקריאה ל-batchUpdate – לדוגמה, UpdateShapeProperties לצורות. הבקשות האלה מקבלות הודעה עם כל המאפיינים, ואפשר להשתמש במסכות שדות כדי לקבוע אילו שדות בהודעת המאפיינים צריך לעדכן.

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

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

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

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

הרעיונות האלה מוסברים בהרחבה בפסקאות הבאות.

ירושה של מאפייני דף

המבנה של השקפים, הפריסות והתבניות מגדיר היררכיית ירושה בתוך המצגת: השקפים יורשים מהפריסות, והפריסות יורשות מהתבניות. פריסת האם והתבנית של השקף מצוינות בשדה slideProperties של השקף.

דף יכול לרשת מאפיינים, כמו רקע וערכת צבעים, מדף הורה. כדי לרשת מאפיין, פשוט לא מגדירים ערך למאפיין הזה בהודעת PageProperties של דף הצאצא. אם לא "עוקפים" את הערך שהוגדר על ידי ההורה, הדף מקבל את הערך שעבר בירושה.

בתרשים הבא מוצגת שקופית שיורשת מאפיינים מפריסה, שיורשת מתבנית בסיס:

המאפיינים שמשמשים לעיבוד שקף הם שילוב של המאפיינים שהוא מגדיר והמאפיינים שהוא יורש. בדוגמה הזו, הערכים שהתקבלו בהתאמת הנתונים ומשמשים לעיבוד של שקף 1 הם:

• הערך של PropertyA הוא "Red".
• הערך של PropertyB הוא "Orange".

דף שאין לו הורה יורש ערכי ברירת מחדל מ-Google Slides לכל המאפיינים שהוא לא מגדיר.

העברת מאפייני צורה בירושה

צורות יכולות לרשת מאפיינים, כמו מילוי, קווי מתאר או צל, מצורות אחרות. צורה היא פלייסהולדר אם השדה Shape.placeholder שלה מוגדר. השדה Shape.placeholder.parentObjectId של הפלייסהולדר המשני מזהה את הפלייסהולדר הראשי שלו. כשיוצרים שקף חדש על סמך פריסה, כל הפלייסהולדרים בפריסה הזו מופיעים כצורות צאצא בשקף החדש. באופן דומה, פלייסהולדרים בדפי פריסת-העל יכולים לשמש כהורים של הפלייסהולדרים בפריסות.

אפשר ליצור פלייסהולדרים באמצעות הכלי לעריכת מצגות ב-Slides, אבל לא באמצעות Slides API.

אחרי שמגדירים את היררכיית ההורשה הזו, דף הצאצא יורש מאפיין אם לא מגדירים את הערך הזה בהודעת ShapeProperties שלו. אם לא משנים את הערך שמוגדר על ידי ההורה, הצורה הצאצאית מקבלת את הערך שעבר בירושה.

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

המאפיינים שמשמשים לעיבוד של צורת פלייסהולדר הם שילוב של המאפיינים שהיא מגדירה והמאפיינים שהיא יורשת. בדוגמה הזו, הערכים המחושבים של הצורות האלה הם:

• ‫Placeholder1: ‏propertyA מוצג כ-"Yellow", ‏propertyB מוצג כ-"Green".
• ‫Placeholder2: ‏propertyA מוצג כ-"Yellow", ‏propertyB מוצג כ-"Purple".
• ‫Placeholder3: ‏propertyA מוצג כ-"Yellow", ‏propertyB מוצג כ-"Purple".

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

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

"הסתרת" נכסים באמצעות PropertyState

הערך של PropertyState קובע אם המאפיין של הצורה משמש בפועל לעיבוד, או אם הערך משמש רק להעברה בירושה לצורות הצאצא. נכס עם מצב הנכס NOT_RENDERED לא ישמש לעיבוד הצורה בדף שלו, אבל צאצאים עם מצב נכס תואם של RENDERED עדיין יכולים לרשת את הנכס הזה.

עדכון של נכס מגדיר באופן משתמע את מצב הנכס ל-`RENDERED`, אלא אם מגדירים את המצב לערך אחר באותה בקשה.

הדיאגרמה הבאה מציגה את ההורשה של מאפיינים בין שלושה פלייסהולדרים שמשנים את השדה PropertyState:

השדה PropertyState יכול להשפיע על העיבוד של מאפייני הצורה. בדוגמה הזו, הערכים שנקבעו לצורות האלה הם:

• ‫Placeholder1: ‏propertyA מוצג בתור "אדום".
• ‫Placeholder2: המאפיין propertyA לא עובר רינדור. אם זה היה המאפיין outline, ל-Placeholder2 לא היה קו מתאר.
• Placeholder3: propertyA is not rendered.

יש עוד ערך אפשרי אחד של המאפיין PropertyState: הערך INHERIT מציין שמצב הנכס עצמו עובר בירושה, וצריך להשתמש בערך של ההורה. לצורות ללא הורים לא יכול להיות מצב מאפיין של INHERIT.