בעזרת Google Docs API אפשר לגשת לתוכן מכל כרטיסייה במסמך.
מהן כרטיסיות?
ב-Google Docs יש שכבה ארגונית שנקראת כרטיסיות. Docs מאפשר למשתמשים ליצור כרטיסייה אחת או יותר בכרטיסייה אחת מסמך, בדומה לאופן שבו יש כרטיסיות כיום ב-Sheets. לכל כרטיסייה יש משלה כותרת ומזהה (המצורפים לכתובת האתר). כרטיסייה יכולה לכלול גם כרטיסיות צאצא, כרטיסיות שמוצבות מתחת לכרטיסייה אחרת.
תמיכה בממשק API לכרטיסיות צאצא זמינה כבר עכשיו, אבל בקרוב תהיה תמיכה בממשק המשתמש. יש לך אפשרות לנהל כרטיסיות צאצא בקוד שלך כבר עכשיו, כך שתושק התמיכה בממשק המשתמש לא תצטרכו לבצע עדכוני קוד נוספים.
שינויים מבניים באופן שבו תוכן המסמך מיוצג במשאב המסמך
בעבר, לא היה עיקרון של כרטיסיות,
Document
המשאב נמצא ישירות
את כל תוכן הטקסט באמצעות השדות הבאים:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
בעקבות ההיררכיה המבנה הנוספת של הכרטיסיות, השדות האלה כבר לא
לייצג את תוכן הטקסט מכל הכרטיסיות במסמך מבחינה סמנטית.
תוכן מבוסס-טקסט מיוצג עכשיו בשכבה שונה. מאפייני הכרטיסייה וגם
ניתן לגשת לתוכן ב-Google Docs באמצעות
document.tabs
, וזו רשימה של
Tab
אובייקטים, שכל אחד מהם
מכיל את כל שדות תוכן הטקסט שהוזכרו קודם לכן. החלקים מאוחרים יותר מספקים
סקירה כללית קצרה; ה
ייצוג JSON של כרטיסייה
מספק מידע מפורט יותר.
גישה למאפייני הכרטיסייה
גישה למאפייני הכרטיסיות באמצעות
tab.tabProperties
,
שכולל מידע כמו המזהה, הכותרת והמיקום של הכרטיסייה.
גישה לתוכן טקסט בתוך כרטיסייה
תוכן המסמך עצמו בכרטיסייה חשוף בתור
tab.documentTab
כל החישובים האלה
ניתן לגשת לשדות תוכן הטקסט שהוזכרו למעלה באמצעות tab.documentTab
.
לדוגמה, במקום להשתמש ב-document.body
, עליך להשתמש ב-
document.tabs[indexOfTab].documentTab.body
.
היררכיית כרטיסיות
כרטיסיות צאצא מיוצגות ב-API בצורה של
השדה tab.childTabs
מופעל
Tab
גישה לכל הכרטיסיות
מסמך מחייב מעבר ל"עץ" של כרטיסיות צאצא. לדוגמה, כדאי לקחת בחשבון
מסמך שמכיל היררכיית כרטיסיות באופן הבא:
כדי לאחזר את Body
מכרטיסייה 3.1.2, תהיה לך גישה
document.tabs[2].childTabs[0].childTabs[1].documentTab.body
. לצפייה בדוגמה
בלוקים של קוד שמופיע בקטע מאוחר יותר, שמספק קוד לדוגמה לצורך חזרה
בכל הכרטיסיות במסמך.
שינויים בשיטות
עם השקת הכרטיסיות, בכל אחת משיטות המסמכים יש מספר שינויים שבהם אולי תצטרכו לעדכן את הקוד.
documents.get
כברירת מחדל, לא כל תוכן הכרטיסייה מוחזר. המפתחים צריכים לעדכן את
כדי לגשת לכל הכרטיסיות.
השיטה documents.get
חושפת
פרמטר includeTabsContent
שמאפשר לקבוע אם תוכן מ-
כל הכרטיסיות מופיעות בתשובה.
- אם המדיניות
includeTabsContent
מוגדרת לערךtrue
, שיטתdocuments.get
תוחזר משאבDocument
עם השדהdocument.tabs
מאוכלס. כל שדות הטקסט ישירות באתרdocument
(למשל,document.body
) יישאר ריק. - אם לא תספקו את
includeTabsContent
, שדות הטקסט במשאבDocument
(למשלdocument.body
) יאוכלסו בתוכן מהכרטיסייה הראשונה בלבד. השדהdocument.tabs
יהיה ריק ותוכן מכרטיסיות אחרות לא יוחזר.
documents.create
השיטה documents.create
מחזירה משאב Document
שמייצג את המסמך הריק שנוצר. המוחזר
Document
המשאב יאכלס את
תוכן של מסמך ריק גם בשדות תוכן הטקסט של המסמך וגם
document.tabs
document.batchUpdate
כל Request
כולל
דרך לציין את הכרטיסיות שעליהן יש להחיל את העדכון. כברירת מחדל, אם הכרטיסייה לא
שצוין,
Request
יהיה עד
יחולו על הכרטיסייה הראשונה במסמך.
ReplaceAllTextRequest
,
DeleteNamedRangeRequest
,
וגם
ReplaceNamedRangeContentRequest
הן שלוש בקשות מיוחדות שבמקום זאת יחולו על כל הכרטיסיות כברירת מחדל.
עיינו ב
Request
שנ'
מסמכים ספציפיים.
שינויים בקישורים פנימיים
המשתמשים יכולים ליצור קישורים פנימיים לכרטיסיות, לסימניות ולכותרות במסמך.
עם השקת התכונה 'כרטיסיות', link.bookmarkId
ו-
link.headingId
שדות ב
אי אפשר יותר להשתמש במשאב Link
לייצג סימנייה או כותרת בכרטיסייה מסוימת במסמך.
המפתחים צריכים לעדכן את הקוד שלהם כדי להשתמש ב-link.bookmark
וב-
link.heading
בפעולות של קריאה וכתיבה. הם חושפים קישורים פנימיים באמצעות
BookmarkLink
ו-
HeadingLink
אובייקטים, כל אחד
שמכיל את המזהה של הסימנייה או הכותרת ואת המזהה של הכרטיסייה שבה היא נמצאת.
אינץ' בנוסף, link.tabId
חושף קישורים פנימיים לכרטיסיות.
תוכן הקישור של documents.get
התגובה עשויה להשתנות בהתאם לפרמטר includeTabsContent
:
- אם המדיניות
includeTabsContent
מוגדרת לערךtrue
, כל הקישורים הפנימיים ייחשפו.link.bookmark
ו-link.heading
. השדות מהדור הקודם לא יהיו יותר בשימוש. - אם לא צוין
includeTabsContent
, במסמכים שמכילים כרטיסייה יחידה, כל קישור פנימי לסימניות או לכותרות בתוך כרטיסייה יחידה זו ימשיכו להיחשף כ-link.bookmarkId
ו-link.headingId
. במסמכים שכולל מספר כרטיסיות, קישורים פנימיים ייחשפו בתורlink.bookmark
link.heading
.
ב-document.batchUpdate
,
אם קישור פנימי נוצר באמצעות אחד מהשדות מהדור הקודם, הסימנייה
תיחשב ככותרת ממזהה הכרטיסייה שצוין
Request
אם לא מוצגת כרטיסייה
מצוין, הוא ייחשב כמשויך לכרטיסייה הראשונה במסמך.
ייצוג JSON של קישור מספק מידע מפורט יותר.
דפוסי שימוש נפוצים בכרטיסיות
דוגמאות הקוד הבאות מתארות דרכים שונות לאינטראקציה עם כרטיסיות.
קריאת התוכן של הכרטיסיות מכל הכרטיסיות במסמך
קוד קיים שביצע את הפעולה הזו לפני שניתן יהיה להעביר את תכונת הכרטיסיות לתמיכה
כרטיסיות על ידי הגדרת הפרמטר includeTabsContent
כ-true
, לאחר המעבר
היררכיית עץ הכרטיסיות, וקריאה לשיטות קבלת
Tab
וגם
DocumentTab
במקום
Document
. החלקיות הבאות
דוגמת הקוד מבוססת על קטע הקוד
חילוץ טקסט ממסמך. רואים
כיצד להדפיס את כל תוכן הטקסט מכל כרטיסייה במסמך. הכרטיסייה הזו
ניתן להתאים את קוד המעבר לתרחישים רבים אחרים שלא חשובים
במבנה בפועל של הכרטיסיות.
Java
/** Prints all text contents from all tabs in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from each tab in the document. for (Tab tab: allTabs) { // Get the DocumentTab from the generic Tab. DocumentTab documentTab = tab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); } } /** * Returns a flat list of all tabs in the document in the order they would * appear in the UI (top-down ordering). Includes all child tabs. */ private List<Tab> getAllTabs(Document doc) { List<Tab> allTabs = new ArrayList<>(); // Iterate over all tabs and recursively add any child tabs to generate a // flat list of Tabs. for (Tab tab: doc.getTabs()) { addCurrentAndChildTabs(tab, allTabs); } return allTabs; } /** * Adds the provided tab to the list of all tabs, and recurses through and * adds all child tabs. */ private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) { allTabs.add(tab); for (Tab tab: tab.getChildTabs()) { addCurrentAndChildTabs(tab, allTabs); } } /** * Recurses through a list of Structural Elements to read a document's text * where text may be in nested elements. * * <p>For a code sample, see * <a href="https://developers.google.com/docs/api/samples/extract-text">Extract * the text from a document</a>. */ private static String readStructuralElements(List<StructuralElement> elements) { ... }
קריאת תוכן הכרטיסייה מהכרטיסייה הראשונה במסמך
הפעולה הזו דומה לקריאת כל הכרטיסיות.
Java
/** Prints all text contents from the first tab in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from the first tab in the document. Tab firstTab = allTabs.get(0); // Get the DocumentTab from the generic Tab. DocumentTab documentTab = firstTab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); }
שליחת בקשה לעדכון הכרטיסייה הראשונה
דוגמת הקוד החלקי הבאה מראה איך לטרגט כרטיסייה ספציפית
Request
הקוד הזה
מבוססת על
מדריך בנושא הוספה, מחיקה והעברה של טקסט.
Java
/** Inserts text into the first tab of the document. */ static void insertTextInFirstTab(Docs service, String documentId) throws IOException { // Get the first tab's ID. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); Tab firstTab = doc.getTabs().get(0); String tabId = firstTab.getTabProperties().getTabId(); List<Request>requests = new ArrayList<>(); requests.add(new Request().setInsertText( new InsertTextRequest().setText(text).setLocation(new Location() // Set the tab ID. .setTabId(tabId) .setIndex(25)))); BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests); BatchUpdateDocumentResponse response = docsService.documents().batchUpdate(DOCUMENT_ID, body).execute(); }