הרחבת Google Docs

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

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

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

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

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.

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

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

החלפת טקסט

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

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

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

הוספת כמה placeholders

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(). דוגמה לטריגר הזה מופיעה במאמר תפריטים בהתאמה אישית ב-Google Workspace. למרות שהטריגר הפשוט הוא שימושי להוספת תפריטים, הוא לא יכול להשתמש בשירותי Apps Script שמחייבים הרשאה.