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

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

الطُرق

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

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

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

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

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>

المَعلمات

الاسمTypeالوصف
...معظم الأنواع قانونية، ولكن ليس 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>

المَعلمات

الاسمTypeالوصف
functionFunctionتشغيل دالة استدعاء من جهة العميل إذا قدّمت الدالة من جهة الخادم استثناءً، إذ يتم تمرير الكائن 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>

المَعلمات

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

استرجاع الكرة

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>

المَعلمات

الاسمTypeالوصف
objectObjectكائنًا ليتم تمريره كمَعلمة ثانية إلى معالِجات النجاح والفشل، ولأن كائنات المستخدم لا يتم إرسالها إلى الخادم، فهي لا تخضع للقيود المطبَّقة على المعلَمات وقيم إرجاع طلبات الخادم. أمّا كائنات المستخدم، فلا يمكن أن تكون كائنات تم إنشاؤها باستخدام عامل التشغيل new.

استرجاع الكرة

google.script.run: "مشغّل النصوص" هذا الخاص بالتسلسل