Biblioteki

Biblioteka to projekt skryptu, którego funkcji można używać ponownie 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 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 Add a library  (Dodaj bibliotekę).
  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 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 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 > Otwórz na 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ć 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, których należy przestrzegać podczas 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 obiektywie 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 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

W przypadku bibliotek dostępne są 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 zasób udostępniony na przykładzie 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ą 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:

Zasób nieudostępniony

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łasnej instancji funkcji/zasobu i zamiast tego korzysta z instancji utworzonej przez skrypt, który ją 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 na serwerze głównego można korzystać, gdy skrypt ma dostęp na poziomie edytowania.

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.