מחלקה 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 מגדירה אובייקט שיועבר כפרמטר שני למטפלי ההצלחה והכשל.

תיעוד מפורט

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

החזרות

google.script.run - הקובץ הזה הוא "script Runner" לשרשורים

withSuccessHandler(function)

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

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פונקציית קריאה חוזרת בצד הלקוח להרצה אם הפונקציה בצד השרת חוזרת בהצלחה; הערך המוחזר של השרת מועבר לפונקציה כארגומנט הראשון, ואובייקט המשתמש (אם קיים) מועבר כארגומנט שני

החזרות

google.script.run - הקובץ הזה הוא "script Runner" לשרשורים

withUserObject(object)

מגדירה אובייקט שיועבר כפרמטר שני למטפלי ההצלחה והכשל. "אובייקט המשתמש", בניגוד למחלקה User, מאפשר לפונקציות הקריאה החוזרת להגיב להקשר שבו הלקוח יצר קשר עם השרת. האובייקטים של המשתמשים לא נשלחים לשרת, ולכן הם לא כפופים להגבלות על הפרמטרים ולערכי ההחזרה של קריאות לשרת. עם זאת, אובייקטים של משתמשים לא יכולים להיות אובייקטים שנוצרים באמצעות האופרטור 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 - הקובץ הזה הוא "script Runner" לשרשורים