الفئة google.script.run (واجهة برمجة تطبيقات من جهة العميل)

google.script.run هي واجهة برمجة تطبيقات JavaScript غير متزامنة من جهة العميل متاحة في صفحات خدمة HTML التي يمكنها استدعاء "برمجة تطبيقات Google" من جهة الخادم الأخرى. للتفاعل مع مربعات الحوار أو الأشرطة الجانبية في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google" من جهة العميل الرمز، استخدِم google.script.host. لمزيد من المعلومات، يُرجى الاطّلاع على دليل التواصل مع وظائف الخادم في خدمة HTML.

الطُرق

الطريقةنوع الإرجاعوصف قصير
myFunction(...) (أي دالة من جهة الخادم) void لتنفيذ وظيفة "برمجة تطبيقات Google" من جهة الخادم بالاسم المقابل
withFailureHandler(function) google.script.run تضبط دالة استدعاء للتشغيل إذا طرحت الدالة من جانب الخادم استثناءً.
withSuccessHandler(function) google.script.run ضبط دالة رد اتصال ليتم تشغيلها إذا تم إرجاع الدالة من جانب الخادم بنجاح.
withUserObject(object) google.script.run تضبط كائنًا لتمريره كمَعلمة ثانية إلى معالِجات النجاح والفشل.

الوثائق التفصيلية

myFunction(...) (أي دالة من جهة الخادم)

لتنفيذ وظيفة "برمجة تطبيقات Google" من جهة الخادم بالاسم المقابل

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) أو قم بتوفير معالج إخفاق لا يفعل أي شيء.

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 — هذا "مشغل النصوص البرمجية"، للسلسلة

withSuccessHandler(function)

ضبط دالة رد اتصال ليتم تشغيلها إذا تم إرجاع الدالة من جانب الخادم بنجاح. عنوان URL الخاص بالخادم يتم تمرير القيمة المعروضة إلى الدالة كوسيطة أولى، يتم تمرير كائن المستخدم (إن توفّر) كوسيطة ثانية.

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 — هذا "مشغل النصوص البرمجية"، للسلسلة

withUserObject(object)

تضبط كائنًا لتمريره كمَعلمة ثانية إلى معالِجات النجاح والفشل. هذا "المستخدم object&quot; - لا يجب الخلط بينه وبين فئة واحدة (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 — هذا "مشغل النصوص البرمجية"، للسلسلة