Własne kafelki

Gdy wbudowane typy kafelków nie pasują do wizualizacji, jakiej chcesz, Saiku dostarcza własne renderery, które idą dalej, pozostając bezpiecznymi. Wszystkie są deklaratywne — opisujesz wynik danymi, nie kodem.

Każdy renderer pojawia się jako osobna pozycja w menu + Dodaj kafelek (pod „Custom”). Wybranie jednego wrzuca kafelek już związany z tym rendererem; potem konfigurujesz go w edytorze ⚙ kafelka dokładnie jak każdy inny — wybierz kostkę, zbuduj zapytanie i podaj konfigurację renderera.

Notatka

Własne renderery włącza się per wdrożenie. Jeśli menu „+ Dodaj kafelek” pokazuje „No custom renderers installed”, Twoje Saiku ich nie zarejestrowało — zapytaj administratora.

Kafelek listy rankingowej

Renderer Lista rankingowa rysuje kartę „movers”, jakiej chce większość dashboardów operacyjnych: numerowany ciąg wierszy, każdy z etykietą i wartością, gdzie wartość jest kolorowana wedle tego, czy poszła w górę, czy w dół.

Zwiąż go z zapytaniem zwracającym kolumnę etykiety i kolumnę wartości, a potem skonfiguruj:

Pole	Znaczenie
Podtytuł	Wyciszona linia pod tytułem kafelka („Product department · MoM”)
Kolumna etykiety	Puste = wywnioskowane (patrz niżej)
Kolumna wartości	Puste = wywnioskowane (patrz niżej)
Format wartości	Opcjonalny wzorzec wyświetlania — $c1 → $27.4M. Puste zachowuje formatowanie kostki
Wiersze	Ile pokazać (domyślnie 6)
Kolejność	Zachowaj kolejność zapytania, najwyższe najpierw albo najniższe najpierw
Kolor wartości	Wedle znaku (w górę zielony / w dół czerwony) albo zwykły
Pokaż numery rang	Wiodące 1, 2, 3…

Zostawione puste kolumny są wnioskowane strukturalnie: wartość to pierwsza kolumna miary w wyniku, a etykieta to reszta. Trzyma się to nawet wtedy, gdy captiony wymiaru wyglądają jak liczby — decyl przepisujących (10.0), rok, numer sklepu — a to dokładnie tam zgadywanie z tekstu wyszłoby na odwrót.

Format wartości przyjmuje ten sam słownik wzorców, co kafelek KPI i oś wartości ECharts: $cN waluta kompaktowa, $N waluta zwykła, N% procent, N cyfry po przecinku. Warto ustawić przy każdej mierze walutowej — karta top-N surowych wierszy $27,432,535.99 źle się skanuje wzrokiem.

Sortowanie dzieje się przed limitem wierszy, więc „najwyższe najpierw, 3 wiersze” to naprawdę top trzy całego wyniku, a nie trzy pierwsze przestawione. Kolory i typografia idą za motywem Appki — bez CSS-a.

Wskazówka

Tę kartę budowało się kiedyś, stylując kafelek Tabela własnym CSS-em. Nie rób tego — kafelek listy rankingowej przemotywuje się razem z Appką, nie zderza się z innymi tabelami na stronie i jest edytowalny przez tego, kto odziedziczy Twoją Appkę.

Kafelek option ECharts

Renderer ECharts option pozwala ułożyć wykres, pisząc wprost obiekt option ECharts. To wyjście awaryjne dla kształtów, których wbudowany kafelek Wykres nie wystawia — nietypowych układów osi, wariantów rose, nietypowych visual map i tak dalej.

Uwaga

Najpierw sprawdź Kafelek Wykres. Radar, punktowy, treemap, sunburst, heatmapa i wodospad to wszystko wbudowane typy wykresów, a podwójne osie, serie combo, linie trendu, Top N, formatowanie liczb i linie referencyjne to wszystko wbudowane opcje. Sięgnięcie po ręcznie pisany option, by dostać jedno z nich, kosztuje Cię dziedziczenie motywu, formatowanie warunkowe i — przede wszystkim — możliwość, by ten, kto odziedziczy Twoją Appkę, zmienił to bez edytowania JSON-a.

Ponieważ Twój option trafia do żywej biblioteki wykresów, jest walidowany wobec bezpiecznego podzbioru, zanim w ogóle się wyrenderuje. Reguły, egzekwowane na każdej głębokości obiektu:

• Żadnych wartości funkcyjnych. ECharts woła rzeczy w rodzaju formatter jako funkcje z żywymi danymi i DOM-em, więc każda funkcja gdziekolwiek w option jest odrzucana. (Czysty JSON nie wyrazi funkcji; kontrola strzeże przed żywym obiektem, który by ją przemycił.)

• Żadnych zdalnych URL-i. http(s): spoza originu, względne wobec protokołu //host, cele url(...) wskazujące poza origin oraz nie-obrazowe URI data: są odrzucane — to wektory wyprowadzania danych / SSRF. Zostają referencje z tego samego originu i względne oraz obrazy data: wyłącznie w PNG, JPEG, GIF albo WebP.

  Zauważ, że SVG nie jest na tej liście, nawet jako obraz data:. SVG może nieść skrypt, więc jest wykluczony celowo — użyj eksportu rastrowego, jeśli potrzebujesz ikony inline.

• Tylko klucze z allowlisty. Akceptowane są wyłącznie wyselekcjonowane klucze najwyższego poziomu (title, grid, xAxis, yAxis, series, legend, tooltip, color, backgroundColor, visualMap, radar, polar i garść innych) oraz wyselekcjonowany zestaw pól per series. Cokolwiek poza allowlistą jest odrzucane, a nie po cichu pomijane — walidator zawodzi bezpiecznie.

Jeśli Twój option łamie którąś regułę, kafelek pokazuje błąd walidacji zamiast się renderować, żebyś mógł to poprawić. Zapytanie, które wiążesz, dostarcza dane (kategorie + serie), które option rysuje.

Najpierw motyw, potem option

Twój option nakłada się na umotywowaną linię bazową Appki. Co powie, to wygrywa; czego nie powie — kolor tytułu, kolor etykiet osi, linie siatki, paleta serii — jest dziedziczone z motywu.

Pisz tylko te części, które są naprawdę szyte na miarę. Option pełen zaszytych na sztywno hexów pierwszego dnia wygląda identycznie, a przestaje pasować do Appki, gdy tylko ktoś zmieni preset.

Notatka

Komponenty są dekorowane, nigdy wprowadzane. W ECharts wspomnienie komponentu go włącza — więc linia bazowa stylizuje legendę, tooltip czy oś tylko wtedy, gdy Twój option już je deklaruje. Wykresowi kołowemu nie wyrastają osie dlatego, że motyw ma o nich zdanie.

Formatowanie osi wartości

Skoro funkcje są odrzucane, nie sformatujesz osi zwykłym sposobem ECharts — axisLabel.formatter musiałby być funkcją. Zamiast tego edytor ma pole Format osi wartości, przyjmujące ten sam wzorzec, którego używa kafelek KPI:

Wzorzec	Renderuje
$c0	$149K — waluta kompaktowa
$c1	$48.2K
$2	$99.50
1%	15.6%
0	1,234

Stosuje się do każdej osi type: "value" i jest kompilowany w czasie renderowania, więc nigdy nie podajesz kodu, a reguła braku funkcji pozostaje absolutna. Osie kategorii są zostawione w spokoju — szablon tekstowy w rodzaju "W{value}" w Twoim option nadal tam działa, bo to jest deklaratywne.

Kafelek grafu

Renderer Graf zamienia rekordy zapytania w graf węzłów i krawędzi — drzewo własności, mapę relacji, przepływ między encjami. Zamiast obiektu option dajesz mu mapowanie kolumn: które kolumny Twojego wyniku są końcami, id, etykietami i wagami.

Pole	Wymagane	Znaczenie
sourceCol	tak	Kolumna z końcem źródłowym każdego wiersza
targetCol	tak	Kolumna z końcem docelowym każdego wiersza
idCol	tak	Kolumna z kanonicznym id węzła (żeby etykieta przyczepiła się do właściwego węzła). Dla zwykłej listy krawędzi ustaw ją równą sourceCol
labelCol	nie	Kolumna z przyjazną nazwą wyświetlaną dla węzła idCol
valueCol	nie	Kolumna liczbowa przenoszona na każdą krawędź i sumowana w wagę węzła
layout	nie	force (domyślnie) albo circular

Każdy wiersz staje się jedną skierowaną krawędzią źródło → cel; węzły są zbierane z każdego końca i deduplikowane po id. Wiersze bez końca są pomijane. Gdy ustawisz valueCol, jego wartość waży zarówno krawędź, jak i jej węzły końcowe — rozmiar węzła skaluje się względem wag w tym grafie, więc najcięższy węzeł zawsze sięga góry pasma rozmiarów, w jakichkolwiek jednostkach liczy miara. Waga zerowa albo ujemna to węzeł najlżejszy, a nie nieważony.

Konfigurowanie własnego kafelka

Przebieg jest dla wszystkich taki sam:

1. + Dodaj kafelek → Ranked list (albo ECharts option, albo Graph).
2. Otwórz edytor ⚙ kafelka.
3. Zwiąż zapytanie — wybierz kostkę i zbuduj zapytanie, którego wynik zasila kafelek.
4. Podaj konfigurację — pola listy rankingowej, obiekt option ECharts albo mapowanie kolumn grafu.
5. Zapisz. Niepoprawna konfiguracja wychodzi jako błąd inline, a nie zepsuty render.

Powiązane

• Budowanie stron i kafelków — wbudowane typy kafelków i jak działa wiązanie.
• Kafelek Wykres — zajrzyj tu, zanim napiszesz option ECharts ręcznie.
• Pluginy — zaawansowany, instalowany przez administratora kafelek z JS w piaskownicy do w pełni własnych widgetów.