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

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

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

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

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

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

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

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

דפי Master – דף ה-Master משמש לשני צרכים. ה-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 הוא 'אדום'.
• הערך של PropertyB הוא 'Orange'.

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

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

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

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

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

• placeholder1: propertyA מוצג כ'צהוב', propertyB כ'ירוק'.
• placeholder2: propertyA מוצג כ'צהוב', propertyB כ'סגול'.
• placeholder3: propertyA מוצג כ'צהוב', propertyB כ'סגול'.

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

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

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

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

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

• placeholder1: propertyA מוצג כ'אדום'.
• placeholder2: propertyA לא עבר רינדור. אם זה היה מאפיין המתאר, ל-Placeholder2 לא היה מתאר.
• placeholder3: propertyA לא עבר רינדור.

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