מסמכים מורחבים

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

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

הסקריפט של Apps יכול לקיים אינטראקציה עם 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. הפונקציה הראשונה שמופיעה בהמשך מוסיפה כמה שורות של 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 תוכלו לפרסם את הסקריפט כתוסף, כדי שמשתמשים אחרים יוכלו להתקין אותו מחנות התוספים.

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

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

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

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