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

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

• מודל רעיוני של רכיבי המצגת
• איך ה-API מייצג את הרכיבים האלה
• תכונות עיצוב של הרכיבים

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

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

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

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

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

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

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

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

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

מבנה וסוגים של ייצוג 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,
}

דפים

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

{
  "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	תרשים שיובא מ-Google Sheets ל-Slides.

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

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

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

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

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

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

סוגי נכסים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• PropertyA הוא "Red".
• PropertyB הוא "Orange".

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

ירושה של תכונות צורה

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

אפשר ליצור placeholders באמצעות העורך ב-Slides, אבל לא באמצעות ה-API של Slides.

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

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

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

• Placeholder1: propertyA מופיע כ-"Yellow", ו-propertyB הוא "Green".
• Placeholder2: propertyA מוצג כ-"Yellow", ו-propertyB הוא "Purple".
• Placeholder3: propertyA מופיע כ-"Yellow", ו-propertyB הוא "Purple".

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

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

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

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

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

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

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

• Placeholder1: propertyA עובר עיבוד כ "אדום".
• Placeholder2: propertyA לא מעובד. אם זה היה המאפיין outline, ל-Placeholder2 לא יהיה קו מתאר.
• Placeholder3: propertyA אינו מעובד.

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