הרחבת Google Docs

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

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

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

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

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.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 של המשתמש, ולאחר מכן מוסיף פסקה שמכילה את אותו הטקסט שמופיע בשם המסמך, סגנונות שפסקה מופיעה ככותרת ומוסיף טבלה המבוססת על הערכים במערך דו-ממדי. הסקריפט יכול לבצע את השינויים האלה במסמך קיים באותה קלות על ידי החלפת הקריאה ל-DocumentApp.create() ב-DocumentApp.openById() או ב-openByUrl(). לסקריפטים שנוצרו בתוך מסמך (כפוף לקונטיינר), משתמשים ב-DocumentApp.getActiveDocument().

המבנה של מסמך

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

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

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

החלפת טקסט

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

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

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

מומלץ להוסיף ערכי placeholder

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

החלפת ה-placeholders

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .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 תוכלו publish את הסקריפט כתוסף, כדי שמשתמשים אחרים יוכלו להתקין אותו מחנות התוספים.

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

גורמים מפעילים

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

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