Biblioteki

Biblioteka to projekt skryptu, którego funkcje mogą być ponownie używane w innych skryptach.

Jak uzyskać dostęp do biblioteki

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

Potrzebny będzie identyfikator skryptu biblioteki, którą chcesz dodać. Gdy będziesz mieć dostęp do biblioteki, identyfikator skryptu znajdziesz na stronie Ustawienia projektu settings.

Dodawanie biblioteki do projektu skryptu

1. Po lewej stronie edytora Apps Script obok pozycji „Biblioteki” kliknij Dodaj bibliotekę add.
2. W polu „Identyfikator skryptu” wklej identyfikator skryptu z biblioteki.
3. Kliknij Wyszukaj.
4. Kliknij menu Wersja i wybierz wersję biblioteki, której chcesz użyć.
5. Sprawdź, czy w przypadku tej biblioteki chcesz używać domyślnej nazwy „Identyfikatora”. Jest to nazwa, której skrypt używa do oznaczenia biblioteki. Jeśli na przykład ustawisz ją na Test, możesz wywołać metodę z tej biblioteki w ten sposób: Test.libraryMethod().
6. Kliknij Dodaj.

Korzystanie z biblioteki

Używaj uwzględnionej biblioteki w taki sam sposób jak 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ę dotyczącą uwzględnionej biblioteki, wykonaj te czynności:

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

Usuwanie biblioteki

Po lewej stronie edytora skryptów obok nazwy biblioteki kliknij Więcej more_vert > Usuń > Usuń 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 skryptu z różnymi wersjami.
2. Przyznaj wszystkim potencjalnym użytkownikom biblioteki dostęp co najmniej na poziomie widoku.
3. Przekaż tym użytkownikom identyfikator skryptu, który znajdziesz na stronie Ustawienia projektu settings.

Sprawdzone metody

Oto kilka wskazówek, których warto przestrzegać podczas pisania biblioteki:

1. Nadaj projektowi rozpoznawalną nazwę, ponieważ jest ona używana jako domyślny identyfikator, gdy Twoja biblioteka jest dołączana przez inne osoby.
2. Jeśli chcesz, aby co najmniej 1 metoda skryptu nie była widoczna (ani nie można z niej korzystać) dla użytkowników biblioteki, możesz zakończyć jej nazwę znakiem podkreślenia. Na przykład: myPrivateMethod_().
3. Użytkownicy biblioteki widzą tylko wyliczane właściwości globalne. Obejmuje to deklaracje funkcji, zmienne utworzone poza funkcją za pomocą polecenia var oraz właściwości ustawione bezpośrednio w obiekcie globalnym. Na przykład ciąg Object.defineProperty() z parametrem enumerable ustawionym 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 Twojej biblioteki mogli korzystać z autouzupełniania edytora skryptów i automatycznie generowanej dokumentacji, musisz zapewnić 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 dostępne są 2 typy zasobów: udostępnione i nieudostępniane. Zasób udostępniony oznacza, że zarówno biblioteka, jak i skrypt włączający mają wbudowany dostęp do tej samej instancji zasobu. Poniższy diagram przedstawia udostępniony zasób z użyciem przykładowych właściwości użytkownika:

Jeśli zasób nie jest udostępniany, oznacza to, że zarówno biblioteka, jak i skrypt włączają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ą trzeba uwzględnić w bibliotece, aby udostępnić jej właściwości skryptu:

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

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

W tej tabeli znajdziesz informacje o zasobach 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			Aktywatory proste utworzone w bibliotece nie są aktywowane przez skrypt dołączający.
Aplikacja Script
Aplikacja UiApp
Właściwości użytkownika
Rejestrator i transkrypcja wykonania
Witryny, Arkusze i inne kontenery			Wywołanie getActive() zwraca kontener zawierającego skrypt.
MailApp i GmailApp
* Oznacza to, że biblioteka nie ma własnej instancji funkcji lub zasobu i zamiast tego korzysta z instancji utworzonej przez skrypt, który ją wywołał. ** Oznacza to, że biblioteka ma własne wystąpienie zasobu lub funkcji i wszystkie skrypty korzystające z niej współdzielą i mają dostęp do tej samej instancji.

Testowanie biblioteki

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

Debugowanie biblioteki

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