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 .

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.
  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, 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ę.

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 udostępniony

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:

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ł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.

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.