คลาส 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 ตั้งค่าฟังก์ชันเรียกกลับให้ทำงานหากฟังก์ชันฝั่งเซิร์ฟเวอร์แสดงข้อผิดพลาด
withSuccessHandler(function) google.script.run ตั้งค่าฟังก์ชันเรียกกลับที่จะเรียกใช้หากฟังก์ชันฝั่งเซิร์ฟเวอร์ส่งกลับได้สำเร็จ
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>

พารามิเตอร์

ชื่อTypeคำอธิบาย
...ประเภทส่วนใหญ่ถูกกฎหมาย แต่ไม่ใช่ Date, Function หรือองค์ประกอบ DOM นอกเหนือจาก form ดูคำอธิบายพารามิเตอร์ทางกฎหมายคือ JavaScript แบบพื้นฐาน เช่น Number, Boolean, String หรือ null รวมถึงออบเจ็กต์และอาร์เรย์ JavaScript ที่ประกอบด้วยแบบพื้นฐาน ออบเจ็กต์ และอาร์เรย์ องค์ประกอบ form ภายในหน้าเว็บก็ถือว่าถูกกฎหมายเช่นกันในฐานะพารามิเตอร์ แต่ต้องเป็นพารามิเตอร์เดียวของฟังก์ชันเท่านั้น คำขอจะไม่สำเร็จหากคุณพยายามส่ง Date, Function, องค์ประกอบ DOM นอกเหนือจาก form หรือประเภทที่ไม่อนุญาตอื่นๆ รวมถึงประเภทที่ไม่อนุญาตภายในออบเจ็กต์หรืออาร์เรย์ ออบเจ็กต์ที่สร้างการอ้างอิงแบบวนรอบก็จะล้มเหลวเช่นกัน และฟิลด์ที่ไม่ได้กำหนดภายในอาร์เรย์จะกลายเป็น null โปรดทราบว่าออบเจ็กต์ที่ส่งไปยังเซิร์ฟเวอร์จะกลายเป็นสำเนาของต้นฉบับ หากฟังก์ชันเซิร์ฟเวอร์ได้รับออบเจ็กต์และเปลี่ยนพร็อพเพอร์ตี้ พร็อพเพอร์ตี้ในไคลเอ็นต์จะไม่ได้รับผลกระทบ

รีเทิร์น

void - วิธีนี้เป็นแบบไม่พร้อมกันและไม่แสดงผลโดยตรง แต่ฟังก์ชันฝั่งเซิร์ฟเวอร์จะส่งค่าไปยังไคลเอ็นต์เป็นพารามิเตอร์ที่ส่งไปยังตัวแฮนเดิลความสำเร็จ นอกจากนี้ ประเภทการแสดงผลยังอยู่ภายใต้ข้อจำกัดเดียวกันกับประเภทพารามิเตอร์ เว้นแต่องค์ประกอบ form ไม่ใช่ประเภทการแสดงผลตามกฎหมาย

withFailureHandler(function)

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

พารามิเตอร์

ชื่อTypeคำอธิบาย
functionFunctionฟังก์ชันเรียกกลับฝั่งไคลเอ็นต์ที่จะเรียกใช้หากฟังก์ชันฝั่งเซิร์ฟเวอร์ส่งข้อยกเว้น ระบบจะส่งผ่านออบเจ็กต์ Error ไปยังฟังก์ชันนั้นเป็นอาร์กิวเมนต์แรก และมีการส่งออบเจ็กต์ผู้ใช้ (หากมี) เป็นอาร์กิวเมนต์ที่ 2

รีเทิร์น

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

withSuccessHandler(function)

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

พารามิเตอร์

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

รีเทิร์น

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

withUserObject(object)

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

รีเทิร์น

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