הרחבת Google Docs

באמצעות Google Apps Script אפשר ליצור ולשנות באופן פרוגרמטי מסמכים ב-Google Docs, וגם להתאים אישית את ממשק המשתמש באמצעות תפריטים, תיבות דו-שיח וסרגלי צד חדשים.

העקרונות הבסיסיים

אפשר לבצע אינטראקציה בין Apps Script לבין Google Docs בשתי דרכים רחבות: כל סקריפט יכול ליצור או לשנות מסמך אם למשתמש של הסקריפט יש הרשאות מתאימות למסמך. אפשר גם לקשר סקריפט למסמך, וכך לתת לסקריפט יכולות מיוחדות לשינוי ממשק המשתמש או לתגובה כשהמסמך נפתח. כדי ליצור סקריפט שמקושר לקונטיינר מתוך Google Docs, לוחצים על תוספים > Apps Script.

בכל מקרה, קל ליצור אינטראקציה עם מסמך ב-Google Docs באמצעות Document Service של Apps Script, כפי שמתואר בדוגמה הבאה.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

הסקריפט שלמעלה יוצר מסמך חדש ב-Google Drive של המשתמש, ואז מאחזר את הכרטיסייה עם המזהה t.0 (הכרטיסייה הראשונה שמוגדרת כברירת מחדל), מוסיף פסקה שמכילה את אותו הטקסט שמופיע בשם המסמך, סגנון את הפיסקה הזו ככותרת ומצרף טבלה בהתאם לערכים במערך דו-ממדי. אפשר לבצע את השינויים האלה בקלות רבה גם באמצעות הסקריפט, על ידי החלפת הקריאה ל-DocumentApp.create() ב-DocumentApp.openById() או ב-openByUrl(). בסקריפטים שנוצרים בתוך מסמך (מקובע לקונטיינר), משתמשים ב-DocumentApp.getActiveDocument() וב-Document.getActiveTab().

המבנה של מסמך

מנקודת המבט של Apps Script, המבנה של מסמך ב-Google Docs דומה למבנה של מסמך HTML. כלומר, מסמך מורכב מאובייקט Tab אחד או יותר, שכל אחד מהם מכיל רכיבים (כמו Paragraph או Table) שכוללים לרוב רכיבים אחרים. רוב הסקריפטים שמבצעים שינויים במסמך ב-Google Docs מתחילים בקריאה ל-getTab() ול-asDocumentTab(), ואחריה getBody(), כי Body הוא רכיב ליבה שמכיל את כל הרכיבים האחרים בכרטיסייה, מלבד HeaderSection,‏ FooterSection וכל רכיב Footnotes.

עם זאת, יש כללים לגבי סוגי הרכיבים שיכולים להכיל סוגים אחרים. בנוסף, שירות המסמכים ב-Apps Script יכול להוסיף רק סוגים מסוימים של אלמנטים לאלמנטים אחרים. בעץ שלמטה מוצגים הרכיבים שאפשר לכלול ברכיב מסוג מסוים.

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

החלפת טקסט

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

יש הרבה דרכים להחליף טקסט, אבל השיטה הפשוטה ביותר היא השיטה replaceText() שמוצגת בדוגמה הבאה. replaceText תומך ברוב תכונות הביטוי הרגולרי של JavaScript. הפונקציה הראשונה שבהמשך מוסיפה כמה שורות של טקסט למעקב אחרי שינויים ב-Google Docs. בעולם האמיתי, סביר יותר שתקלידו את הסמנים למעקב אחרי שינויים במסמך בעצמכם. הפונקציה השנייה מחליפה את ה-placeholders במאפיינים שהוגדרו באובייקט client.

הערה: שתי הפונקציות האלה משתמשות ב-methods getActiveDocument() ו-getActiveTab(), שחלות רק על סקריפטים שנוצרו בתוך מסמך Google Docs. בסקריפט עצמאי, משתמשים ב-DocumentApp.create(), openById() או openByUrl(), בשילוב עם Document.getTab().

מוסיפים כמה placeholders

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

החלפת ה-placeholders

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

תפריטים וממשקי משתמש מותאמים אישית

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

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

תוספים ל-Google Docs

תוספים פועלים בתוך Google Docs וניתן להתקין אותם מחנות התוספים של Google Docs. אם פיתחתם סקריפט ל-Google Docs ואתם רוצים לשתף אותו עם כולם, אתם יכולים לפרסם את הסקריפט כתוסף ב-Apps Script כדי שמשתמשים אחרים יוכלו להתקין אותו מחנות התוספים.

במאמר מדריך למתחילים ליצירת תוספים ל-Docs מוסבר איך יוצרים תוסף ל-Google Docs.

טריגרים

סקריפטים שמקושרים למסמך של Google Docs יכולים להשתמש בטריגר פשוט כדי להגיב לאירוע של onOpen שמתרחש בכל פעם שמשתמש שיש לו גישת עריכה למסמך פותח אותו ב-Google Docs.

כדי להגדיר את הטריגר, פשוט כותבים פונקציה בשם onOpen(). דוגמה לטריגר הזה מופיעה במאמר תפריטים מותאמים אישית ב-Google Workspace. למרות שהטריגר הפשוט הוא שימושי להוספת תפריטים, הוא לא יכול להשתמש בשירותי Apps Script שמחייבים הרשאה.