Biblioteki

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

Uzyskiwanie dostępu do biblioteki

Aby dołączyć do projektu bibliotekę, musisz mieć do niej dostęp co najmniej na poziomie widoku. Jeśli nie jesteś autorem biblioteki, którą chcesz dodać, skontaktuj się z jej autorem i poproś o dostęp.

Potrzebny jest identyfikator skryptu z biblioteki, którą chcesz dołączyć. Gdy masz dostęp do biblioteki, identyfikator skryptu znajdziesz na stronie Ustawienia projektu .

Dodawanie biblioteki do projektu skryptu

  1. Po lewej stronie edytora Apps Script, obok opcji „Biblioteki” kliknij Dodaj bibliotekę .
  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 tej bibliotece chcesz używać domyślnej nazwy „identyfikatora”. Jest to nazwa, której skrypt odwołuje się do biblioteki. Jeśli np. ustawisz ją na 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 samo jak z usługi domyślnej. Jeśli na przykład Test jest identyfikatorem Twojej biblioteki, wpisz Test bezpośrednio z kropką, aby zobaczyć listę metod w bibliotece.

Dokumentację referencyjną biblioteki dołączonej można otworzyć, wykonując 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ę.

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ć projektu skryptu i je udostępniać jako bibliotekę, wykonaj poniższe czynności.

  1. Utwórz wdrożenie z różnymi wersjami skryptu.
  2. Przyznaj wszystkim potencjalnym użytkownikom biblioteki dostęp co najmniej na poziomie widoku danych.
  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 pisania biblioteki:

  1. Wybierz rozpoznawalną nazwę projektu, ponieważ jest ona używana jako identyfikator domyślny, gdy inni użytkownicy dołączają do Twojej biblioteki.
  2. Jeśli chcesz, aby co najmniej jedna metoda skryptu była niewidoczna (ani przydatna) użytkownikom biblioteki, możesz zakończyć jej nazwę podkreśleniem. Na przykład: myPrivateMethod_().
  3. Użytkownicy biblioteki widzą tylko wymienne właściwości globalne. Obejmuje to deklaracje funkcji, zmienne utworzone poza funkcją za pomocą parametru var i właściwości ustawione bezpośrednio w obiekcie globalnym. Na przykład dyrektywa Object.defineProperty() z wartością enumerable ustawioną na false powoduje utworzenie symbolu, 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 korzystali z autouzupełniania w edytorze skryptów i z 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

Wyróżniamy 2 typy zasobów podczas pracy z bibliotekami: udostępnione i nieudostępnione. Współużytkowany zasób oznacza, że zarówno biblioteka, jak i skrypt „zawierający” mają wbudowany dostęp do tej samej instancji zasobu. Poniższy diagram przedstawia udostępniony zasób z użyciem przykładu właściwości użytkownika:

Współużytkowany zasób

Zasób nieudostępniony oznacza, że zarówno biblioteka, jak i skrypt ma wbudowany dostęp tylko do swojej instancji zasobu. Biblioteka może jednak zapewnić dostęp do nieudostępnionych zasobów przez wykonywanie na nich określonych funkcji. Oto przykład funkcji, którą można umieścić w bibliotece, aby udostępnić jej właściwości skryptu:

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

Na diagramie poniżej widać zasób, który nie jest udostępniany, z zastosowaniem właściwości skryptu:

Zasób nieudostępniony

Poniższa tabela zawiera dostępne i nieudostępnione zasoby informacyjne:

Zasób Udostępnione* Nieudostępnione** Notatki
Zablokuj Ta sama instancja jest widoczna dla wszystkich (łącznie ze skryptami) po utworzeniu w bibliotece.
Właściwości skryptu Ta sama instancja jest widoczna dla wszystkich (łącznie ze skryptami) po utworzeniu w bibliotece.
Cache (Pamięć podręczna) Ta sama instancja jest widoczna dla wszystkich (łącznie ze skryptami) po utworzeniu w bibliotece.
Aktywatory Proste aktywatory utworzone w bibliotece nie są aktywowane przez skrypt uwzględniający.
ScriptApp
UiApp
Właściwości użytkownika
Rejestrator i transkrypcja wykonania
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 że wszystkie skrypty korzystające z biblioteki współdzielą ją i mają dostęp do tej samej instancji.

Testowanie biblioteki

Aby przetestować bibliotekę, użyj wdrożenia głównego. Każdy, kto ma uprawnienia do edycji skryptu, może korzystać z wdrożenia głównego.

Debugowanie biblioteki

Gdy używasz debugera w projekcie zawierającym bibliotekę, możesz przejść do funkcji uwzględnionej biblioteki. Kod pojawia się w debugerze w trybie „tylko wyświetlanie” i w odpowiedniej wersji.