Biblioteki

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

Uzyskiwanie dostępu do biblioteki

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

Musisz mieć identyfikator skryptu biblioteki, którą chcesz uwzględnić. 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 sekcji „Biblioteki”, kliknij Dodaj bibliotekę add.
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 „identyfikatora” ma być używana w tej bibliotece. Jest to nazwa, której skrypt używa w odniesieniu do biblioteki. Jeśli jest na przykład ustawiona wartość Test, możesz wywołać metodę biblioteki w ten sposób: Test.libraryMethod().
6. Kliknij Dodaj.

Korzystanie z biblioteki

Korzystaj z biblioteki, tak jak w przypadku usługi domyślnej. Jeśli na przykład identyfikator Twojej biblioteki to Test, wpisz Test, a następnie kropkę, aby wyświetlić listę metod w bibliotece.

Aby otworzyć dokumentację dotyczącą dołączonej 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 skryptu, 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ć skryptu i udostępnić go jako bibliotekę, wykonaj poniższe czynności.

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

Sprawdzone metody

Oto kilka wskazówek, które należy stosować podczas pisania biblioteki:

1. Wybierz rozpoznawalną nazwę projektu, ponieważ jest używana jako identyfikator domyślny, gdy biblioteka jest dołączana przez inne osoby.
2. Jeśli chcesz, aby co najmniej jedna metoda skryptu była niewidoczna dla użytkowników biblioteki (bezużyteczna), możesz zakończyć jej nazwę znakiem podkreślenia. Na przykład: myPrivateMethod_().
3. Użytkownicy z biblioteki widzą tylko wymienne właściwości globalne. Obejmuje to deklaracje funkcji, zmienne utworzone poza funkcją var oraz właściwości jawnie ustawione w obiekcie globalnym. Na przykład Object.defineProperty() z atrybutem enumerable ustawionym na false tworzy symbol, którego możesz użyć w bibliotece, ale nie jest on dostępny dla użytkowników.

4. Jeśli chcesz, aby użytkownicy biblioteki mogli korzystać z automatycznego uzupełniania edytora 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 dostępne są 2 typy zasobów: udostępnione i nieudostępnione. Wspólny zasób oznacza, że zarówno biblioteka, jak i skrypt zawierający kod mają wbudowany dostęp do tego samego wystąpienia zasobu. Poniższy diagram przedstawia udostępniony zasób z użyciem przykładu właściwości użytkownika:

Nieudostępniony zasób oznacza, że zarówno biblioteka, jak i skrypt zawierający wbudowany dostęp mają dostęp tylko do jego instancji. Biblioteka może jednak zapewnić dostęp do zasobów, które nie są współużytkowane, za pomocą jawnych funkcji, które działają na nich. Oto przykład funkcji, którą należy dodać do biblioteki, aby wyświetlić jej właściwości skryptu:

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

Ten diagram pokazuje nieudostępniony zasób z użyciem przykładowej właściwości skryptu:

W tej tabeli znajdziesz informacje o zasobach udostępnionych i nieudostępnionych:

Zasób	Udostępnione*	Nieudostępniony**	Uwagi
Zamek			Ta sama instancja jest widoczna dla wszystkich użytkowników, w tym dla skryptów tworzonych w bibliotece.
Właściwości skryptu			Ta sama instancja jest widoczna dla wszystkich użytkowników, w tym dla skryptów tworzonych w bibliotece.
Cache (Pamięć podręczna)			Ta sama instancja jest widoczna dla wszystkich użytkowników, w tym dla skryptów tworzonych w bibliotece.
Aktywatory			Proste aktywatory utworzone w bibliotece nie są wyzwalane przez dołączenie skryptu.
Skrypt aplikacji
Aplikacja użytkownika
Właściwości użytkownika
Transkrypcja i rejestracja wykonania
Witryny, arkusze kalkulacyjne i inne kontenery			Wywołanie getActive() zwraca kontener skryptu.
MailApp i GmailApp
* Oznacza to, że biblioteka nie ma własnego wystąpienia funkcji/zasobu i używa tej, która została wywołana przez skrypt. ** Oznacza to, że biblioteka ma własne wystąpienie zasobu lub funkcji oraz że wszystkie skrypty używające biblioteki mają dostęp do tej samej instancji i mają do niej dostęp.

Testowanie biblioteki

Aby przetestować bibliotekę, użyj wdrożenia Head. Każdy, kto ma dostęp do skryptu na poziomie edytora, może użyć wdrożenia Head.

Debugowanie biblioteki

Podczas korzystania z debugera w projekcie zawierającym bibliotekę możesz uzyskać dostęp do funkcji tej biblioteki. Kod jest wyświetlany w debugerze w trybie tylko do odczytu i w odpowiedniej wersji.