Biblioteki

Biblioteka to projekt skryptu, którego funkcji można używać ponownie w innych skryptach.

Uzyskiwanie dostępu do biblioteki

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

Potrzebujesz identyfikatora skryptu biblioteki, którą chcesz uwzględnić. Gdy masz dostęp do biblioteki, możesz znaleźć identyfikator skryptu na stronie Ustawienia projektu settings.

Dodawanie biblioteki do projektu skryptu

1. Po lewej stronie edytora Apps Script obok „Libraries” (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 „Identyfikator” jest taka, której chcesz używać w tej bibliotece. Jest to nazwa, której twój skrypt używa w odniesieniu do biblioteki. Jeśli na przykład ustawisz wartość Test, możesz wywołać metodę tej biblioteki w ten sposób: Test.libraryMethod().
6. Kliknij Dodaj.

Korzystanie z biblioteki

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

Aby otworzyć dokumentację referencyjną dla załączonej biblioteki:

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

Usuwanie biblioteki

Po lewej stronie edytora skryptu obok nazwy biblioteki kliknij Więcejmore_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żywać i udostępniać projekt skryptu jako biblioteki, wykonaj te czynności.

1. Utwórz wdrożenie z wersjami skryptu.
2. Udostępnij wszystkim potencjalnym użytkownikom biblioteki dostęp co najmniej na poziomie wyświetlania.
3. Przekaż tym użytkownikom identyfikator skryptu, który można znaleźć na stronie Ustawienia projektu settings.

Sprawdzone metody

Oto kilka wskazówek dotyczących pisania biblioteki:

1. Wybierz sensowną nazwę projektu, ponieważ jest ona używana jako domyślny identyfikator, gdy inni użytkownicy korzystają z Twojej biblioteki.
2. Jeśli chcesz, aby jedna lub więcej metod w skrypcie była niewidoczna (ani też nieużywalna) dla użytkowników biblioteki, możesz zakończyć nazwę metody podkreślnikiem. Na przykład: myPrivateMethod_().
3. Użytkownicy biblioteki widzą tylko właściwości globalne, które można wyliczać. Dotyczy to deklaracji funkcji, zmiennych utworzonych poza funkcją za pomocą var oraz właściwości ustawionych w sposób jawny w obiekcie globalnym. Na przykład Object.defineProperty() z wartością enumerable falsetworzy 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 autouzupełniania w edytorze skryptów i automatycznie generowanej dokumentacji, musisz mieć dokumentację wszystkich funkcji w formacie JSDoc. 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

W przypadku bibliotek istnieją 2 typy zasobów: udostępnione i nieudostępnione. Zasób wspólny oznacza, że zarówno biblioteka, jak i skrypt zawierający mają wbudowany dostęp do tego samego wystąpienia zasobu. Na diagramie poniżej pokazano zasob współdzielony na przykładzie właściwości użytkownika:

Zasób, który nie jest udostępniony, oznacza, że zarówno biblioteka, jak i skrypt zawierający mają dostęp tylko do swojej instancji zasobu. Biblioteka może jednak udostępniać dostęp do nieudostępnionych zasobów, jeśli zawiera funkcje, które na nich działają. Oto przykład funkcji, którą należy uwzględnić w bibliotece, aby udostępnić jej właściwości skryptu:

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

Ten diagram pokazuje zasób nieudostępniony na przykładzie właściwości skryptu:

Ta tabela zawiera listę udostępnionych i nieudostępnionych zasobów:

Zasób	Udostępnione*	Nieudostępnione**	Uwagi
Zablokuj			Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, gdy zostanie utworzona w bibliotece.
Właściwości skryptu			Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, gdy zostanie utworzona w bibliotece.
Cache (Pamięć podręczna)			Ta sama instancja jest widoczna dla wszystkich, w tym skryptów, gdy zostanie utworzona w bibliotece.
Reguły			Proste aktywatory utworzone w bibliotece nie są uruchamiane przez skrypt obejmujący.
ScriptApp
UiApp
Właściwości użytkownika
Dziennik i transkrypcja wykonania
Witryny, Arkusze i inne kontenery			Wywołanie funkcji getActive() zwraca kontener skryptu.
MailApp i GmailApp
* Oznacza to, że biblioteka nie ma własnego wystąpienia funkcji lub zasobu, a zamiast tego używa tego, które zostało utworzone przez skrypt, który go wywołał. ** Oznacza to, że biblioteka ma własny egzemplarz zasobu lub funkcji i że wszystkie skrypty, które korzystają z biblioteki, mają dostęp do tego samego egzemplarza.

Testowanie biblioteki

Aby przetestować bibliotekę, użyj wdrożenia głównego. Z wdrożenia głównego może korzystać każdy, kto ma dostęp do skryptu na poziomie edytora.

Debugowanie biblioteki

Gdy używasz debugera w projekcie, który zawiera bibliotekę, możesz przejść do funkcji tej biblioteki. Kod jest widoczny w debugerze w trybie tylko do wyświetlania i w prawidłowej wersji.