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
- Po lewej stronie edytora Apps Script, obok opcji „Biblioteki” kliknij Dodaj bibliotekę .
- W polu „Identyfikator skryptu” wklej identyfikator skryptu z biblioteki.
- Kliknij Wyszukaj.
- Kliknij menu Wersja i wybierz wersję biblioteki, której chcesz użyć.
- 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()
. - 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.
- Po lewej stronie edytora w sekcji „Biblioteki” kliknij nazwę biblioteki.
- 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.
- Utwórz wdrożenie z różnymi wersjami skryptu.
- Przyznaj wszystkim potencjalnym użytkownikom biblioteki dostęp co najmniej na poziomie widoku danych.
- 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:
- Wybierz rozpoznawalną nazwę projektu, ponieważ jest ona używana jako identyfikator domyślny, gdy inni użytkownicy dołączają do Twojej biblioteki.
- 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_()
. - 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 dyrektywaObject.defineProperty()
z wartościąenumerable
ustawioną nafalse
powoduje utworzenie symbolu, którego możesz używać w bibliotece, ale nie jest on dostępny dla użytkowników. 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:
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:
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.