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

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

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

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

גישה לכרטיסיות

אפשר לגשת למאפיינים ולתוכן של הכרטיסייה באמצעות Document.getTabs(), שמחזירה רשימה של Tab. בקטעים הבאים מופיעה סקירה כללית קצרה של המחלקה Tab. מידע מפורט יותר זמין גם במסמכי התיעוד של המחלקה Tab.

מאפייני הכרטיסייה

אפשר לאחזר את מאפייני הכרטיסייה באמצעות שיטות כמו Tab.getId() ו-Tab.getTitle().

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

אפשר לאחזר את תוכן המסמך בכל כרטיסייה באמצעות Tab.asDocumentTab(). בקטע שינויים במבנה של Document Class מוסבר איך אפשר להשתמש בזה.

היררכיית הכרטיסיות

כרטיסיות של ילדים נחשפות ב-Google Apps Script דרך Tab.getChildTabs(). כדי לגשת לתוכן מכל הכרטיסיות, צריך לעבור בין הכרטיסיות המשנה. לדוגמה, מסמך שמכיל היררכיית כרטיסיות באופן הבא:

כדי לגשת אל כרטיסייה 3.1.2, אפשר לבצע את הפעולות הבאות:

// Print the ID of Tab 3.1.2.
const doc = DocumentApp.getActiveDocument();
const tab = doc.getTabs()[2].getChildTabs()[0].getChildTabs()[1];
console.log(tab.getId());

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

דרכים אחרות לשחזור כרטיסיות

יש עוד שתי דרכים לשחזר כרטיסיות:

• ‫Document.getTab(tabId): מחזירה את הכרטיסייה עם המזהה שצוין.
• ‫Document.getActiveTab(): מחזירה את הכרטיסייה הפעילה של המשתמש. הפונקציה פועלת רק בסקריפטים מקשרים למסמך. בקטעים הבאים מוסבר על כך בפירוט.

שינויים במבנה של Document Class

בעבר, לא היה מושג של כרטיסיות במסמכים, ולכן המחלקה Document חשפה שיטות לגישה ישירה לתוכן הטקסטואלי של המסמך ולשינוי שלו. השיטות הבאות נכללות בקטגוריה הזו:

• Document.addBookmark(position)
• Document.addFooter()
• Document.addHeader()
• Document.addNamedRange(name, range)
• Document.getBody()
• Document.getBookmark(id)
• Document.getBookmarks()
• Document.getFooter()
• Document.getFootnotes()
• Document.getHeader()
• Document.getNamedRangeById(id)
• Document.getNamedRanges()
• Document.getNamedRanges(name)
• Document.newPosition(element, offset)
• Document.newRange()

בגלל ההיררכיה המבנית הנוספת של הכרטיסיות, השיטות האלה כבר לא מייצגות באופן סמנטי את תוכן הטקסט מכל הכרטיסיות במסמך. תוכן הטקסט יוצג עכשיו בשכבה אחרת. כל שיטות הטקסט שצוינו למעלה זמינות דרך DocumentTab.

השיטות הקיימות האלה במחלקה Document יגשו לתוכן או ישנו אותו מהכרטיסייה הפעילה (בסקריפטים מאוגדים למסמך מסוים) או מהכרטיסייה הראשונה (אם אין כרטיסייה פעילה).

גישה לתוכן טקסט בכרטיסייה ספציפית

במקום להשתמש בשיטות הטקסט מתוך Document, מומלץ להשתמש בשיטות שזמינות מתוך המחלקה DocumentTab (שזמינה דרך השיטה Tab.asDocumentTab()). לדוגמה:

// Print the text from the body of the active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const body = documentTab.getBody();
console.log(body.getText());

שינויים בבחירת המשתמשים

הערה: הרעיון של בחירת המשתמש רלוונטי רק לסקריפטים שמקושרים למסמך, ורק הם יכולים להשתמש בו או לשנות אותו.

שיטות לבחירת טקסט

המחלקות Document מספקות getters ו-setters כדי לנהל את המיקום בטקסט שהמשתמש בוחר, במסמך הפעיל. השיטות האלה פועלות בהקשר של הכרטיסייה הפעילה של המשתמש שמריץ את הסקריפט.

• ‫Document.getCursor(): מחזירה את מיקום הסמן של המשתמש בכרטיסייה הפעילה.
• ‫Document.getSelection(): מחזירה את טווח הבחירה של המשתמש בכרטיסייה הפעילה.
• ‫Document.setCursor(position): מגדיר את מיקום הסמן של המשתמש במסמך הפעיל. אם המיקום הוא בכרטיסייה לא פעילה, הכרטיסייה הפעילה של המשתמש תעבור גם היא לכרטיסייה שמשויכת למיקום הזה.
• ‫Document.setSelection(range): מגדיר את טווח הבחירה של המשתמש במסמך הפעיל. אם הטווח נמצא בכרטיסייה לא פעילה, הכרטיסייה הפעילה של המשתמש תעבור גם היא לכרטיסייה שמשויכת לטווח הזה.

שיטות לבחירת כרטיסיות ותרחישי שימוש

עם ההשקה של הכרטיסיות, יכול להיות שיהיה לכם שימושי לקבל ולהגדיר את הכרטיסייה הפעילה של המשתמש שמריץ את הסקריפט. אפשר לעשות זאת באמצעות השיטות הבאות:

• ‫Document.getActiveTab(): הפונקציה מחזירה את ה-Tab הפעיל של המשתמש במסמך הפעיל.
• ‫Document.setActiveTab(tabId): מגדיר את Tab שנבחר על ידי המשתמש במסמך הנוכחי לכרטיסייה עם המזהה שצוין.

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

אפשר לשנות באופן מפורש את הכרטיסייה הפעילה של המשתמש באמצעות Document.setActiveTab(tabId). לחלופין, אם מפעילים את הפונקציה Document.setCursor(position) או Document.setSelection(range) עם Position או Range מכרטיסייה לא פעילה, הכרטיסייה הזו תהפוך לפעילה.

אם ההתנהגות הרצויה של הסקריפט היא שימוש בכרטיסייה הפעילה של המשתמש בלי לשנות אותה, אז אין צורך ב-Document.setActiveTab(tabId). השיטות Document.getCursor() ו-Document.getSelection() כבר יפעלו בכרטיסייה הפעילה, בהתאם לכרטיסייה שממנה המשתמש מריץ את הסקריפט.

שימו לב: במסמך אי אפשר לבחור כמה כרטיסיות, כמה מיקומים או כמה טווחים בכרטיסיות שונות. לכן, שימוש בתווית Document.setActiveTab(tabId) ינקה את מיקום הסמן הקודם או את טווח הבחירה.

שיטות למיקום ולטווח של כרטיסייה ספציפית

הכרטיסייה הספציפית היא מה שנותן משמעות למושגים של בחירת הטקסט Position ו-Range. במילים אחרות, למיקום הסמן או לטווח הבחירה יש משמעות רק אם התסריט יודע באיזה כרטיסייה נמצאים המיקום או הטווח.

הפעולה הזו מתבצעת באמצעות ה-methods‏ DocumentTab.newPosition(element, offset) ו-DocumentTab.newRange(), שיוצרות Position או Range שמטרגטים את DocumentTab הספציפי שה-method נקראת ממנו. לעומת זאת, ‫Document.newPosition(element, offset) ו-Document.newRange() ייצרו Position או Range שמכוונים לכרטיסייה הפעילה (או לכרטיסייה הראשונה, אם הסקריפט לא מאוגד).

בקטעים הבאים מופיעות דוגמאות של בלוקים של קוד, שכוללות קוד לדוגמה לעבודה עם בחירות.

דפוסי שימוש נפוצים בכרטיסיות

בדוגמאות הקוד הבאות מתוארות דרכים שונות לאינטראקציה עם כרטיסיות.

קריאת תוכן הכרטיסייה מכל הכרטיסיות במסמך

אפשר להעביר קוד קיים שעשה את זה לפני התכונה 'כרטיסיות' כדי לתמוך בכרטיסיות. לשם כך, צריך לעבור על עץ הכרטיסיות ולקרוא לשיטות getter מ-Tab ומ-DocumentTab במקום מ-Document. בדוגמה החלקית הבאה של קוד מוצג איך להדפיס את כל תוכן הטקסט מכל כרטיסייה במסמך. אפשר להתאים את הקוד הזה למעבר בין כרטיסיות למקרים רבים אחרים שלא דורשים התייחסות למבנה בפועל של הכרטיסיות.

/** Logs all text contents from all tabs in the active document. */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs. DocumentApp.openById('abc123456') can also
  // be used instead of DocumentApp.getActiveDocument().
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from each tab in the document.
  for (const tab of allTabs) {
    // Get the DocumentTab from the generic Tab object.
    const documentTab = tab.asDocumentTab();
    // Get the body from the given DocumentTab.
    const body = documentTab.getBody();
    // Get the body text and log it to the console.
    console.log(body.getText());
  }
}

/**
 * Returns a flat list of all tabs in the document, in the order
 * they would appear in the UI (i.e. top-down ordering). Includes
 * all child tabs.
 */
function getAllTabs(doc) {
  const allTabs = [];
  // Iterate over all tabs and recursively add any child tabs to
  // generate a flat list of Tabs.
  for (const tab of 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.
 */
function addCurrentAndChildTabs(tab, allTabs) {
  allTabs.push(tab);
  for (const childTab of tab.getChildTabs()) {
    addCurrentAndChildTabs(childTab, allTabs);
  }
}

קריאת תוכן הכרטיסייה מהכרטיסייה הראשונה במסמך

זה דומה לקריאת כל הכרטיסיות.

/** 
 * Logs all text contents from the first tab in the active 
 * document. 
 */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs.
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from the first tab in the document.
  const firstTab = allTabs[0];
  // Get the DocumentTab from the generic Tab object.
  const documentTab = firstTab.asDocumentTab();
  // Get the body from the DocumentTab.
  const body = documentTab.getBody();
  // Get the body text and log it to the console.
  console.log(body.getText());
}

עדכון התוכן של הכרטיסייה הראשונה

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

/** Inserts text into the first tab of the active document. */
function insertTextInFirstTab() {
  // Get the first tab's body.
  const doc = DocumentApp.getActiveDocument();
  const firstTab = doc.getTabs()[0];
  const firstDocumentTab = firstTab.asDocumentTab();
  const firstTabBody = firstDocumentTab.getBody();

  // Append a paragraph and a page break to the first tab's body
  // section.
  firstTabBody.appendParagraph("A paragraph.");
  firstTabBody.appendPageBreak();
}

עדכון התוכן של הכרטיסייה הפעילה או הכרטיסייה שנבחרה

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

/**
 * Inserts text into the active/selected tab of the active
 * document.
 */
function insertTextInActiveTab() {
  // Get the active/selected tab's body.
  const doc = DocumentApp.getActiveDocument();
  const activeTab = doc.getActiveTab();
  const activeDocumentTab = activeTab.asDocumentTab();
  const activeTabBody = activeDocumentTab.getBody();

  // Append a paragraph and a page break to the active tab's body
  // section.
  activeTabBody.appendParagraph("A paragraph.");
  activeTabBody.appendPageBreak();
}

הגדרת מיקום סמן או טווח בחירה בכרטיסייה הפעילה

דוגמת הקוד החלקית הבאה מראה איך לעדכן את מיקום הסמן או את טווח הבחירה בכרטיסייה הפעילה של המשתמש. ההגדרה הזו רלוונטית רק בסקריפטים שקשורים למסמכים.

/**
 * Changes the user's selection to select all tables within the tab
 * with the provided ID.
 */
function selectAllTables(tabId) {
  const doc = DocumentApp.getActiveDocument();
  const tab = doc.getTab(tabId);
  const documentTab = tab.asDocumentTab();

  // Build a range that encompasses all tables within the specified
  // tab.
  const rangeBuilder = documentTab.newRange();
  const tables = documentTab.getBody().getTables();
  for (let i = 0; i < tables.length; i++) {
    rangeBuilder.addElement(tables[i]);
  }
  // Set the document's selection to the tables within the specified
  // tab. Note that this actually switches the user's active tab as
  // well.
  doc.setSelection(rangeBuilder.build());
}

הגדרת הכרטיסייה הפעילה או הנבחרת

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

/**
 * Changes the user's selected tab to the tab immediately following
 * the currently selected one. Handles child tabs.
 *
 * 
Only changes the selection if there is a tab following the
 * currently selected one.
 */
function selectNextTab() {
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);
  const activeTab = doc.getActiveTab();

  // Find the index of the currently active tab.
  let activeTabIndex = -1;
  for (let i = 0; i < allTabs.length; i++) {
    if (allTabs[i].getId() === activeTab.getId()) {
      activeTabIndex = i;
    }
  }

  // Update the user's selected tab if there is a valid next tab.
  const nextTabIndex = activeTabIndex + 1;
  if (nextTabIndex < allTabs.length) {
    doc.setActiveTab(allTabs[nextTabIndex].getId());
  }
}