หน้านี้ได้รับการแปลโดย Cloud Translation API

บริการ HTML: สื่อสารกับฟังก์ชันของเซิร์ฟเวอร์

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

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>
</html>

หากใช้งานสคริปต์นี้เป็นเว็บแอปและเข้าไปที่ URL ของสคริปต์แล้ว คุณจะไม่เห็นข้อมูลใดๆ แต่หากดูบันทึก คุณจะเห็นว่ามีการเรียกฟังก์ชัน doSomething() ของเซิร์ฟเวอร์

การเรียกฟังก์ชันฝั่งไคลเอ็นต์ไปยังฟังก์ชันฝั่งเซิร์ฟเวอร์ไม่พร้อมกัน หลังจากที่เบราว์เซอร์ขอให้เซิร์ฟเวอร์เรียกใช้ฟังก์ชัน doSomething() เบราว์เซอร์จะดำเนินการต่อไปยังบรรทัดโค้ดถัดไปทันทีโดยไม่รอการตอบกลับ ซึ่งหมายความว่าการเรียกใช้ฟังก์ชันของเซิร์ฟเวอร์อาจไม่ทำงานตามลำดับที่คุณคาดหวัง หากคุณเรียกใช้ฟังก์ชัน 2 รายการพร้อมกัน ไม่มีทางรู้ว่าฟังก์ชันใดจะทำงานก่อน ผลลัพธ์อาจแตกต่างกันไปในแต่ละครั้งที่โหลดหน้าเว็บ ในสถานการณ์นี้ ตัวแฮนเดิลที่ประสบความสำเร็จและตัวแฮนเดิลที่ล้มเหลวจะช่วยควบคุมโฟลว์ของโค้ด

google.script.run API อนุญาตให้มีการเรียกฟังก์ชันของเซิร์ฟเวอร์พร้อมกัน 10 ครั้ง ถ้าคุณทำการเรียกครั้งที่ 11 ในขณะที่ 10 ยังทำงานอยู่ ฟังก์ชันของเซิร์ฟเวอร์จะหน่วงเวลาจนกว่าจะมีการปล่อยจุด 1 ใน 10 จุด ในทางปฏิบัติ คุณแทบจะไม่ต้องคิดถึงข้อจำกัดนี้ โดยเฉพาะเพราะเบราว์เซอร์ส่วนใหญ่จำกัดจำนวนคำขอที่ส่งไปยังเซิร์ฟเวอร์เดียวกันพร้อมกันไว้ที่ต่ำกว่า 10 แล้ว ยกตัวอย่างเช่น ใน Firefox ขีดจำกัดคือ 6 ในทำนองเดียวกัน เบราว์เซอร์ส่วนใหญ่มักหน่วงเวลาคำขอของเซิร์ฟเวอร์ที่เกินมาจนกว่าคำขอที่มีอยู่รายการใดรายการหนึ่งจะเสร็จสิ้น

พารามิเตอร์และค่าที่ส่งกลับ

คุณสามารถเรียกฟังก์ชันของเซิร์ฟเวอร์ที่มีพารามิเตอร์จากไคลเอ็นต์ได้ ในทํานองเดียวกัน ฟังก์ชันของเซิร์ฟเวอร์อาจแสดงผลค่าไปยังไคลเอ็นต์เป็นพารามิเตอร์ที่ส่งไปยังตัวแฮนเดิลความสำเร็จ

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

โปรดทราบว่าออบเจ็กต์ที่ส่งไปยังเซิร์ฟเวอร์จะกลายเป็นสำเนาของต้นฉบับ หากฟังก์ชันของเซิร์ฟเวอร์ได้รับออบเจ็กต์และเปลี่ยนพร็อพเพอร์ตี้ พร็อพเพอร์ตี้ในไคลเอ็นต์จะไม่ได้รับผลกระทบ

เครื่องจัดการความสำเร็จ

เนื่องจากโค้ดฝั่งไคลเอ็นต์จะทํางานต่อไปที่บรรทัดถัดไปโดยไม่ต้องรอให้การเรียกจากเซิร์ฟเวอร์เสร็จสมบูรณ์ withSuccessHandler(function) จึงให้คุณระบุฟังก์ชันเรียกกลับฝั่งไคลเอ็นต์ให้ทํางานเมื่อเซิร์ฟเวอร์ตอบสนองได้ หากฟังก์ชันเซิร์ฟเวอร์แสดงผลค่า API จะส่งค่าไปยังฟังก์ชันใหม่เป็นพารามิเตอร์

ตัวอย่างต่อไปนี้แสดงการแจ้งเตือนของเบราว์เซอร์เมื่อเซิร์ฟเวอร์ตอบสนอง โปรดทราบว่าตัวอย่างโค้ดนี้ต้องมีการให้สิทธิ์เนื่องจากฟังก์ชันฝั่งเซิร์ฟเวอร์กำลังเข้าถึงบัญชี Gmail ของคุณ วิธีที่ง่ายที่สุดในการให้สิทธิ์สคริปต์คือการเรียกใช้ฟังก์ชัน getUnreadEmails() ด้วยตนเองจากเครื่องมือแก้ไขสคริปต์ 1 ครั้งก่อนที่จะโหลดหน้าเว็บ หรือเมื่อทำให้เว็บแอปใช้งานได้ คุณสามารถเลือกที่จะเรียกใช้แอปเป็น "ผู้ใช้ที่เข้าถึงเว็บแอป" ซึ่งในกรณีนี้คุณจะได้รับข้อความแจ้งให้ให้สิทธิ์เมื่อโหลดแอป

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>

เครื่องจัดการความล้มเหลว

ในกรณีที่เซิร์ฟเวอร์ไม่ตอบสนองหรือเกิดข้อผิดพลาด 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>

ออบเจ็กต์ผู้ใช้

คุณใช้เครื่องจัดการความสำเร็จหรือความล้มเหลวเดียวกันซ้ำสำหรับการเรียกหลายรายการไปยังเซิร์ฟเวอร์ได้โดยการเรียกใช้ withUserObject(object) เพื่อระบุออบเจ็กต์ที่จะส่งไปยังตัวแฮนเดิลเป็นพารามิเตอร์ที่ 2 "ออบเจ็กต์ผู้ใช้" นี้ อย่าสับสนกับคลาส User จะให้คุณตอบกลับบริบทที่ไคลเอ็นต์ติดต่อกับเซิร์ฟเวอร์ได้ เนื่องจากระบบจะไม่ส่งออบเจ็กต์ผู้ใช้ไปยังเซิร์ฟเวอร์ ออบเจ็กต์ดังกล่าวอาจเป็นอะไรก็ได้เกือบทั้งหมด รวมถึงฟังก์ชัน องค์ประกอบ DOM ฯลฯ โดยไม่มีข้อจำกัดด้านพารามิเตอร์และจะแสดงผลค่าสำหรับการเรียกเซิร์ฟเวอร์ แต่ออบเจ็กต์ผู้ใช้เป็นออบเจ็กต์ที่สร้างด้วยโอเปอเรเตอร์ new ไม่ได้

ในตัวอย่างนี้ การคลิกปุ่มใดปุ่มหนึ่งจาก 2 ปุ่มจะอัปเดตปุ่มนั้นด้วยค่าจากเซิร์ฟเวอร์และไม่เปลี่ยนแปลงอีกปุ่มหนึ่ง แม้ว่าทั้ง 2 ปุ่มจะใช้เครื่องจัดการความสำเร็จร่วมกันเพียงตัวเดียว ภายในตัวแฮนเดิล onclick คีย์เวิร์ด this หมายถึงตัวbutton

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>

แบบฟอร์ม

หากเรียกฟังก์ชันของเซิร์ฟเวอร์ที่มีองค์ประกอบ form เป็นพารามิเตอร์ แบบฟอร์มจะกลายเป็นออบเจ็กต์เดียวที่มีชื่อช่องเป็นคีย์และค่าของช่องเป็นค่า ระบบจะแปลงค่าทั้งหมดเป็นสตริง ยกเว้นเนื้อหาของช่องอินพุตไฟล์ ซึ่งจะกลายเป็นออบเจ็กต์ Blob

ตัวอย่างนี้จะประมวลผลแบบฟอร์ม รวมถึงช่องอินพุตไฟล์โดยไม่ต้องโหลดหน้าซ้ำ ระบบจะอัปโหลดไฟล์ไปยัง Google ไดรฟ์แล้วพิมพ์ URL ของไฟล์ในหน้าฝั่งไคลเอ็นต์ ภายในเครื่องจัดการ onsubmit คีย์เวิร์ด this หมายถึงแบบฟอร์ม โปรดทราบว่าเมื่อโหลดแบบฟอร์มทั้งหมดในหน้าเว็บ ระบบจะปิดการส่งตามค่าเริ่มต้นโดย preventFormSubmit วิธีนี้จะช่วยป้องกันไม่ให้หน้าเว็บเปลี่ยนเส้นทางไปยัง URL ที่ไม่ถูกต้องในกรณีที่มีข้อยกเว้น

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function processForm(formObject) {
  var formBlob = formObject.myFile;
  var driveFile = DriveApp.createFile(formBlob);
  return driveFile.getUrl();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      // Prevent forms from submitting.
      function preventFormSubmit() {
        var forms = document.querySelectorAll('form');
        for (var i = 0; i < forms.length; i++) {
          forms[i].addEventListener('submit', function(event) {
            event.preventDefault();
          });
        }
      }
      window.addEventListener('load', preventFormSubmit);

      function handleFormSubmit(formObject) {
        google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
      }
      function updateUrl(url) {
        var div = document.getElementById('output');
        div.innerHTML = '<a href="' + url + '">Got it!</a>';
      }
    </script>
  </head>
  <body>
    <form id="myForm" onsubmit="handleFormSubmit(this)">
      <input name="myFile" type="file" />
      <input type="submit" value="Submit" />
    </form>
    <div id="output"></div>
 </body>
</html>

ตัวเรียกใช้สคริปต์

อาจมองว่า google.script.run เป็นเครื่องมือสร้างสำหรับ "โปรแกรมเรียกใช้สคริปต์" หากเพิ่มตัวแฮนเดิลการทำงานสำเร็จ ตัวแฮนเดิลความล้มเหลว หรือออบเจ็กต์ผู้ใช้ลงในตัวเรียกใช้สคริปต์ ก็หมายความว่าคุณไม่ได้เปลี่ยนตัวเรียกใช้ที่มีอยู่ แต่จะได้ตัวเรียกใช้สคริปต์ใหม่ที่มีลักษณะการทำงานแบบใหม่กลับมา

คุณสามารถใช้ชุดค่าผสมใดก็ได้และลำดับใดก็ได้ของ withSuccessHandler(), withFailureHandler() และ withUserObject() และยังสามารถเรียกใช้ฟังก์ชันการแก้ไขในโปรแกรมเรียกใช้สคริปต์ที่มีชุดค่าแล้ว ค่าใหม่เพียงแค่ลบล้างค่าก่อนหน้า

ตัวอย่างนี้ตั้งค่าเครื่องจัดการความล้มเหลวทั่วไปสำหรับการเรียกเซิร์ฟเวอร์ทั้ง 3 รายการ แต่มีเครื่องจัดการความสำเร็จ 2 รายการแยกกัน ดังนี้

var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);

myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();

ฟังก์ชันส่วนตัว

ฟังก์ชันเซิร์ฟเวอร์ที่มีชื่อลงท้ายด้วยขีดล่างจะถือว่าเป็นส่วนตัว โดย google.script จะเรียกใช้ฟังก์ชันเหล่านี้ไม่ได้ และจะไม่มีการส่งชื่อไปยังไคลเอ็นต์ ดังนั้นคุณจึงใช้ครีเอทีฟโฆษณาดังกล่าวเพื่อซ่อนรายละเอียดการใช้งานที่จำเป็นต้องเก็บเป็นความลับบนเซิร์ฟเวอร์ได้ นอกจากนี้ google.script จะดูฟังก์ชันในไลบรารีและฟังก์ชันที่ไม่ได้ประกาศที่ระดับบนสุดของสคริปต์ไม่ได้ด้วย

ในตัวอย่างนี้ ฟังก์ชัน getBankBalance() มีอยู่ในไคลเอ็นต์ ผู้ใช้ที่ตรวจสอบซอร์สโค้ดของคุณจะค้นพบชื่อได้แม้ว่าคุณจะไม่ได้เรียกโค้ดนั้นก็ตาม แต่ไคลเอ็นต์จะไม่เห็นฟังก์ชัน deepSecret_() และ obj.objectMethod() โดยสิ้นเชิง

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getBankBalance() {
  var email = Session.getActiveUser().getEmail()
  return deepSecret_(email);
}

function deepSecret_(email) {
 // Do some secret calculations
 return email + ' has $1,000,000 in the bank.';
}

var obj = {
  objectMethod: function() {
    // More secret calculations
  }
};

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(balance) {
        var div = document.getElementById('output');
        div.innerHTML = balance;
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getBankBalance();
    </script>
  </head>
  <body>
    <div id="output">No result yet...</div>
  </body>
</html>

ปรับขนาดกล่องโต้ตอบใน Google Workspace แอปพลิเคชัน

กล่องโต้ตอบที่กำหนดเองใน Google เอกสาร ชีต หรือฟอร์มสามารถปรับขนาดได้โดยเรียกใช้เมธอด google.script.host setWidth(width) หรือ setHeight(height) ในโค้ดฝั่งไคลเอ็นต์ (หากต้องการกำหนดขนาดเริ่มต้นของกล่องโต้ตอบ ให้ใช้เมธอด HtmlOutput setWidth(width) และ setHeight(height)) โปรดทราบว่ากล่องโต้ตอบจะไม่จัดกึ่งกลางใหม่ในหน้าต่างหลักเมื่อปรับขนาด และจะเปลี่ยนแถบด้านข้างไม่ได้

การปิดกล่องโต้ตอบและแถบด้านข้างใน Google Workspace

หากใช้บริการ HTML เพื่อแสดงกล่องโต้ตอบหรือแถบด้านข้างใน Google เอกสาร ชีต หรือฟอร์ม คุณจะปิดอินเทอร์เฟซด้วยการเรียก window.close() ไม่ได้ คุณต้องโทรหา google.script.host.close() แทน ดูตัวอย่างได้ที่ส่วนการแสดง HTML เป็น Google Workspace อินเทอร์เฟซผู้ใช้

กำลังย้ายโฟกัสของเบราว์เซอร์ใน Google Workspace

หากต้องการเปลี่ยนโฟกัสในเบราว์เซอร์ของผู้ใช้จากกล่องโต้ตอบหรือแถบด้านข้างกลับไปเป็นเครื่องมือแก้ไข Google เอกสาร ชีต หรือฟอร์ม ให้เรียกใช้เมธอด google.script.host.editor.focus() วิธีการนี้เป็นประโยชน์อย่างยิ่งเมื่อใช้ร่วมกับเมธอด บริการเอกสาร Document.setCursor(position) และ Document.setSelection(range)