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

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

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

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

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

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

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

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

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

תוכן הגוף

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

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

רכיב מבני

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

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

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

לסוגים Header, Footer ו-Footnote יש רכיבי תוכן שגם מכילים רצף של רכיבים מבניים.

מבנה הפִּסקה

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

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

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

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

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

הפעלות טקסט

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

איור 4. מסמך קטן.

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

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

AutoText

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

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

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

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

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

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

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

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

רכיבי גישה

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

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

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

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

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

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

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

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

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

נושאים קשורים

• בקשות ותשובות
• כללים והתנהגות עריכה מבנית