עבודה עם כרטיסיות

Google Docs API מאפשר לכם לגשת לתוכן מכל כרטיסייה במסמך.

מהן כרטיסיות?

ב-Google Docs יש שכבת ארגון שנקראת כרטיסיות. Docs מאפשר למשתמשים ליצור כרטיסייה אחת או יותר בכרטיסייה אחת מסמך, בדומה לאופן שבו יש כרטיסיות כיום ב-Sheets. לכל כרטיסייה יש משלה כותרת ומזהה (המצורפים לכתובת האתר). כרטיסייה יכולה לכלול גם כרטיסיות צאצא, כרטיסיות שמוצבות מתחת לכרטיסייה אחרת.

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

שינויים מבניים באופן שבו תוכן המסמך מיוצג במשאב המסמך

בעבר, לא היה עיקרון של כרטיסיות, Document המשאב נמצא ישירות את כל תוכן הטקסט באמצעות השדות הבאים:

מאחר שיש היררכיה מבנית נוספת של כרטיסיות, השדות האלה כבר לא לייצג את תוכן הטקסט מכל הכרטיסיות במסמך מבחינה סמנטית. תוכן מבוסס-טקסט מיוצג עכשיו בשכבה שונה. מאפייני הכרטיסייה וגם ניתן לגשת לתוכן ב-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();
}