Biblioteki

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

Ostrzeżenie: skrypt korzystający z biblioteki nie działa tak szybko, jak gdyby cały kod był zawarty w pojedynczym projekcie skryptu. Chociaż biblioteki mogą ułatwiać tworzenie i utrzymanie aplikacji, używaj ich oszczędnie w projektach, w których szybkość jest kluczowa. Z tego powodu należy ograniczyć korzystanie z biblioteki w dodatkach.

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 .

Dodawanie biblioteki do projektu skryptu

1. Po lewej stronie edytora Apps Script obok „Libraries” (Biblioteki) kliknij Dodaj bibliotekę .
2. W polu „Identyfikator skryptu” wklej identyfikator skryptu biblioteki.
3. Kliknij Wyszukaj.
   Jeśli pojawi się błąd, sprawdź, czy masz co najmniej dostęp na poziomie widoku 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 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().
   Jeśli użyjesz nazwy identyfikatora, która pasuje do nazwy istniejącej usługi, np. MailApp, lub wcześniej dodanej biblioteki, to ostatnio dodana biblioteka zastąpi istniejącą usługę lub bibliotekę.
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, wykonaj te czynności:

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

Usuwanie biblioteki

Po lewej stronie edytora skryptu obok nazwy biblioteki kliknij Więcej > Usuń > Usuń bibliotekę.

Jeśli biblioteka została usunięta przez autora, musisz ją usunąć z listy dołączonych 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 .

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 zliczać. 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 ustawionym parametrem 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) {
    const scriptProperties = PropertiesService.getScriptProperties();
    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żonego głównego skryptu może korzystać każdy, kto ma do niego dostęp na poziomie edytora.

Wciąż 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 jest widoczny w debugerze w trybie tylko do wyświetlania i w odpowiedniej wersji.