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

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

ה-method documents.create מחזירה משאב Document שמייצג את מסמך ריק שנוצר. המוחזר Document המשאב יאכלס את תוכן של מסמך ריק גם בשדות תוכן הטקסט של המסמך וגם document.tabs

document.batchUpdate

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

עיינו ב Request שנ' מסמכים ספציפיים.

המשתמשים יכולים ליצור קישורים פנימיים לכרטיסיות, לסימניות ולכותרות במסמך. עם השקת התכונה 'כרטיסיות', link.bookmarkId ו- שדות link.headingId לא יכולים יותר לייצג סימניה או כותרת ספציפית במסמך.

המפתחים צריכים לעדכן את הקוד שלהם כדי להשתמש ב-link.bookmark וב- link.heading בפעולות של קריאה וכתיבה. הם חושפים קישורים פנימיים באמצעות BookmarkLink ו- HeadingLink אובייקטים, כל אחד שמכיל את המזהה של הסימנייה או הכותרת ואת המזהה של הכרטיסייה שבה היא נמצאת. אינץ' בנוסף, link.tabId חושף קישורים פנימיים לכרטיסיות.

גם תוכן הקישור של תשובת documents.get עשוי להשתנות בהתאם ל הפרמטר includeTabsContent:

  • אם המדיניות includeTabsContent מוגדרת לערך true, כל הקישורים הפנימיים ייחשפו. link.bookmark ו-link.heading. שדות מדור קודם (link.bookmarkId ו- link.headingId) לא יהיו בשימוש יותר.
  • אם לא צוין 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();
}