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

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

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

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

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

הרכיבים ברמה העליונה של משאב documents כוללים את המאפיינים Body, Header, Footer ועוד:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

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

התוכן בגוף

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

מבנה התוכן בגוף.
איור 1. מבנה התוכן בגוף.

יסוד מבני

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

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

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

מבנה הפִּסקה

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

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

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

המבנה של רכיבי הפסקה.
איור 3. המבנה של רכיבי הפסקה.

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

ריצות טקסט

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

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

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

המבנה של הרצת טקסט.
איור 5. המבנה של הרצת טקסט.

AutoText

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

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

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

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

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

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

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

גישה לרכיבים

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

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

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

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

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

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

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

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

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