คลาส google.script.run (API ฝั่งไคลเอ็นต์)

google.script.run คือ JavaScript API ฝั่งไคลเอ็นต์แบบอะซิงโครนัสซึ่งมีให้บริการใน หน้าบริการ HTML ที่เรียกใช้ Apps Script ฝั่งเซิร์ฟเวอร์ได้ หากต้องการโต้ตอบกับกล่องโต้ตอบหรือแถบด้านข้างใน Google เอกสาร, ชีต หรือฟอร์มจากฝั่งไคลเอ็นต์ ให้ใช้ google.script.host สำหรับข้อมูลเพิ่มเติม โปรดดู คู่มือการสื่อสารกับฟังก์ชันของเซิร์ฟเวอร์ ในบริการ HTML

เมธอด

วิธีการประเภทการแสดงผลรายละเอียดแบบย่อ
myFunction(...) (ฟังก์ชันฝั่งเซิร์ฟเวอร์ใดก็ได้) void เรียกใช้ฟังก์ชัน Apps Script ฝั่งเซิร์ฟเวอร์ด้วยชื่อที่ตรงกัน
withFailureHandler(function) google.script.run ตั้งค่าฟังก์ชัน Callback ให้ทำงาน หากฟังก์ชันฝั่งเซิร์ฟเวอร์ส่งข้อยกเว้น
withSuccessHandler(function) google.script.run ตั้งค่าฟังก์ชัน Callback ให้ทำงานหากฟังก์ชันฝั่งเซิร์ฟเวอร์แสดงผลสำเร็จ
withUserObject(object) google.script.run ตั้งค่าออบเจ็กต์เพื่อส่งผ่านเป็นพารามิเตอร์ที่ 2 ไปยังเครื่องจัดการสำเร็จและความล้มเหลว

เอกสารโดยละเอียด

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)

ตั้งค่าฟังก์ชัน Callback ให้ทำงาน หากฟังก์ชันฝั่งเซิร์ฟเวอร์ส่งข้อยกเว้น Error ไปยังฟังก์ชันเป็นอาร์กิวเมนต์แรก และ ออบเจ็กต์ผู้ใช้ (หากมี) จะส่งเป็นอาร์กิวเมนต์ที่ 2 ไม่มี เครื่องจัดการความล้มเหลว บันทึกความล้มเหลวลงในคอนโซล 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ฟังก์ชัน Callback ฝั่งไคลเอ็นต์เพื่อ เรียกใช้หากฟังก์ชันฝั่งเซิร์ฟเวอร์แสดงผลข้อยกเว้น เวลา Error ไปยังฟังก์ชันเป็นอาร์กิวเมนต์แรก และ ออบเจ็กต์ผู้ใช้ (หากมี) จะส่งเป็นอาร์กิวเมนต์ที่ 2

รีเทิร์น

google.script.run — "โปรแกรมเรียกใช้สคริปต์" นี้ สำหรับการทำโซ่

withSuccessHandler(function)

ตั้งค่าฟังก์ชัน Callback ให้ทำงานหากฟังก์ชันฝั่งเซิร์ฟเวอร์แสดงผลสำเร็จ เซิร์ฟเวอร์ จะส่งค่าที่ส่งกลับไปยังฟังก์ชันเป็นอาร์กิวเมนต์แรก และฟังก์ชัน user object (หากมี) จะส่งเป็นอาร์กิวเมนต์ที่ 2

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ฟังก์ชัน Callback ฝั่งไคลเอ็นต์เพื่อ ทำงานหากฟังก์ชันฝั่งเซิร์ฟเวอร์แสดงผลสำเร็จ จะส่งค่าส่งกลับของเซิร์ฟเวอร์ไปยัง เป็นอาร์กิวเมนต์แรก และออบเจ็กต์ผู้ใช้ (หากมี) มีการส่งเป็นอาร์กิวเมนต์ที่ 2

รีเทิร์น

google.script.run — "โปรแกรมเรียกใช้สคริปต์" นี้ สำหรับการทำโซ่

withUserObject(object)

ตั้งค่าออบเจ็กต์เพื่อส่งผ่านเป็นพารามิเตอร์ที่ 2 ไปยังเครื่องจัดการสำเร็จและความล้มเหลว "ผู้ใช้" นี้ 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ออบเจ็กต์ที่จะส่งผ่านเป็นพารามิเตอร์ที่ 2 สำหรับเครื่องจัดการความสำเร็จและความล้มเหลว เนื่องจากไม่ได้ส่งออบเจ็กต์ผู้ใช้ไปยังเซิร์ฟเวอร์ อยู่ภายใต้ข้อจำกัดเกี่ยวกับพารามิเตอร์และค่าที่ส่งกลับสำหรับ การเรียกเซิร์ฟเวอร์ ออบเจ็กต์ผู้ใช้ต้องไม่เป็นออบเจ็กต์ที่สร้างขึ้น โดยใช้โอเปอเรเตอร์ new

รีเทิร์น

google.script.run — "โปรแกรมเรียกใช้สคริปต์" นี้ สำหรับการทำโซ่