הרחבת 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.

חשוב לזכור ששתי הפונקציות האלה משתמשות בשיטות 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}');
}

החלפת ערכי ה-placeholder

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 שדורשים הרשאה.