Usługa HTML: komunikacja z funkcjami serwera

google.script.run to asynchroniczny interfejs API JavaScript po stronie klienta, który umożliwia stronom usługi HTML wywoływanie funkcji Apps Script po stronie serwera. Poniższy przykład pokazuje najbardziej podstawową funkcję google.script.run – wywoływanie funkcji na serwerze z poziomu JavaScriptu po stronie klienta.

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>

Jeśli wdrożysz ten skrypt jako aplikację internetową i otworzysz jej adres URL, nic nie zobaczysz, ale jeśli wyświetlisz logi, zauważysz, że wywołana została funkcja serwera doSomething.

Wywołania funkcji po stronie serwera z poziomu klienta są asynchroniczne: po tym, jak przeglądarka zażąda od serwera uruchomienia funkcji doSomething, od razu przechodzi do następnego wiersza kodu, nie czekając na odpowiedź. Oznacza to, że wywołania funkcji serwera mogą nie być wykonywane w oczekiwanej kolejności. Jeśli wykonasz 2 wywołania funkcji w tym samym czasie, nie będziesz mieć pewności, która z nich zostanie uruchomiona jako pierwsza. Wynik może się różnić przy każdym wczytaniu strony. W takiej sytuacji funkcje obsługi powodzenia i funkcje obsługi niepowodzenia pomagają kontrolować przepływ kodu.

Interfejs google.script.run API umożliwia 10 jednoczesnych wywołań funkcji serwera. Jeśli wykonasz 11 połączenie, gdy 10 połączeń jest nadal aktywnych, funkcja serwera zostanie opóźniona, dopóki nie zwolni się jedno z 10 miejsc. W praktyce rzadko musisz się martwić tym ograniczeniem, zwłaszcza że większość przeglądarek ogranicza już liczbę jednoczesnych żądań do tego samego serwera do wartości mniejszej niż 10. Na przykład w Firefoxie limit wynosi 6. Większość przeglądarek podobnie opóźnia nadmiarowe żądania serwera, dopóki nie zostanie zrealizowane jedno z dotychczasowych żądań.

Parametry i zwracane wartości

Wywołaj funkcję serwera z parametrami klienta. Podobnie funkcja serwera może zwrócić wartość do klienta jako parametr przekazany do procedury obsługi sukcesu.

Prawidłowe parametry i wartości zwracane to podstawowe typy danych JavaScript, takie jak Number, Boolean, String lub null, a także obiekty i tablice JavaScript, które składają się z podstawowych typów danych, obiektów i tablic. Element form na stronie jest też prawidłowy jako parametr, ale musi być jedynym parametrem funkcji i nie może być wartością zwracaną. Żądania nie powiodą się, jeśli spróbujesz przekazać element Date, Function lub DOM inny niż form lub inny zabroniony typ, w tym zabronione typy w obiektach lub tablicach. Obiekty, które tworzą odwołania cykliczne, również nie działają, a niezdefiniowane pola w tablicach stają się null.

Pamiętaj, że obiekt przekazany na serwer staje się kopią oryginału. Jeśli funkcja serwera otrzyma obiekt i zmieni jego właściwości, nie wpłynie to na właściwości po stronie klienta.

Obsługa powodzenia

Ponieważ wywołania google.script.run są asynchroniczne, kod po stronie klienta przechodzi do następnego wiersza bez czekania na odpowiedź. Aby określić funkcję wywołania zwrotnego, która jest uruchamiana, gdy serwer odpowiada, użyj withSuccessHandler(function). Jeśli funkcja serwera zwraca wartość, interfejs API przekazuje ją do funkcji wywołania zwrotnego jako parametr.

Poniższy przykład pokazuje alert przeglądarki, gdy serwer odpowiada. Ten przykładowy kod wymaga autoryzacji, ponieważ funkcja po stronie serwera uzyskuje dostęp do Twojego konta Gmail. Aby autoryzować skrypt, uruchom funkcję getUnreadEmails ręcznie w edytorze skryptów, zanim załadujesz stronę. Jeśli wdrożysz aplikację internetową, aby działała jako „użytkownik uzyskujący dostęp do aplikacji internetowej”, podczas wczytywania aplikacji pojawi się prośba o autoryzację.

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>

Moduły obsługi błędów

Jeśli serwer nie odpowie lub zgłosi błąd,withFailureHandler(function) umożliwia określenie procedury obsługi błędów, która zostanie uruchomiona zamiast procedury obsługi powodzenia. Jeśli wystąpi błąd, interfejs API przekazuje obiekt Error jako argument do modułu obsługi błędów.

Domyślnie, jeśli nie określisz modułu obsługi błędów, błędy są rejestrowane w konsoli JavaScript. Aby to zmienić, wywołaj funkcję withFailureHandler(null) lub podaj funkcję obsługi błędów, która nic nie robi.

Składnia funkcji obsługi błędów jest niemal identyczna ze składnią funkcji obsługi powodzeń, co widać na tym przykładzie.

Code.gs

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

function getUnreadEmails() {
  // 'got' instead of 'get' throws 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>

Obiekty użytkownika

Aby ponownie użyć tego samego modułu obsługi sukcesu lub błędu w przypadku wielu wywołań serwera, wywołaj withUserObject(object), aby określić obiekt, który jest przekazywany do modułu obsługi jako drugi parametr. Ten „obiekt użytkownika”, którego nie należy mylić z klasą User, umożliwia odpowiadanie na kontekst, w którym klient skontaktował się z serwerem. Obiekty użytkownika nie są wysyłane na serwer, więc mogą być dowolnymi elementami, w tym funkcjami i elementami DOM, bez ograniczeń dotyczących parametrów i wartości zwracanych w przypadku wywołań serwera. Obiekty użytkownika nie mogą być obiektami utworzonymi za pomocą operatora new.

W tym przykładzie kliknięcie dowolnego z 2 przycisków powoduje zaktualizowanie tego przycisku o wartość z serwera, a drugi przycisk pozostaje bez zmian, mimo że oba przyciski mają ten sam moduł obsługi sukcesu. W funkcji obsługi onclick słowo kluczowe this odnosi się do samego 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>

Formularze

Jeśli wywołasz funkcję serwera z elementem form jako parametrem, formularz stanie się pojedynczym obiektem, w którym nazwy pól będą kluczami, a wartości pól – wartościami. Wszystkie wartości są konwertowane na ciągi znaków, z wyjątkiem zawartości pól file-input, które stają się obiektami Blob.

Ten przykład przetwarza formularz, w tym pole wprowadzania pliku, bez ponownego wczytywania strony. Przesyła plik na Dysk Google, a następnie drukuje adres URL pliku na stronie po stronie klienta. W funkcji obsługi onsubmit słowo kluczowe this odnosi się do samego formularza. Pamiętaj, że po wczytaniu wszystkich formularzy na stronie domyślna czynność przesyłania jest wyłączona przez preventFormSubmit. Zapobiega to przekierowaniu strony do nieprawidłowego adresu URL w przypadku wystąpienia wyjątku.

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>

Uruchamiający skrypt

google.script.run to narzędzie do tworzenia „skryptów”. Jeśli dodasz do narzędzia do uruchamiania skryptów moduł obsługi sukcesu, moduł obsługi błędów lub obiekt użytkownika, nie zmienisz istniejącego narzędzia. Zamiast tego otrzymasz nowe narzędzie do uruchamiania skryptów z nowym działaniem.

Możesz użyć dowolnej kombinacji i dowolnej kolejności właściwości withSuccessHandler, withFailureHandler i withUserObject. Wywołuj też dowolne funkcje modyfikujące w przypadku narzędzia do uruchamiania skryptów, które ma już ustawioną wartość. Nowa wartość zastępuje poprzednią.

W tym przykładzie ustawiono wspólny moduł obsługi błędów dla wszystkich 3 wywołań serwera, ale 2 osobne moduły obsługi sukcesu:

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

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

Funkcje prywatne

Funkcje serwera, których nazwy kończą się podkreśleniem, są uważane za prywatne. Funkcji tych nie można wywoływać za pomocą google.script, a ich nazwy nigdy nie są wysyłane do klienta. Możesz ich używać do ukrywania szczegółów implementacji, które muszą pozostać tajne na serwerze. google.script nie widzi też funkcji w bibliotekach ani funkcji, które nie zostały zadeklarowane na najwyższym poziomie skryptu.

W tym przykładzie funkcja getBankBalance jest dostępna w kodzie klienta. Użytkownik, który sprawdzi Twój kod źródłowy, może odkryć jej nazwę, nawet jeśli jej nie wywołasz. Funkcje deepSecret_ i obj.objectMethod są jednak całkowicie niewidoczne dla klienta.

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>

Zmiana rozmiaru okien w aplikacjach Google Workspace

Niestandardowe okna dialogowe w Dokumentach Google, Arkuszach Google lub Formularzach Google można zmieniać, wywołując metody google.script.host, setWidth(width) lub setHeight(height) w kodzie po stronie klienta. (Aby ustawić początkowy rozmiar okna, użyj metod HtmlOutput methods setWidth(width) and setHeight(height).) Pamiętaj, że po zmianie rozmiaru okna nie jest ono ponownie wyśrodkowywane w oknie nadrzędnym i nie można zmieniać rozmiaru pasków bocznych.

Zamykanie okien i pasków bocznych w Google Workspace

Jeśli używasz usługi HTML do wyświetlania okna lub paska bocznego w Dokumentach Google, Arkuszach lub Formularzach Google, nie możesz zamknąć interfejsu, wywołując window.close. Zamiast tego musisz wywołać funkcję google.script.host.close. Przykład znajdziesz w sekcji Wyświetlanie kodu HTML jako interfejsu użytkownika Google Workspace.

Przenoszenie fokusu przeglądarki w Google Workspace

Aby przełączyć fokus w przeglądarce użytkownika z okna lub paska bocznego z powrotem na edytor Dokumentów Google, Arkuszy lub Formularzy, wywołaj metodę google.script.host.editor.focus. Ta metoda jest szczególnie przydatna w połączeniu z metodami usługi Document Document.setCursor(position) i Document.setSelection(range).

Usługa HTML: komunikacja z funkcjami serwera Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Code.gs

Index.html

Parametry i zwracane wartości

Obsługa powodzenia

Code.gs

Index.html

Moduły obsługi błędów

Code.gs

Index.html

Obiekty użytkownika

Code.gs

Index.html

Formularze

Code.gs

Index.html

Uruchamiający skrypt

Funkcje prywatne

Code.gs

Index.html

Zmiana rozmiaru okien w aplikacjach Google Workspace

Zamykanie okien i pasków bocznych w Google Workspace

Przenoszenie fokusu przeglądarki w Google Workspace

Usługa HTML: komunikacja z funkcjami serwera