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

כדי להשתמש ב-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 API אפשר לקרוא ולעדכן את המראה של דפים ורכיבי דפים במצגת. מרכיבי דף שונים תומכים במאפיינים שונים שקובעים איך מרכיב הדף מוצג.

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

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

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

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

סוגי נכסים

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

עדכון מאפיינים

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

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

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

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

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

העברה אוטומטית של מאפייני דף

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

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

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

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

• המאפיין PropertyA הוא 'Red'.
• הערך של PropertyB הוא Orange.

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

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

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

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

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

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

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

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

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

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

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

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

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