המבנה של מסמך ב-Google Docs

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

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

רכיבים ברמה העליונה

האלמנט הכי חיצוני של הקונטיינר ב-Google Docs הוא מסמך. זהו היחידה שאפשר לשמור ב-Google Drive, לשתף עם משתמשים אחרים ולעדכן עם טקסט ותמונות.

הרכיבים ברמה העליונה של משאב documents כוללים את Tab,‏ SuggestionsViewMode ומאפיינים אחרים:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

כרטיסיות

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

  • ‫TabProperties: מכיל את המאפיינים של הכרטיסייה, כמו מזהה, שם ואינדקס.
  • ‫childTabs: חשיפת כרטיסיות צאצא של כרטיסייה (כרטיסיות שמוטמעות ישירות מתחתיה).
  • ‫DocumentTab: מייצג את תוכן הטקסט של כרטיסייה.
מבנה הכרטיסיות במסמך.
איור 1. מבנה הכרטיסיות במסמך.

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

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

תוכן גוף ההודעה

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

המבנה של תוכן גוף ההודעה.
איור 2. המבנה של תוכן גוף ההודעה.

אלמנט מבני

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

אלמנטים מבניים.
איור 3. אלמנטים מבניים.

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

מבנה הפסקה

‫Paragraph הוא StructuralElement שמייצג פסקה. יש לו טווח של תוכן שמסתיים בתו מעבר שורה. הוא מורכב מהאובייקטים הבאים:

  • ‫ParagraphElement: מתאר תוכן בתוך פסקה.
  • ‫ParagraphStyle: רכיב אופציונלי שמגדיר באופן מפורש מאפייני סגנון לפסקה.
  • ‫Bullet: אם הפסקה היא חלק מרשימה, זהו רכיב אופציונלי שמספק את הגדרת התבליט.

התכונה ParagraphElement פועלת כמו StructuralElement. קבוצה של סוגי רכיבי תוכן (כמו ColumnBreak ו-Equation) מבצעת התאמה אישית של ParagraphElement משלה, כמו שמוצג בתרשים הבא:

המבנה של אלמנטים של פסקאות.
איור 4. המבנה של אלמנטים של פסקאות.

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

רכיבי טקסט

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

מסמך קצר עם פסקאות ורשימה עם תבליטים.
איור 5. מסמך קטן.

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

המבנה של רצף טקסט.
איור 6. המבנה של רצף טקסט.

AutoText

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

אינדקס התחלה ואינדקס סיום

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

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

האינדקסים נמדדים ביחידות קוד UTF-16. כלומר, זוגות ממלאי מקום צורכים שני אינדקסים. לדוגמה, האמוג'י 'פנים מחייכות', 😄, מיוצג כ-\uD83D\uDE00 וצורכת שני אינדקסים.

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

לסוגי ה'התאמה אישית' של רכיבים מבניים – SectionBreak, TableOfContents, Table ו-Paragraph – אין את האינדקסים האלה כי הרכיב StructuralElement שמקיף אותם כולל את השדות האלה. הדבר נכון גם לגבי סוגי ההתאמה האישית שכלולים ב-ParagraphElement, כמו TextRun,‏ AutoText ו-PageBreak.

גישה לרכיבים

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

כדי לקרוא רכיבים במסמך, משתמשים בשיטה documents.get כדי לקבל קובץ JSON של המסמך המלא. לאחר מכן אפשר לנתח את ה-JSON שמתקבל כדי למצוא את הערכים של רכיבים ספציפיים. מידע נוסף זמין במאמר בנושא הצגת התוכן של מסמך הפלט כ-JSON.

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

המבנה של קטלוג מסמכים.
איור 7. המבנה של קטלוג מסמכים.

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

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

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

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

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