Biblioteki

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

Ostrzeżenie: 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ść ma kluczowe znaczenie, należy ich używać oszczędnie. Z tego powodu korzystanie z bibliotek w dodatkach powinno być ograniczone.

Uzyskiwanie dostępu do biblioteki

Aby uwzględnić bibliotekę w projekcie, musisz mieć do niej dostęp co najmniej na poziomie wyświetlania. 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, identyfikator skryptu znajdziesz na stronie Ustawienia projektu .

Dodawanie biblioteki do projektu skryptu

1. Po lewej stronie edytora Apps Script obok pozycji „Biblioteki” kliknij Dodaj bibliotekę .
2. W polu „Identyfikator skryptu” wklej identyfikator skryptu biblioteki.
3. Kliknij Wyszukaj.
   Jeśli pojawi się błąd, upewnij się, że masz co najmniej dostęp na poziomie wyświetlania do projektu, który chcesz uwzględnić.
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, możesz wywołać metodę tej biblioteki w ten sposób: Test.libraryMethod().
   Jeśli użyjesz nazwy identyfikatora, która jest zgodna z nazwą istniejącej już usługi, np. MailApp, lub wcześniej dodanej biblioteki, ostatnio dodana biblioteka zastąpi istniejącą usługę lub bibliotekę.
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 Twojej biblioteki, wpisz Test, a następnie od razu kropkę, aby wyświetlić listę metod w bibliotece.

Dokumentację referencyjną dołączonej biblioteki można otworzyć, wykonując 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

Możesz zmienić wersję biblioteki lub zaktualizować 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 co najmniej dostęp na poziomie wyświetlania wszystkim potencjalnym użytkownikom biblioteki.
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. Jeśli chcesz, aby jedna lub więcej metod skryptu nie była widoczna (ani użyteczna) dla użytkowników biblioteki, możesz zakończyć 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 i 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. Jeśli chcesz, aby użytkownicy biblioteki mogli korzystać z funkcji autouzupełniania w edytorze skryptów i automatycznie generowanej dokumentacji, musisz mieć 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:

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:

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, gdy jest tworzona w bibliotece.
Właściwości skryptu			Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, gdy jest tworzona w bibliotece.
Cache (Pamięć podręczna)			Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, gdy jest tworzona 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 funkcji getActive() zwraca kontener, w tym skrypt.
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ą, mają dostęp do tej samej instancji.

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

Gdy używasz debugera w projekcie, który zawiera bibliotekę, możesz przejść do funkcji tej biblioteki. Kod pojawi się w debuggerze w trybie tylko do odczytu i w odpowiedniej wersji.