Biblioteki

Biblioteka to projekt skryptu, którego funkcje można ponownie wykorzystać w innych skryptach.

Skrypt, który korzysta z biblioteki, nie działa tak szybko, jak gdyby cały kod był zawarty w jednym projekcie skryptu. Biblioteki mogą ułatwiać programowanie i konserwację, ale w projektach, w których szybkość jest kluczowa, należy ich używać oszczędnie. Z tego powodu korzystanie z bibliotek w dodatkach do Google Workspace powinno być ograniczone.

Uzyskiwanie dostępu do biblioteki

Aby uwzględnić bibliotekę w projekcie, musisz mieć do niej dostęp co najmniej na poziomie widoku. Jeśli nie jesteś autorem biblioteki, którą chcesz uwzględnić, skontaktuj się z nim i poproś o dostęp.

Potrzebujesz identyfikatora skryptu biblioteki, którą chcesz uwzględnić. Gdy uzyskasz dostęp do biblioteki, znajdź identyfikator skryptu na stronie Ustawienia projektu .

Dodawanie biblioteki do projektu skryptu

  1. Po lewej stronie edytora skryptów Apps Script obok pozycji „Biblioteki” kliknij Dodaj bibliotekę .
  2. W polu „Identyfikator skryptu” wklej identyfikator skryptu biblioteki.
  3. Kliknij Wyszukaj.
  4. Kliknij menu Wersja i wybierz wersję biblioteki, której chcesz użyć.
  5. Sprawdź, czy domyślna nazwa „Identyfikator” jest tą, której chcesz używać w tej bibliotece. Jest to nazwa, której skrypt używa do odwoływania się do biblioteki. Jeśli na przykład ustawisz wartość Test, wywołaj metodę tej biblioteki w ten sposób: Test.libraryMethod.
  6. Kliknij Dodaj.

Korzystanie z biblioteki

Korzystaj z biblioteki w taki sam sposób jak z domyślnej usługi. Jeśli na przykład Test jest identyfikatorem biblioteki, wpisz Test, a następnie od razu kropkę, aby wyświetlić listę metod w bibliotece.

Aby otworzyć dokumentację referencyjną dołączonej biblioteki, wykonaj te czynności:

Po lewej stronie edytora skryptów obok nazwy biblioteki kliknij Więcej > Otwórz w nowej karcie.

Usuwanie biblioteki

Po lewej stronie edytora skryptów, obok nazwy biblioteki, kliknij Więcej > Usuń > Usuń bibliotekę.

Jeśli biblioteka zostanie usunięta przez autora, nadal musisz usunąć ją z listy uwzględnionych bibliotek.

Aktualizowanie biblioteki

Zmień wersję biblioteki lub zaktualizuj jej identyfikator.

  1. Po lewej stronie edytora w sekcji „Biblioteki” kliknij nazwę biblioteki.
  2. Wprowadź zmiany i kliknij Zapisz.

Tworzenie i udostępnianie biblioteki

Aby używać projektu skryptu jako biblioteki i udostępniać go, wykonaj te czynności:

  1. Utwórz wdrożenie skryptu z określoną wersją.
  2. Udostępnij wszystkim potencjalnym użytkownikom biblioteki co najmniej dostęp na poziomie wyświetlania.
  3. Podaj tym użytkownikom identyfikator skryptu, który znajdziesz na stronie Ustawienia projektu .

Sprawdzone metody

Oto kilka wskazówek, których należy przestrzegać podczas pisania biblioteki:

  1. Wybierz dla projektu znaczącą nazwę, ponieważ będzie ona używana jako domyślny identyfikator, gdy Twoja biblioteka zostanie uwzględniona przez inne osoby.
  2. Aby jedna lub więcej metod skryptu nie było widocznych (ani użytecznych) dla użytkowników biblioteki, zakończ nazwę metody podkreśleniem. Na przykład: myPrivateMethod_.
  3. Użytkownicy biblioteki widzą tylko właściwości globalne, które można wyliczyć. Obejmuje to deklaracje funkcji, zmienne utworzone poza funkcją za pomocą var oraz właściwości jawnie ustawione w obiekcie globalnym. Na przykład Object.defineProperty() z ustawioną wartością enumerable na false tworzy symbol, którego możesz używać w bibliotece, ale nie jest on dostępny dla użytkowników.

  4. Aby użytkownicy biblioteki mogli korzystać z autouzupełniania w edytorze skryptów i automatycznie generowanej dokumentacji, dołącz dokumentację w stylu JSDoc dla wszystkich funkcji. Oto przykład:

    /**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Określanie zakresu zasobów

Podczas pracy z bibliotekami możesz korzystać z 2 rodzajów zasobów: udostępnionych i nieudostępnionych. Wspólny zasób oznacza, że zarówno biblioteka, jak i skrypt, który ją zawiera, mają wbudowany dostęp do tej samej instancji zasobu. Poniższy diagram przedstawia zasób udostępniony na przykładzie właściwości użytkownika:

Udostępniony zasób

Zasób nieudostępniony oznacza, że zarówno biblioteka, jak i skrypt, który ją zawiera, mają wbudowany dostęp tylko do swojej instancji zasobu. Biblioteka może jednak udostępniać swoje nieudostępnione zasoby, udostępniając funkcje, które na nich działają. Oto przykład funkcji, którą możesz umieścić w bibliotece, aby udostępnić jej właściwości skryptu:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

Poniższy diagram przedstawia zasób nieudostępniony na przykładzie właściwości skryptu:

Przykład zasobu, który nie jest udostępniony

W tej tabeli znajdziesz listę udostępnionych i nieudostępnionych zasobów:

Zasób Udostępniono* Nieudostępnione** Uwagi
Zablokuj Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, jeśli została utworzona w bibliotece.
Właściwości skryptu Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, jeśli została utworzona w bibliotece.
Cache (Pamięć podręczna) Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, jeśli została utworzona w bibliotece.
Aktywatory Proste aktywatory utworzone w bibliotece nie są wywoływane przez skrypt zawierający.
ScriptApp
UiApp
Właściwości użytkownika
Rejestrator i zapis wykonywania
Witryny, Arkusze i inne kontenery Wywołanie getActive zwraca kontener z zawartością, w tym skryptem.
MailApp i GmailApp
* Oznacza to, że biblioteka nie ma własnej instancji funkcji lub zasobu i zamiast tego używa instancji utworzonej przez skrypt, który ją wywołał.
** Oznacza to, że biblioteka ma własną instancję zasobu lub funkcji, a wszystkie skrypty, które jej używają, współdzielą tę samą instancję i mają do niej dostęp.

Testowanie biblioteki

Aby przetestować bibliotekę, użyj wdrożenia head. Każda osoba, która ma dostęp do skryptu na poziomie edytora, może używać wdrożenia głównego.

Musisz mieć zapisaną co najmniej 1 wersję biblioteki.

Debugowanie biblioteki

Podczas debugowania skryptu, który zawiera bibliotekę, nie możesz przejść do kodu biblioteki ani ustawić w nim punktów przerwania. Jeśli w trybie debugowania spróbujesz przejść do funkcji biblioteki, debuger pominie tę funkcję i przejdzie do następnego wiersza w skrypcie wywołującym.

Użycie HEAD (tryb deweloperski) w przypadku wersji biblioteki nie umożliwia przechodzenia do biblioteki ani osiągania w niej punktów przerwania.

Aby debugować kod biblioteki, użyj jednej z tych metod:

  • Debugowanie z poziomu projektu biblioteki: otwórz projekt skryptu biblioteki w edytorze skryptów Apps Script. Aby przetestować funkcje biblioteki z określonymi argumentami, utwórz w projekcie biblioteki tymczasową funkcję „test”, która wywołuje funkcje biblioteki, a następnie uruchom tę funkcję testową w trybie debugowania.
  • Logowanie: używaj znaku console.log() w funkcjach biblioteki, aby przekazywać informacje do dzienników wykonania. Gdy biblioteka jest wywoływana przez inny skrypt, te dzienniki pojawiają się w dziennikach wykonywania skryptu wywołującego.