טריגרים פשוטים

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

הערה: למידע על שימוש בטריגרים בפרויקטים של תוספים, ראו טריגרים של תוספים.

איך מתחילים

על מנת להשתמש בטריגר פשוט, יוצרים פונקציה שמשתמשת באחד מהשמות השמורים הבאים:

• onOpen(e) פועל כשמשתמש פותח גיליון אלקטרוני, מסמך, מצגת או טופס שלמשתמש יש הרשאה לערוך אותם.
• onInstall(e) פועל כשמשתמש מתקין תוסף עריכה מתוך Google Docs , Sheets , Slides או Forms.
• הפונקציה onEdit(e) פועלת כשמשתמש משנה ערך בגיליון אלקטרוני.
• הפקודה onSelectionChange(e) פועלת כשמשתמש משנה את הבחירה בגיליון אלקטרוני.
• הפקודה doGet(e) פועלת כשמשתמש נכנס לאפליקציית אינטרנט או שתוכנה שולחת בקשת HTTP GET לאפליקציית אינטרנט.
• הרכיב doPost(e) פועל כשתוכנית שולחת בקשת HTTP POST לאפליקציית אינטרנט.

הפרמטר e בשמות הפונקציות שלמעלה הוא אובייקט אירוע שמועבר לפונקציה. האובייקט מכיל מידע על ההקשר שגרם להפעלת הטריגר, אבל השימוש בו הוא אופציונלי.

הגבלות

מאחר שטריגרים פשוטים מופעלים באופן אוטומטי, בלי לבקש הרשאה מהמשתמש, הם כפופים למספר הגבלות:

• הסקריפט צריך להיות מקושר לקובץ של Google Sheets, Slides, Docs או Forms, או להיות תוסף שמרחיב את אחת מהאפליקציות האלה.
• הן לא פועלות אם קובץ נפתח במצב קריאה-בלבד (הצגה או תגובה).
• הרצת סקריפטים ובקשות API לא גורמים להרצת טריגרים. לדוגמה, קריאה ל-Range.setValue() לעריכת תא לא מפעילה את הטריגר onEdit של הגיליון האלקטרוני.
• הם לא יכולים לגשת לשירותים שדורשים הרשאה. לדוגמה, טריגר פשוט לא יכול לשלוח אימייל כי שירות Gmail מחייב הרשאה, אבל טריגר פשוט יכול לתרגם ביטוי באמצעות שירות השפה, שהוא אנונימי.
• הם יכולים לשנות את הקובץ שאליו הם מחויבים, אבל לא יכולים לגשת לקבצים אחרים כי בשביל לעשות זאת תידרש הרשאה.
• יכול להיות שהם יוכלו לזהות את המשתמש הנוכחי, אבל לא בהכרח, בהתאם לסדרה מורכבות של הגבלות אבטחה.
• הן לא יכולות לפעול יותר מ-30 שניות.
• בנסיבות מסוימות, תוספים ל-Editor מריצים את onOpen(e) ואת onEdit(e) הטריגרים הפשוטים במצב ללא הרשאה, שיש בו כמה סיבוכים נוספים. למידע נוסף, קראו את המדריך למחזור החיים של הרשאות לתוספים.
• טריגרים פשוטים כפופים למגבלות מכסות של טריגר של Apps Script.

ההגבלות האלה לא חלות על doGet(e) או על doPost(e).

onOpen(e)

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

triggers/triggers.gs

הצגת הקוד ב-GitHub

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

הטריגר onInstall(e) פועל באופן אוטומטי כשמשתמש מתקין תוסף עריכה מתוך Google Docs , Sheets , Slides או Forms. הטריגר לא יפעל כשמשתמש יתקין את התוסף מהאתר של Google Workspace Marketplace. שימו לב שיש הגבלות מסוימות על מה שאפשר לעשות עם onInstall(e). אפשר לקרוא מידע נוסף על הרשאה. השימוש הנפוץ ביותר ב-onInstall(e) הוא פשוט לקרוא ל-onOpen(e) כדי להוסיף תפריטים מותאמים אישית. אחרי שמתקינים תוסף, הקובץ כבר פתוח, ולכן onOpen(e) לא פועל בעצמו אלא אם הקובץ נפתח מחדש.

triggers/triggers.gs

הצגת הקוד ב-GitHub

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

הטריגר onEdit(e) פועל באופן אוטומטי כשמשתמש משנה את הערך של תא כלשהו בגיליון האלקטרוני. רוב הטריגרים של onEdit(e) משתמשים במידע שבאובייקט האירוע כדי להגיב בהתאם. לדוגמה, הפונקציה onEdit(e) שלמטה מגדירה בתא תגובה שמתעדת את הפעם האחרונה שבה היא נערכה.

triggers/triggers.gs

הצגת הקוד ב-GitHub

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

הערה: הטריגר onEdit() מציג רק עד 2 אירועי הפעלה בתור.

onSelectionChange(e)

הטריגר onSelectionChange(e) פועל באופן אוטומטי כשמשתמש משנה את הבחירה בגיליון אלקטרוני. כדי להפעיל את הטריגר הזה, צריך לרענן את הגיליון האלקטרוני אחרי שמוסיפים את הטריגר ובכל פעם שהגיליון האלקטרוני נפתח.

אם הבחירה עוברת בין מספר תאים בפרק זמן קצר, ייתכן שהמערכת תדלג על חלק מאירועי שינוי הבחירה כדי לצמצם את זמן האחזור. לדוגמה, אם מבצעים הרבה שינויים בבחירה תוך שתי שניות, רק השינויים הראשונים והאחרונים יפעילו את הטריגר onSelectionChange(e).

בדוגמה הבאה, אם בוחרים תא ריק, הפונקציה onSelectionChange(e) מגדירה את רקע התא לאדום.

triggers/triggers.gs

הצגת הקוד ב-GitHub

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) וגם doPost(e)

הטריגר doGet(e) פועל באופן אוטומטי כשמשתמש מבקר באפליקציית אינטרנט או בתוכנה ששולחים בקשת HTTP מסוג GET לאפליקציית אינטרנט. doPost(e) פועל כשהתוכנית שולחת בקשת HTTP POST לאפליקציית אינטרנט. הטריגרים האלה מוצגים בצורה מפורטת יותר במדריכים לאפליקציות אינטרנט, לשירות HTML ולשירות תוכן. שימו לב: doGet(e) וגם doPost(e) לא כפופים להגבלות שצוינו למעלה.

הסוגים הזמינים של טריגרים

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

אירוע	טריגרים פשוטים	טריגרים שניתנים להתקנה
פתיחה	Sheets Slides Forms* Docs function onOpen(e)	Sheets Forms* Docs
עריכה	Sheets function onEdit(e)	Sheets
שינוי הבחירה	Sheets function onSelectionChange(e)
התקנה	Sheets Slides Forms Docs function onInstall(e)
שינוי		Sheets
טופס נשלח		Sheets Forms
מבוסס-זמן (שעון)		Sheets Slides Forms Docs מיקום עצמאי
הורדה	מיקום מודעה עצמאי function doGet(e)
פוסט	מיקום מודעה עצמאי function doPost(e)

* האירוע הפתוח ב-Google Forms לא מתרחש כשמשתמש פותח טופס כדי להגיב, אלא כשעורך פותח את הטופס כדי לשנות אותו.