המבנה של מסמך ב-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: הוא מייצג את תוכן הטקסט של כרטיסייה.

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

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

תוכן הגוף

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

יסוד מבני

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

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

מבנה הפסקה

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

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

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

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

רצפי טקסט

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

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

AutoText

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

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

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

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

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

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

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

גישה לרכיבים

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

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

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

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

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

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

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

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

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

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