המבנה של מסמך ב-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. כלומר, זוגות ממלאי מקום צורכים שני אינדקסים. לדוגמה, האמוג'י 'פנים מחייכות', 😄, מיוצג באמצעות \uD83D\uDE00 וצורכת שני אינדקסים.

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

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

גישה לאלמנטים

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

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

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

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

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

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

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

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

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

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