Twórz własne widżety w Tulip przy użyciu HTML, CSS i JavaScript
Users on Professional plans and above.
Please allow Outgoing access to Custom Widgets. See Networking requirements for a Tulip Cloud Deployment to learn more.* *.tulip-custom-widgets.com
Elementy, które przeciągasz i upuszczasz do swojej aplikacji, nazywane są widżetami. Mogą to być przyciski, obrazy, pola wprowadzania danych i wszystko inne, co jest dostępne na pasku narzędzi.

Niestandardowe widżety pozwalają na pisanie własnego kodu i tworzenie własnych widżetów, które następnie można przeciągać i upuszczać do aplikacji oraz z nimi wchodzić w interakcję. Ta funkcja pozwala użytkownikom Tulip poszerzać granice możliwości platformy.
Obejrzyj poniższy film, aby zapoznać się z tą funkcją:
Zobacz dostępne niestandardowe widżety w bibliotece Tulip.
Podstawy widżetów niestandardowych
Ekran zarządzania niestandardowymi widżetami znajduje się na stronie ustawień konta. To właśnie tam możesz tworzyć i usuwać widżety. Edytor niestandardowych widżetów pozwala na pisanie kodu widżetu, tworzenie właściwości (props) i zdarzeń (events) oraz podgląd widżetu. Poniżej znajduje się schemat opisujący, czym są właściwości i zdarzenia:

Props: Props to dane współdzielone między niestandardowymi widżetami a aplikacjami Tulip. Props będą widoczne w edytorze aplikacji i pozwolą edytorom aplikacji wybrać, które zmienne, rekordy tabeli lub inne informacje mają być powiązane z danym propem.

Zdarzenia: Zdarzenia to sygnały, które widget może wysyłać do aplikacji. Zdarzenia pozwalają aplikacji reagować za pomocą wyzwalacza i mogą przenosić ze sobą informacje.

Dostęp do niestandardowych widżetów można uzyskać za pomocą rozwijanego menu „Niestandardowe” w edytorze aplikacji.

Utwórz widget
Only users with access to account settings (i.e. Account Owners) or users with specific permission to access the custom widget page can use the custom widget editor.
Ekran edytora widgetów jest podzielony na cztery sekcje. Kod wpisany w sekcji w lewym dolnym rogu pojawi się w sekcji podglądu po kliknięciu w tę sekcję. Wartości właściwości można zmieniać bezpośrednio w sekcji podglądu w celach testowych.

Dostępne są specjalne funkcje do interakcji z właściwościami (props) i zdarzeniami (events).
Pobieranie wartości właściwości
It is not guaranteed that the prop being used by a widget will load before that widget loads, so all props associated with Table record fields, Aggregations, or any other dynamic value should include logic to support cases where they are null at the point the widget is loaded. See this section for details on triggering logic when a prop changes.
//Pobieranie wartości właściwości getValue('My Prop');``//Zapisanie właściwości do zmiennej let myVariable = getValue('My Prop');
Wykonaj czynność po zmianie wartości właściwości
//Wykonaj czynność za każdym razem, gdy zmieni się wartość właściwości getValue('My Prop', (internalVariable) => { doSomething(internalVariable);});
Ustawianie wartości właściwości
//Ustaw wartość właściwości tekstowej na 'hello!'setValue('My Text Prop', 'hello!');
//Ustaw wartość elementu w obiekcie setValue('My Object Prop', { 'Key inside object': 'new value' });```
### Wywołanie zdarzenia
```**Wywołanie zdarzenia** fireEvent('event', *payload*);
//wywołaj zdarzenie bez danych fireEvent('My Event');
//wywołaj zdarzenie z danymi fireEvent('My Event', myVariable);```
Poniższy schemat ilustruje przepływ informacji przez niestandardowy widget w aplikacji. Dane zmiennej wejściowej są zapisywane w właściwości. Zmiana wartości sygnalizuje zdarzenie, w wyniku którego wyzwalacz zapisuje dane do zmiennej wyjściowej.
{height="" width=""}
## Demo tworzenia widżetu
{height="576" width="1024"}
## Importowanie i eksportowanie aplikacji
Zobacz sekcję [Import i eksport](/r230/docs/import-export), aby dowiedzieć się więcej o tej funkcji.
### Eksport
1. W przeglądzie niestandardowych widżetów wybierz **menu z trzema kropkami** obok widżetu, który chcesz wyeksportować.
{height="" width=""}
1. Wybierz opcję **Eksportuj**.
{height="" width="800"}
### Import
1. Na ekranie przeglądu niestandardowych widżetów wybierz **menu z trzema kropkami** u góry.
{height="" width="800"}
1. Wybierz opcję **„Importuj**”.
{height="" width="350"}
1. Znajdź plik widżetu niestandardowego w formacie .json.
## Włącz biblioteki zewnętrzne
Biblioteki zewnętrzne dodatkowo rozszerzają możliwości niestandardowych widżetów. Biblioteki zewnętrzne przejmują ręczne pisanie kodu HTML bezpośrednio w JavaScript. Biblioteki zewnętrzne muszą być włączone dla każdego widżetu, w którym chcesz z nich korzystać.
1. Będąc w widżecie, kliknij **menu z trzema kropkami** w prawym górnym rogu strony.
{height="" width=""}
1. Wybierz opcję **Włącz bibliotekę zewnętrzną**.
{height="" width="250"}
1. Wybierz **rozszerzenie**, które chcesz włączyć.
{height="" width=""}
Oto podstawowy opis działania poszczególnych rozszerzeń:
* **jQuery** – umożliwia bardziej płynny wybór elementów HTML oraz manipulację nimi.
* **D3 –** złoty standard wizualizacji danych; wymaga sporo nauki, ale oferuje ogromną elastyczność.
* **Google Visualization –** świetne narzędzie do, jak sama nazwa wskazuje, wizualizacji.
* **Lodash –** Lodash oferuje mnóstwo narzędzi, które ułatwiają pracę z typami danych w JavaScript.
* **ChartJS –** prawdopodobnie najprostsza biblioteka do tworzenia wykresów, z ogromną ilością zasobów online.
* **Moment –** Moment oferuje mnóstwo narzędzi do pracy z datami i godzinami.
## Wersja środowiska uruchomieniowego
Sposób ładowania niestandardowych widżetów w nowym środowisku uruchomieniowym został zaktualizowany (zobacz [Ulepszenia niestandardowych widżetów](/r230/docs/custom-widget-improvements)). Ta zmiana wpływa na to, kiedy można niezawodnie uzyskać dostęp do właściwości widżetu, takich jak te pobierane za pomocą `getValue()`.
Aby sprawdzić, z której wersji środowiska uruchomieniowego korzysta dany widget:
* Na stronie **listy niestandardowych widżetów** lub w edytorze, jeśli obok nazwy widżetu znajduje się ikona **„Legacy”**, oznacza to, że widżet korzysta ze starego środowiska uruchomieniowego. Jeśli ikony nie ma, widżet korzysta z nowego środowiska uruchomieniowego.
* W panelu bocznym z informacjami o niestandardowym widżecie sprawdź sekcję **Środowisko uruchomieniowe**.
* W **ustawieniach uprawnień** niestandardowego widżetu, jeśli przełącznik **„Środowisko uruchomieniowe niestandardowego widżetu”** jest włączony, oznacza to, że widżet korzysta z nowego środowiska uruchomieniowego.
:::(Info) (NOTE)
By default, newly created Custom Widgets use the old runtime.
:::
Aby zmienić wersję środowiska uruchomieniowego dla niestandardowego widżetu, użyj przełącznika **„Środowisko uruchomieniowe niestandardowego widżetu”** w **ustawieniach uprawnień**.{height="" width=""}
## Przykłady
Poniżej znajduje się kilka niestandardowych widżetów z [biblioteki Tulip](https://tulip.co/library/), które ilustrują opisane powyżej możliwości tej funkcji:
### Prosty widget timera
[Prosty widget timera](https://library.tulip.co/apps/simple-timer-widget)
Przyjazny dla użytkownika widget timera służący do śledzenia czasu, który upłynął podczas wykonywania zadań w aplikacji. Operatorzy mogą uruchamiać, zatrzymywać i resetować timer bezpośrednio z poziomu interfejsu aplikacji, co sprawia, że jest on przydatny do mierzenia czasu trwania zadań lub procesów.
{height="" width=""}
### Widżet wskaźnika promieniowego
[Widżet wskaźnika promieniowego](https://library.tulip.co/apps/radial-gauge-widget)
Ten widget wizualnie przedstawia wartości liczbowe za pomocą konfigurowalnego wskaźnika promieniowego. Idealnie nadaje się do wyświetlania wskaźników, takich jak prędkość maszyny, temperatura lub postęp, w szybkim i łatwo zrozumiałym formacie.
{height="" width=""}
### Widżet osi czasu
[Widżet osi czasu](https://library.tulip.co/apps/timeline-widget)
Wyświetla wydarzenia lub etapy na poziomej osi czasu, pomagając użytkownikom w szybkiej wizualizacji etapów procesu, ukończonych zadań lub danych czasowych.
{height="" width=""}
## Najlepsze praktyki
### 1. Zapobieganie niezamierzonym skutkom ubocznym wynikającym z kodu widżetu uruchamianego podczas ładowania
Tulip uruchamia rzeczywisty kod Twojego widżetu za każdym razem, gdy jest on renderowany — nie tylko w odtwarzaczu, ale także w edytorze widżetów niestandardowych, edytorze aplikacji oraz w podglądzie na żywo stacji. Dzięki temu otrzymujesz dokładny podgląd na żywo swojego widżetu. Każdy kod powodujący skutki uboczne (np. wywołania API, zapisy w tabelach, powiadomienia) na najwyższym poziomie skryptu jest uruchamiany za każdym razem, gdy widget jest renderowany, w tym za każdym razem, gdy widget jest ponownie otwierany w edytorze lub gdy podgląd jest odświeżany.
Wszelkie operacje mające rzeczywisty wpływ na system należy umieścić za jawnym wyzwalaczem (np. naciśnięcie przycisku, wywołanie `fireEvent` w odpowiedzi na działanie użytkownika lub zmiana właściwości Prop), zamiast uruchamiać je automatycznie podczas ładowania.
```// DOBRZE: uruchamia się tylko wtedy, gdy aplikacja wyraźnie o to poprosi getValue('TriggerIncrement', (shouldIncrement) => { if (shouldIncrement) { fetch("https://api.example.com/increment-counter", { method: "POST" }); }});
// ŹLE: uruchamia się za każdym razem, gdy ładuje się widget, w tym w edytorze i podglądziefetch("https://api.example.com/increment-counter", { method: "POST" });```Jeśli widget musi automatycznie ładować dane, należy użyć punktu końcowego tylko do odczytu lub idempotentnego, aby powtarzające się ładowanie nie powodowało niepożądanych skutków.
### 2. Testuj iteracyjnie bez wywoływania rzeczywistych skutków ubocznych
Podczas tworzenia widżetu, który wywołuje produkcyjne API powodujące rzeczywiste skutki uboczne, kieruj żądania do punktu końcowego testowego lub stagingowego do momentu zakończenia iteracji, a następnie przełącz się na punkt końcowy produkcyjny przed opublikowaniem. Zapobiega to powielaniu rekordów, powiadomień lub innym skutkom ubocznym edycji i podglądu widżetu.
W przypadku działań, które muszą zostać wykonane w środowisku produkcyjnym nawet po opublikowaniu, wbuduj potwierdzenie w interfejs użytkownika samego widgetu, zamiast polegać na czasie ładowania. Wymagając widocznej akcji (np. kliknięcia przycisku), osoba przeglądająca widget ma kontrolę nad tym, kiedy efekt nastąpi.
```// Wymaga wyraźnego kliknięcia przed uruchomieniem rzeczywistej akcji,// niezależnie od tego, ile razy sam widget został wyrenderowanydocument.getElementById('submitBtn')?.addEventListener('click', () => { fetch("https://api.example.com/submit-order", { method: "POST" });});
3. Zarządzanie właściwościami — sprawdzaj poprawność wartości właściwości
Upewnij się, że Twój niestandardowy widget niezawodnie obsługuje dane. Props to sposób na przekazywanie informacji do widgetu, ale ich wartości mogą ulec zmianie lub początkowo mogą być niezdefiniowane. Mimo że props mają ustalony typ, początkowo mogą być niezdefiniowane, co może powodować błędy w kodzie niestandardowego widgetu. Stosowanie dobrych praktyk pozwala uniknąć błędów i sprawia, że widget jest bardziej niezawodny.
W poniższym przykładzie jako drugi parametr funkcji getValue użyto funkcji wywołania zwrotnego. Ta funkcja wywołania zwrotnego zostanie uruchomiona za każdym razem, gdy niestandardowy widget otrzyma zaktualizowaną wartość właściwości.
Ponieważ początkowa wartość właściwości może być niezdefiniowana, a później może zostać zaktualizowana, należy upewnić się, że konfiguracja zostanie zastosowana dopiero po otrzymaniu zaktualizowanej wartości. Użycie metody getValue bez funkcji wywołania zwrotnego zwraca wartość właściwości w momencie wykonania kodu.
getValue('config', function(config) { if (config) { applyConfiguration(config); }});
Poniższy przykład nie jest zalecany, ponieważ początkowa wartość właściwości może być niezdefiniowana:const config = getValue('config');applyConfiguration(config);
4. Obsługa zdarzeń — sprawdzanie poprawności danych
Dane zdarzeń mają określony typ. Chociaż wywołanie zdarzenia z nieprawidłowym typem danych nie spowoduje awarii ani nie zatrzyma wykonywania kodu niestandardowego widżetu, dobrą praktyką jest stosowanie własnych mechanizmów zabezpieczających, aby zapewnić, że dane przesyłane w metodzie fireEvent są sprawdzane pod kątem poprawności i mają właściwy typ.
Taka praktyka zapobiega nieoczekiwanym zachowaniom i sprawia, że kod staje się bardziej przewidywalny.
if (data != null && typeof data === 'string') { fireEvent(eventName, data);} else { // Opcjonalnie obsłuż przypadek nieprawidłowych danych.}
5. Użyj funkcji wywołania zwrotnego do asynchronicznego dostępu do właściwości
Gdy wywołujesz metodę `setValue()`, aktualizacja właściwości przebiega asynchronicznie. Oznacza to, że nie następuje ona natychmiast, ponieważ Twój niestandardowy widget komunikuje się z główną aplikacją za pośrednictwem ramki iframe. Żądanie `setValue()` zostaje wysłane, ale Twój kod kontynuuje działanie, nie czekając na wejście zmiany w życie. Jeśli spróbujesz użyć getValue() zaraz po tym, prawdopodobnie otrzymasz starą wartość.
Aby uzyskać najbardziej aktualne dane, zawsze używaj metody `getValue()` z funkcją wywołania zwrotnego. Funkcja wywołania zwrotnego jest wykonywana dopiero po pomyślnej aktualizacji właściwości, co gwarantuje, że pracujesz z najnowszymi informacjami.
Poniższy przykład ilustruje tę najlepszą praktykę:```// DOBRZE: Asynchroniczny dostęp do wartości właściwościconst newConfig = { setting: 'value' };setValue('config', newConfig);
// Funkcja wywołania zwrotnego zostanie uruchomiona po zakończeniu aktualizacji właściwości.getValue('config', function(updatedConfig) { console.log('Właściwość została zaktualizowana. Nowa konfiguracja to:', updatedConfig); // Wykonaj operację na gwarantowanej nowej wartości applyConfiguration(updatedConfig);});```
Poniższy przykład pokazuje, czego należy unikać:```// ŹLE: To może nie działać zgodnie z oczekiwaniami const newConfig = { setting: 'value' }; setValue('config', newConfig);
// Prawdopodobnie zostanie wyświetlona stara wartość, a nie nowa.const currentConfig = getValue('config'); ```
6. Używaj obsługiwanych nagłówków przy wywołaniach API
Podczas wykonywania zewnętrznych wywołań API z niestandardowych widżetów należy zachować ostrożność w zakresie nagłówków HTTP, aby uniknąć problemów związanych z CORS (Cross-Origin Resource Sharing). Niestandardowe widżety działają w środowisku iframe z określonymi ograniczeniami bezpieczeństwa.
Należy używać wyłącznie nagłówków, które są wyraźnie obsługiwane. Ustawienie nieobsługiwanych nagłówków, takich jak Content-Type lub innych niestandardowych nagłówków, może wywołać błędy CORS i uniemożliwić działanie wywołań API.
Poniższy przykład ilustruje tę najlepszą praktykę:// DOBRZE: Proste wywołanie API bez niestandardowych nagłówkówfetch("https://akhatri.bulb.cloud/api/v3/w/1/tables", { headers: { Authorization: "<klucz API>", },}) .then((response) => response.json()) .then((data) => console.log(data)) .catch((error) => console.error("Błąd:", error));
Poniższy przykład pokazuje, czego należy unikać:// ŹLE: Ustawienie nagłówka Content-Type spowoduje problemy z CORSfetch("https://api.example.com/data", { headers: { Authorization: "<klucz API>", "Content-Type": "application/json", // Spowoduje to błędy związane z CORS },})
If you encounter CORS errors, first remove any custom headers you've set (especially Content-Type) and test with minimal headers. The iframe security model restricts which headers can be set from custom widgets.
7. Inicjalizuj widżety w oparciu o środowisko uruchomieniowe
Więcej informacji znajdziesz w sekcji „Wersja środowiska uruchomieniowego ”.
Nowe środowisko uruchomieniowe
W nowym środowisku uruchomieniowym atrybut src zwraca pusty plik HTML szkieletu. Po załadowaniu ten plik szkieletu wysyła komunikat do aplikacji nadrzędnej. Aplikacja nadrzędna wysyła kod niestandardowego widżetu, funkcje użytkowe (takie jak getValue()) oraz początkowe wartości właściwości, które mają zostać wstrzyknięte do ramki iframe.
Z tego powodu zdarzenia DOMContentLoaded i window.onload są wyzwalane po załadowaniu pustej powłoki, zanim kod widżetu zostanie wstrzyknięty. Każda procedura obsługi przypisana do tych zdarzeń jest rejestrowana zbyt późno: zdarzenie już zostało wyzwolone, więc wywołanie zwrotne nigdy nie zostanie wykonane. Kod wewnątrz tych procedur obsługi jest pomijany bez powiadomienia, jak pokazano w poniższym przykładzie:
document.addEventListener('DOMContentLoaded', function() { // Wyzwalane podczas ładowania SHELL, przed wstrzyknięciem kodu użytkownika // Kod użytkownika nie został jeszcze wstrzyknięty! const myProp = getValue('myProp'); // BŁĄD: getValue nie jest zdefiniowane});
W custom widgets nie ma potrzeby używania DOMContentLoaded ani window.onload. Tulip ładuje zasoby w następującej kolejności: biblioteki stron trzecich, kod HTML użytkownika, a następnie JavaScript. Zanim kod JavaScript zostanie wykonany, DOM jest już dostępny. Można uzyskać bezpośredni dostęp do elementów DOM bez czekania na zdarzenie załadowania, jak pokazano w poniższym przykładzie:
// Bezpieczne bezpośrednie wywołanie — w momencie uruchomienia kodu DOM jest już załadowany.const btn = document.getElementById('my-btn');
Stare środowisko uruchomieniowe
W starym środowisku uruchomieniowym atrybut srcDoc wstrzykuje kod niestandardowego widżetu do ramki iframe wraz z funkcjami pomocniczymi, takimi jak getValue(), oraz początkowymi wartościami właściwości. Ponieważ kod widżetu od samego początku stanowi część dokumentu, funkcja getValue() i właściwości są dostępne natychmiast po załadowaniu zawartości ramki iframe.W rezultacie zdarzenia DOMContentLoaded i window.onload działają zgodnie z oczekiwaniami w starym środowisku uruchomieniowym, co pokazuje poniższy przykład:
document.addEventListener('DOMContentLoaded', function() { // Wyzwalane, gdy kod HTML użytkownika jest gotowy // Właściwości są już dostępne const myProp = getValue('myProp'); // Działa natychmiast});
{{snippet.Czy znalazłeś to, czego szukałeś?}}
