Biblioteka to projekt skryptu, którego funkcje mogą być ponownie używane w innych skryptach.
Jak uzyskać dostęp do biblioteki
Aby uwzględnić w projekcie bibliotekę, musisz mieć do niej dostęp na poziomie co najmniej widoku. Jeśli nie jesteś autorem biblioteki, którą chcesz zamieścić, skontaktuj się z jej autorem i poproś o dostęp.
Potrzebny będzie identyfikator skryptu biblioteki, którą chcesz dodać. Gdy będziesz mieć dostęp do biblioteki, identyfikator skryptu znajdziesz na stronie Ustawienia projektu
.Dodawanie biblioteki do projektu skryptu
- Po lewej stronie edytora Apps Script obok pozycji „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 przypadku tej biblioteki chcesz używać domyślnej nazwy „Identyfikatora”. Jest to nazwa, której skrypt używa
do oznaczenia biblioteki. Jeśli na przykład ustawisz ją na
Test
, możesz wywołać metodę z tej biblioteki w ten sposób:Test.libraryMethod()
. - Kliknij Dodaj.
Korzystanie z biblioteki
Używaj uwzględnionej biblioteki w taki sam sposób jak usługi domyślnej. Jeśli np. identyfikator biblioteki to Test
, wpisz Test
bezpośrednio po kropce, aby wyświetlić listę metod w bibliotece.
Aby otworzyć dokumentację dotyczącą uwzględnionej biblioteki, wykonaj 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żyć projektu skryptu i udostępnić go jako bibliotekę, wykonaj poniższe czynności.
- Utwórz wdrożenie skryptu z różnymi wersjami.
- Przyznaj wszystkim potencjalnym użytkownikom biblioteki dostęp co najmniej na poziomie widoku.
- Przekaż tym użytkownikom identyfikator skryptu, który znajdziesz na stronie Ustawienia projektu .
Sprawdzone metody
Oto kilka wskazówek, których warto przestrzegać podczas pisania biblioteki:
- Nadaj projektowi rozpoznawalną nazwę, ponieważ jest ona używana jako domyślny identyfikator, gdy Twoja biblioteka jest dołączana przez inne osoby.
- Jeśli chcesz, aby co najmniej 1 metoda skryptu nie była widoczna (ani nie można z niej korzystać) dla użytkowników biblioteki, możesz zakończyć jej nazwę znakiem podkreślenia. Na przykład:
myPrivateMethod_()
. - Użytkownicy biblioteki widzą tylko wyliczane właściwości globalne. Obejmuje to deklaracje funkcji, zmienne utworzone poza funkcją za pomocą polecenia
var
oraz właściwości ustawione bezpośrednio w obiekcie globalnym. Na przykład ciągObject.defineProperty()
z parametremenumerable
ustawionym nafalse
tworzy symbol, którego możesz używać w bibliotece, ale nie jest on dostępny dla użytkowników. Jeśli chcesz, aby użytkownicy Twojej biblioteki mogli korzystać z autouzupełniania edytora skryptów i automatycznie generowanej dokumentacji, musisz zapewnić 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
Podczas pracy z bibliotekami dostępne są 2 typy zasobów: udostępnione i nieudostępniane. Zasób udostępniony oznacza, że zarówno biblioteka, jak i skrypt włączający mają wbudowany dostęp do tej samej instancji zasobu. Poniższy diagram przedstawia udostępniony zasób z użyciem przykładowych właściwości użytkownika:
Jeśli zasób nie jest udostępniany, oznacza to, że zarówno biblioteka, jak i skrypt włączający mają wbudowany dostęp tylko do swojej instancji zasobu. Biblioteka może jednak zapewniać dostęp do nieudostępnionych zasobów, używając wyraźnych funkcji, które na nich działają. Oto przykład funkcji, którą trzeba uwzględnić w bibliotece, aby udostępnić jej właściwości skryptu:
function getLibraryProperty(key) {
return ScriptProperties.getProperty(key);
}
Poniższy diagram przedstawia zasób nieudostępniany na przykładzie właściwości skryptu:
W tej tabeli znajdziesz informacje o zasobach udostępnionych i nieudostępnionych:
Zasób | Udostępnione* | Nieudostępnione** | Uwagi |
---|---|---|---|
Zamek | Ta sama instancja jest widoczna dla wszystkich skryptów po utworzeniu w bibliotece. | ||
Właściwości skryptu | Ta sama instancja jest widoczna dla wszystkich skryptów po utworzeniu w bibliotece. | ||
Cache (Pamięć podręczna) | Ta sama instancja jest widoczna dla wszystkich skryptów po utworzeniu w bibliotece. | ||
Aktywatory | Aktywatory proste utworzone w bibliotece nie są aktywowane przez skrypt dołączający. | ||
Aplikacja Script | |||
Aplikacja UiApp |
|
||
Właściwości użytkownika | |||
Rejestrator i transkrypcja wykonania | |||
Witryny, Arkusze i inne kontenery | Wywołanie getActive() zwraca kontener zawierającego skrypt. |
||
MailApp i GmailApp | |||
* Oznacza to, że biblioteka nie ma własnej instancji funkcji lub zasobu i zamiast tego korzysta z instancji utworzonej przez skrypt, który ją wywołał.
** Oznacza to, że biblioteka ma własne wystąpienie zasobu lub funkcji i wszystkie skrypty korzystające z niej współdzielą i mają dostęp do tej samej instancji. |
Testowanie biblioteki
Aby przetestować bibliotekę, użyj wdrożenia head. Każdy użytkownik, który ma dostęp do skryptu na poziomie edytora, może używać wdrożenia z nagłówkiem.
Debugowanie biblioteki
Jeśli używasz debugera w projekcie, który zawiera bibliotekę, możesz uruchomić funkcję załączonej biblioteki. Kod pojawia się w debugerze w trybie „tylko wyświetlanie” i we właściwej wersji.