מחלקה google.script.run (ממשק API בצד הלקוח)

google.script.run הוא ממשק API אסינכרוני של JavaScript בצד הלקוח שזמין ב- דפי שירות HTML שיכולים לקרוא ל-Apps Script בצד השרת למשימות ספציפיות. לבצע פעולות בתיבות דו-שיח או בסרגלי צד ב-Google Docs, ב-Sheets או ב-Forms מצד הלקוח את הקוד, יש להשתמש ב-google.script.host. מידע נוסף זמין במאמר מדריך לתקשורת עם פונקציות שרת בשירות HTML.

שיטות

שיטהסוג הערך המוחזרתיאור קצר
myFunction(...) (כל פונקציה בצד השרת) void מפעיל את פונקציית Apps Script בצד השרת עם השם המתאים.
withFailureHandler(function) google.script.run מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת גורמת לחריגה.
withSuccessHandler(function) google.script.run מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת חוזרת בהצלחה.
withUserObject(object) google.script.run מגדיר אובייקט שיועבר כפרמטר שני לרכיבי ה-handler של הצלחה וכשלים.

מסמכי תיעוד מפורטים

myFunction(...) (כל פונקציה בצד השרת)

מפעיל את פונקציית Apps Script בצד השרת עם השם המתאים.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function doSomething() {
  Logger.log('I was called!');
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      google.script.run.doSomething();
    </script>
  </head>
  <body>
  </body>
</html>

פרמטרים

שםסוגתיאור
...רוב הסוגים הם משפטיים, אבל לא Date, Function, או רכיב DOM שאינו form; הצגת התיאורפרמטרים משפטיים הם JavaScript רכיבים בסיסיים כמו Number, Boolean, String או null, וגם אובייקטים ומערכים של JavaScript שמורכבים מפרימיטיבים, אובייקטים ומערכים. גם רכיב form בדף הוא חוקי כפרמטר, אבל הוא חייב להיות הפרמטר היחיד של הפונקציה. הבקשות ייכשלו אם תנסו להעביר Date, Function, רכיב DOM מלבד form או רכיב אחר סוג אסור, כולל סוגים אסורים בתוך אובייקטים או מערכים. אובייקטים שיוצרים מעגלי גם ההפניות ייכשלו, ושדות לא מוגדרים בתוך מערכים יהפכו ל-null. שימו לב אובייקט שמועבר לשרת הופך לעותק של המקור. אם פונקציית שרת מקבלת ומשנה את המאפיינים שלו, המאפיינים של הלקוח לא מושפעים.

חזרה

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

withFailureHandler(function)

מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת גורמת לחריגה. Error מועבר לפונקציה כארגומנט הראשון, אובייקט user (אם יש) מועבר כארגומנט שני. ללא מטפל בכשלים, הכשלים נרשמים בלוח JavaScript. כדי לשנות את זה, צריך להפעיל withFailureHandler(null) או לספק handler של כשל שלא עושה דבר.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  // 'got' instead of 'get' will throw an error.
  return GmailApp.gotInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onFailure(error) {
        var div = document.getElementById('output');
        div.innerHTML = "ERROR: " + error.message;
      }

      google.script.run.withFailureHandler(onFailure)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

פרמטרים

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

חזרה

google.script.run — 'הרצת הסקריפטים' הזה, לשרשורים

withSuccessHandler(function)

מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת חוזרת בהצלחה. המיקום של המוחזר מועבר לפונקציה כארגומנט הראשון, user object (אם קיים) מועבר כארגומנט שני.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  return GmailApp.getInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(numUnread) {
        var div = document.getElementById('output');
        div.innerHTML = 'You have ' + numUnread
            + ' unread messages in your Gmail inbox.';
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

פרמטרים

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

חזרה

google.script.run — 'הרצת הסקריפטים' הזה, לשרשורים

withUserObject(object)

מגדיר אובייקט שיועבר כפרמטר שני לרכיבי ה-handler של הצלחה וכשלים. "המשתמש הזה object&quot; - בלי להתבלבל עם המחלקה User — מאפשרת לבצע את הקריאה החוזרת (callback) מגיבות להקשר שבו הלקוח יצר קשר עם השרת. כי אובייקטים של משתמשים לא נשלחים לשרת, הם אינם כפופים למגבלות על פרמטרים והחזרות לערכים של קריאות שרת. עם זאת, האובייקטים של המשתמש לא יכולים להיות אובייקטים שנוצר באמצעות האופרטור new.

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getEmail() {
  return Session.getActiveUser().getEmail();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function updateButton(email, button) {
        button.value = 'Clicked by ' + email;
      }
    </script>
  </head>
  <body>
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
  </body>
</html>

פרמטרים

שםסוגתיאור
objectObjectאובייקט להעברה כפרמטר שני למטפלים בהצלחות ובכשלים. מכיוון שאובייקטים של משתמשים לא נשלחים לשרת, הם לא בכפוף למגבלות על פרמטרים וערכי החזרה עבור קריאות שרת. עם זאת, אי אפשר ליצור אובייקטים של משתמשים באמצעות האופרטור new

חזרה

google.script.run — 'הרצת הסקריפטים' הזה, לשרשורים