כדי להשתמש ב-Google Docs API ביעילות, עליך להבין את של מסמך Google Docs והרכיבים שמרכיבים את על מסמכים, ואת הקשרים ביניהם. הדף הזה מספק סקירה כללית מפורטת של הנושאים האלה:
- מודל רעיוני של רכיבי המסמך
- איך Docs API מייצג את הרכיבים האלה
- מאפייני העיצוב של הרכיבים
רכיבים ברמה העליונה
רכיב הקונטיינר החיצוני ביותר ב-Google Docs הוא מסמך. כאן יחידה שאפשר לשמור ב-Google Drive, לשתף עם משתמשים אחרים ולעדכן באמצעות טקסט ותמונות.
הרכיבים ברמה העליונה של documents
כוללים את ה-Tab
s שלו,
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
שמייצג מחרוזת טקסט רציפה עם סגנון טקסט זהה. א'
פיסקה יכולה להכיל כמה הפעלות טקסט, אבל טקסט אף פעם לא יכול לפעול בין פסקאות
גבולות. התוכן מחולק אחרי תו בשורה חדשה כדי ליצור טקסט נפרד
פועלות. לדוגמה, נבחן מסמך קטנטן כמו:
![מסמך קטן עם פסקאות ורשימה עם תבליטים.](https://developers.google.com/static/docs/api/images/simpledoc.png?hl=he)
בתרשים הבא אפשר לראות איך ניתן להציג את רצף הפסקאות
במסמך הקודם, לכל אחד מהם יש 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
הבסיסי.
לעומת זאת, תכונות עיצוב שלא הגדרתם ימשיכו לקבל בירושה
סגנון הפסקה.