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

כדי להשתמש ב-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 API הן לקריאה בלבד.

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

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

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

.

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

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

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

בקטעים הבאים מוסברות עוד רעיונות.

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

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

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

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

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

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

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

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

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

אפשר ליצור placeholder באמצעות כלי העריכה של 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 מוצג כ-"Red".
• ‫Placeholder2: המאפיין propertyA לא עבר רינדור. אם זה היה מאפיין המתאר, ל-Placeholder2 לא היה מתאר.
• ‫Placeholder3: המאפיין A לא עבר רינדור.

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