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

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

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

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

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

הרכיבים ברמה העליונה של documents של המשאב כולל את ה-Tabs שלו, 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 ו-0 שמבוססים על אפס. endIndex נכסים. האותות האלה מציינים את ההיסט בין ההתחלה של רכיב מסוים בפועל, ביחס לתחילת הקטע הסוגר שלו. אפשר לקבל מידע נוסף בנושא הזמנה של קריאות אצווה ל-Google 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 הבסיסי. לעומת זאת, תכונות עיצוב שלא הגדרתם ימשיכו לקבל בירושה סגנון הפסקה.

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

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