Biblioteki

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

Ostrzeżenie: skrypt, który korzysta z biblioteki, nie działa tak szybko, jakby cały kod był zawarty w jednym projekcie skryptu. Chociaż biblioteki mogą ułatwić programowanie i obsługę, używaj ich oszczędnie w projektach, w których kluczowe znaczenie ma szybkość. Z powodu tego problemu korzystanie z biblioteki powinno być ograniczone w przypadku dodatków.

Jak uzyskać dostęp do biblioteki

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

Potrzebujesz identyfikatora skryptu z biblioteki, którą chcesz uwzględnić. Po uzyskaniu dostępu 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 z biblioteki.
3. Kliknij Wyszukaj.
   Jeśli napotkasz błąd, sprawdź, czy masz dostęp do projektu, który chcesz uwzględnić, na poziomie co najmniej widoku.
4. Kliknij menu Wersja i wybierz wersję biblioteki, której chcesz użyć.
5. Sprawdź, czy chcesz użyć domyślnej nazwy „Identyfikatora” z tą biblioteką. Jest to nazwa, której skrypt używa do określania biblioteki. Jeśli np. ustawisz wartość Test, możesz wywołać metodę tej biblioteki w ten sposób: Test.libraryMethod().
   Jeśli używasz identyfikatora, który jest zgodny z nazwą istniejącej usługi, takiej jak MailApp lub wcześniej dodanej biblioteki, wtedy dodana ostatnio biblioteka zastąpi obecną.
6. Kliknij Dodaj.

Korzystanie z biblioteki

Korzystaj z uwzględnionej biblioteki w taki sam sposób jak z usługi domyślnej. Jeśli np. identyfikator biblioteki to Test, wpisz Test bezpośrednio po kropce, aby wyświetlić listę metod w bibliotece.

Aby otworzyć dokumentację załączoną 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 została usunięta przez autora, nadal musisz ją usunąć 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żyć projektu skryptu i udostępnić go jako bibliotekę, wykonaj poniższe czynności.

1. Utwórz wdrożenie z obsługą wersji skryptu.
2. Wszystkim potencjalnym użytkownikom biblioteki musisz przyznać co najmniej dostęp na poziomie widoku.
3. Przekaż tym użytkownikom identyfikator skryptu, który znajdziesz na stronie Ustawienia projektu .

Sprawdzone metody

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

1. Nadaj projektowi rozpoznawalną nazwę, ponieważ jest ona używana jako domyślny identyfikator, gdy Twoja biblioteka jest dołączana do biblioteki.
2. Jeśli chcesz, aby co najmniej jedna metoda skryptu nie była widoczna (i nie była używana) dla użytkowników biblioteki, możesz zakończyć jej nazwę podkreśleniem. Na przykład: myPrivateMethod_().
3. Użytkownicy biblioteki widzą tylko liczne właściwości globalne. Obejmuje to deklaracje funkcji, zmienne utworzone poza funkcją var oraz właściwości bezpośrednio ustawione w obiekcie globalnym. Na przykład zapis Object.defineProperty() z parametrem enumerable ustawionym na false tworzy symbol, którego możesz użyć w swojej bibliotece, ale nie jest on dostępny dla użytkowników.

4. Jeśli chcesz, aby użytkownicy Twojej biblioteki korzystali z autouzupełniania edytora skryptów i automatycznie generowanej dokumentacji, musisz przygotować 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

Istnieją 2 typy zasobów: udostępnione i nieudostępniane. Zasób wspólny oznacza, że zarówno biblioteka, jak i skrypt włączający mają wbudowany dostęp do tej samej instancji zasobu. Na diagramie poniżej widać udostępniony zasób za pomocą przykładowych właściwości użytkownika:

Zasób nieudostępniony oznacza, że zarówno biblioteka, jak i skrypt uwzględniający mają wbudowany dostęp tylko do swojej instancji zasobu. Biblioteka może jednak zapewniać dostęp do nieudostępnionych zasobów, używając wyraźnych funkcji, które na nich działają. Oto przykład funkcji, którą należałoby umieścić w bibliotece, aby udostępnić jej właściwości skryptu:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

Poniższy diagram przedstawia zasób, który nie jest udostępniany, z przykładowymi właściwościami skryptu:

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

Zasób	Udostępnione*	Nieudostępnione**	Uwagi
Zamek			Ta sama instancja jest widoczna dla wszystkich skryptów po utworzeniu w bibliotece.
Właściwości skryptu			Ta sama instancja jest widoczna dla wszystkich skryptów po utworzeniu w bibliotece.
Cache (Pamięć podręczna)			Ta sama instancja jest widoczna dla wszystkich skryptów po utworzeniu w bibliotece.
Aktywatory			Proste aktywatory utworzone w bibliotece nie są wyzwalane przez skrypt uwzględniający.
ScriptApp
UiApp
Właściwości użytkownika
Rejestrator i transkrypcja wykonywania
Witryny, Arkusze i inne kontenery			Wywołanie getActive() zwraca kontener skryptu uwzględniającego.
MailApp i GmailApp
* Oznacza to, że biblioteka nie ma własnej instancji funkcji/zasobu i zamiast tego korzysta z instancji utworzonej przez skrypt, który ją wywołał. ** Oznacza to, że biblioteka ma własną instancję zasobu lub funkcji i wszystkie skrypty, które z niej korzystają, mają do niej dostęp i mają do niej dostęp.

Testowanie biblioteki

Aby przetestować bibliotekę, użyj wdrożenia z nagłówka. Każdy użytkownik, który ma dostęp do skryptu na poziomie edytora, może użyć wdrożenia z nagłówka.

Nadal musisz zapisać co najmniej 1 wersję biblioteki.

Debugowanie biblioteki

Jeśli używasz debugera w projekcie, który zawiera bibliotekę, możesz przejść do funkcji załączonej biblioteki. Kod pojawia się w debugerze w trybie „tylko wyświetlanie” i we właściwej wersji.