הרחבת Google Docs

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

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

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

בכל מקרה, אפשר לבצע אינטראקציות עם מסמך 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. בסקריפטים שנוצרו בתוך מסמך (container-bound), משתמשים בפקודות DocumentApp.getActiveDocument ו-Document.getActiveTab.

מבנה המסמך

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

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

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

החלפת טקסט

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

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

שתי הפונקציות האלה משתמשות ב-methods‏ getActiveDocument ו-getActiveTab, שרלוונטיות רק לסקריפטים שנוצרו בתוך מסמך 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}');
}

החלפת הפלייסהולדרים

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);
}

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

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

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

תוספים ל-Docs

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

כדי ליצור תוסף ל-Docs, אפשר לעיין במדריך למתחילים ליצירת תוספים ל-Docs.

טריגרים

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

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