کلاس google.script.run (API سمت مشتری)

google.script.run یک API جاوا اسکریپت سمت کلاینت ناهمزمان است که در صفحات سرویس HTML موجود است که می تواند توابع برنامه های اسکریپت سمت سرور را فراخوانی کند. برای تعامل با دیالوگ ها یا نوارهای فرعی در 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 . توضیحات را ببینید پارامترهای قانونی اولیه جاوا اسکریپت مانند Number ، Boolean ، String یا null و همچنین اشیا و آرایه های جاوا اسکریپت هستند که از ابتدایی ها، اشیاء و آرایه ها تشکیل شده اند. یک عنصر form در صفحه نیز به عنوان یک پارامتر قانونی است، اما باید تنها پارامتر تابع باشد. اگر بخواهید یک عنصر Date ، Function ، DOM را علاوه بر form ، یا سایر انواع ممنوعه، از جمله انواع ممنوعه در داخل اشیا یا آرایه ها، ارسال کنید، درخواست ها با شکست مواجه می شوند. اشیایی که ارجاعات دایره ای ایجاد می کنند نیز شکست خواهند خورد و فیلدهای تعریف نشده در آرایه ها null می شوند. توجه داشته باشید که یک شیء ارسال شده به سرور به یک کپی از اصل تبدیل می شود. اگر یک تابع سرور یک شی را دریافت کند و ویژگی های آن را تغییر دهد، ویژگی های روی کلاینت تحت تأثیر قرار نمی گیرند.

برگشت

void - این روش ناهمزمان است و مستقیماً بر نمی گردد. با این حال، تابع سمت سرور می تواند یک مقدار را به عنوان یک پارامتر به یک کنترل کننده موفقیت ارسال کند. همچنین، انواع برگشتی مشمول محدودیت‌های مشابه انواع پارامتر هستند، با این تفاوت که عنصر form ، نوع بازگشتی قانونی نیست

withFailureHandler(function)

اگر تابع سمت سرور یک استثنا ایجاد کند، یک تابع برگشت به تماس را تنظیم می کند تا اجرا شود. شی Error به عنوان آرگومان اول به تابع ارسال می شود و شی کاربر (در صورت وجود) به عنوان آرگومان دوم ارسال می شود. بدون کنترل کننده خرابی، خرابی ها در کنسول جاوا اسکریپت ثبت می شوند. برای لغو این مورد، withFailureHandler(null) تماس بگیرید یا یک کنترل کننده خرابی ارائه دهید که هیچ کاری انجام نمی دهد.

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>

مولفه های

نام تایپ کنید شرح
function Function یک تابع فراخوان سمت کلاینت برای اجرا اگر تابع سمت سرور یک استثنا ایجاد کند. شی Error به عنوان آرگومان اول به تابع ارسال می شود و شی کاربر (در صورت وجود) به عنوان آرگومان دوم ارسال می شود.

برگشت

google.script.run - این "اسکریپت اجرا کننده" برای زنجیر کردن

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>

مولفه های

نام تایپ کنید شرح
function Function یک تابع تماس سمت کلاینت برای اجرا در صورت بازگشت موفقیت آمیز تابع سمت سرور. مقدار برگشتی سرور به عنوان آرگومان اول به تابع ارسال می شود و شی کاربر (در صورت وجود) به عنوان آرگومان دوم ارسال می شود.

برگشت

google.script.run - این "اسکریپت اجرا کننده" برای زنجیر کردن

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>

مولفه های

نام تایپ کنید شرح
object Object یک شی برای ارسال به عنوان پارامتر دوم به کنترل کننده های موفقیت و شکست. از آنجایی که اشیاء کاربر به سرور ارسال نمی شوند، مشمول محدودیت در پارامترها و مقادیر بازگشتی برای تماس های سرور نیستند. با این حال، اشیاء کاربر نمی توانند اشیایی باشند که با عملگر new ساخته شده اند

برگشت

google.script.run - این "اسکریپت اجرا کننده" برای زنجیر کردن