Pomoc:Importowanie CSS i JS/techniczne

Ta strona pomocy omawia bardziej techniczne sposoby dodawania CSS i JavaScript na Twojej wiki.

importArticles

Globalna funkcja JavaScript importArticles() udostępnia wspólny interfejs do wgrywania na wiki artykułów, które zawierają skrypty i style. Najczęściej używa się jej do warunkowego ładowania CSS/JS.

Funkcjonalnie jest podobna do starszych metod importScriptPage i importStylesheetPage, ale ma kilka zalet:

• pozwala na import artykułów z innych wiki,
• potrafi łączyć wiele stron w jeden pakiet,
• minifikuje kod zmniejszając zarówno rozmiar pliku, jak i ruch sieciowy wywołany jego pobraniem,
• wysyła wszystko w ramach jednego żądania,

Dzięki temu wiki korzystająca z wielu dodatkowych plików JS/CSS może ładować się znacznie szybciej.

Użycie

Funkcja importArticles() korzysta z tzw. modułów do wgrania artykułów. Moduły są obiektami JavaScript z własnościami w formie klucz/wartość. Poniższe właściwości są wymagane dla każdego modułu:

• type – oznacza typ artykułów jaki zostanie zawarty w tym module. Wspierane typy to:
  • style – zawierające CSS (np: "MediaWiki:Common.css")
  • script – zawierające JavaScript (np: "MediaWiki:Common.js")
• articles – artykuły, które mają zostać zaimportowane.

Aby poprawnie wskazać artykuły do zaimportowania, stosuje się prostą składnię — bardzo podobną do linków interwiki:

(Prefiks:NazwaWiki:){Artykuł}

• parametr Artykuł to nazwa strony do zaimportowania. Wskazane artykuły muszą znajdować się w przestrzeni nazw MediaWiki.
• parametry Prefiks oraz NazwaWiki są opcjonalne i zostały omówione szerzej w sekcjach poniżej.

Do importArticles() można przekazać dowolną ilość modułów, jednakże wszystkie artykuły w danym module muszą być tego samego typu.

Pamięć podręczna

Linki generowane przez importArticles() (oraz przez zaawansowane techniki opisane poniżej) są zapisywane w pamięci podręcznej na maksymalnie 10 minut. Pamiętaj, że przy każdej zmianie należy założyć, że wszyscy użytkownicy na danej wiki otrzymają zaktualizowane wersje plików js i css dodanych przez importArticles() dopiero po 10 minutach.

Lokalne artykuły

Aby zaimportować artykuł znajdujący się na tej samej wiki, co wywołanie importArticles wiki, wystarczy podać jego nazwę tak samo, jak w zwykłym linku.

Choć linki do lokalnych artykułów nie wymagają prefiksu czy nazwy wiki, wiele wiki stosuje prefiks local (lub w skrócie "l"). Przykładowo, jeśli chcesz zaimportować artykuł MediaWiki:Common.js, zadziała dowolna z poniższych wartości:

MediaWiki:Common.js
l:MediaWiki:Common.js
local:MediaWiki:Common.js

Artykuły z innych wiki

Funkcja importArticles pozwala również importować artykuły z innych wiki Fandomu. Jednakże, strony z zewnętrznych wiki wymagają prefixu — zbliżonego do linków interwiki — oraz nazwy społeczności, aby ResourceLoader wiedział, skąd wczytać plik.

Fandom umożliwia wyszukiwanie wiki na podstawie:

• nazwy bazy danych, za pomocą prefiksu external (lub "remote" albo "w" w skrócie)
• adresu URL wiki, za pomocą prefiksu url (lub w skrócie "u").

Przykładowo, jeśli chcesz zaimportować artykuł Highlight/code.css z FANDOM Open Source Library, zadziała dowolna z poniższych wartości:

w:dev:Highlight/code.css
remote:dev:Highlight/code.css
external:dev:Highlight/code.css
u:dev:Highlight/code.css
url:dev:Highlight/code.css
u:dev.wikia.com:Highlight/code.css
url:dev.wikia.com:Highlight/code.css

Ta składnia działa też dla wiki w innych językach. Na przykład, jeśli chcesz dodać artykuł MediaWiki:Common.js z włoskiej One Piece Wiki:

u:it.onepiece:MediaWiki:Common.js
url:it.onepiece:MediaWiki:Common.js
url:it.onepiece.wikia.com:MediaWiki:Common.js

Uwaga nt. wiki ze zmienioną domeną lub myślnikami

Z reguły łatwiej odwołać się do zasobów na innych wiki przez ich URL niż przez bazę danych, ponieważ nazwy baz czasami się nie zgadzają.

Jednakże w przypadku niektórych wiki — szczególnie, gdy mają subdomeny z myślnikami lub były przenoszone — ResourceLoader może nie wykryć poprawnie wiki, zwracając błąd „missing”.

W takich przypadkach możesz spróbować:

• usunąć myślniki (np. „genshin-impact” → „genshinimpact”),
• użyć starej domeny wiki,
• użyć nazwy bazy danych (dostępnej np. przez wartość mw.config.values.wgDBName).

Jeśli import nadal nie działa, skontaktuj się z pomocą techniczną Fandomu.

Ważne: Nie używaj surowych adresów URL w importArticles().

Zaawansowane użycie

Za kulisami, funkcja importArticles() wykonuje cztery kluczowe zadania:

1. Koduje nazwy artykułów za pomocą mw.util.wikiUrlencode.
2. Włącza wersje testowe skryptów, jeśli użytkownik ma aktywny tryb testowy (poprzez dodanie prefixu test:).
3. Rejestruje artykuł jako moduł ResourceLoadera (jeśli nie był wcześniej zarejestrowany), co pozwala później ładować go przez metody mw.loader.
4. Wyświetlenie informacji użytkownikowi w przypadku wystąpienia błędu.

Metoda ta opakowuje funkcję mw.loader.using, która faktycznie realizuje większość pracy:

1. Tworzy poprawny adres URL dla ResourceLoadera.
2. Sprawdza, czy moduł nie został już wcześniej załadowany lub jest w trakcie ładowania.
3. Weryfikuje poprawność nazw artykułów.
4. Grupuje wiele importów w jedno zapytanie oraz normalizuje je, by poprawić cache.
5. Tworzy element <script> z wygenerowanym URL-em i dodaje go do nagłówka strony.
6. Tworzy i zwraca obietnicę (Promise), która zostanie rozwiązana, gdy skrypt się pobierze i załaduje.

Rejestrowanie artykułów

Jedną z kluczowych ról importArticles() jest rejestrowanie artykułów jako modułów w ResourceLoaderze. Dzięki temu możesz ich później używać w innych metodach RL np. mw.loader.using().

Możesz użyć mw.loader.using() bezpośrednio, ale nie będzie ona działaćdla artykułów, które:

• nie zostały zaimportowane przez importArticles(),
• ani nie zostały ręcznie zarejestrowane poprzez mw.loader.register().

importArticles a ImportJS

W przeciwieństwie do importArticles() MediaWiki:ImportJS nie rejestruje artykułów jako modułów — zarejestrowane jest jedynie samo żądanie ext.fandom.ImportJs. Oznacza to, jeśli ten sam skrypt jest ładowany przez ImportJS oraz w importArticles(), zostanie onpobrany i uruchomiony podwójnie.

Ładowanie kodu w oparciu o importowany artykuł

Metoda importArticles() zwraca **Promise**, który zostaje rozwiązany, gdy wszystkie wskazane moduły zostaną pobrane, zinterpretowane oraz wykonane. Możesz to wykorzystać, by uruchamiać kod, który zależy od importowanych modułów.

Po rozwiązaniu obietnicy otrzymujesz jeden argument — funkcję require. Funkcja ta zwraca wartości eksportowane przez moduł (zwykle obiekt zawierający metody i ustawienia). Jeśli moduł nie eksportuje niczego i nie udostępnia funkcji globalnie, nie będzie można go wywołać przez require.

Skrypty społeczności Fandomu najczęściej nie korzystają z eksportów modułów — zamiast tego swoje funkcje umieszczają globalnie, np. w window.dev.

importArticles({ type: "script", articles: "u:dev:MediaWiki:Script.js"})
.then(function(require){
    // Ten kod wykona się dopiero po załadowaniu i uruchomieniu Script.js
    
    // Przykład pobrania eksportów modułu
    var module = require("u:dev:MediaWiki:Script.js");
});

Oznacza to, że po pierwszym wywołaniu importArticles() – jeśli Twój kod zależy od danego modułu – możesz ponownie wywołać importArticles() lub mw.loader.using() bez obaw, że załaduje się on drugi raz.

Przykłady

importArticles({
    type: "script",
    articles: [
        "MediaWiki:MyCustomJavaScript.js",
        "external:dev:MediaWiki:External_include.js"
    ]
});

importArticles({
    type: "style",
    articles: [
        "MediaWiki:Common.css",
        "external:starwars:MediaWiki:External_include.css"
    ]
});

importArticles({
    type: "script",
    articles: [
        "MediaWiki:MyCustomJavaScript.js",
        "external:dev:MediaWiki:External_include.js"
    ]
}, {
    type: "style",
    article: "MediaWiki:Common.css"
});

importArticles({
    articles: [
        "MediaWiki:MyCustomJavaScript.js",
        "MediaWiki:MyCustomStylesheet.css",
        "u:dev:MediaWiki:External_include.js",
        "u:dev:MediaWiki:External_include.css"
    ]
});

importArticle({
    type: "style",
    article: "MediaWiki:Common.css"
});

Ręczne importowanie CSS i JS

Możliwe jest także ręczne wczytywanie skryptów i arkuszy stylów — bez użycia importArticles(). Ta metoda jest przydatna w sytuacjach nietypowych lub gdy potrzebujesz pełnej kontroli nad sposobem i warunkami ładowania plików.

Poniżej omówione są dwa sposoby:

• korzystanie z mw.loader (zalecane w większości sytuacji),
• użycie index.php z ResourceLoaderem,
• bezpośrednie ładowanie CSS/JS z URL (rzadko zalecane).

load.php

load.php jest punktem końcowym (ang. endpoint) ResourceLoadera, który umożliwia połączenie wielu artykułów w jedno żądanie. Jest częścią systemu . Korzystanie z tego URL jest zalecane, ponieważ zmniejsza zużycie transferu danych dzięki łączeniu i minimalizacji skryptów. Zwrócony kod automatycznie implementuje wszystkie artykuły podane jako moduły.

Funkcje importArticles() i mw.loader.using() tworzą żądania korzystając właśnie z tego punktu końcowego.

Chociaż można użyć wielu parametrów w URL, poniższe są najczęściej przydatne:

Na koniec powinien powstać adres URL, który wygląda mniej więcej tak:

/load.php?mode=articles&articles=MediaWiki:Jeden.css|MediaWiki:Dwa.css&only=styles

Jeśli zasób jest na innej wiki Fandom, użyj pełnego URL lub składni u::

https://dev.fandom.com/load.php?mode=articles&articles=MediaWiki:Jeden.css|MediaWiki:Dwa.css&only=styles

/load.php?mode=articles&articles=u:dev:MediaWiki:Jeden.css|u:dev:MediaWiki:Dwa.css&only=styles

index.php

Alternatywną metodą jest użycie skryptu index.php, która pozwala pobrać pojedynczy, niezmieniony, nie-przetworzony i nie-minifikowany skrypt lub arkusz stylów. Może to być przydatne:

• do debugowania pozwalając na łatwiejsze odnalezienie arkusza w miejscach jak karta „Sieć” narzędzi deweloperskich przeglądarek,
• jeśli chcesz obejść ResourceLoader (np. przy implementacji skryptów korzystającej z niewspieranej, nowoczesnej składni ES6).

index.php nie pozwala pobierać modułów – tylko strony. Dodatkowo linki interwiki i składnia u nie działają, gdy używasz action=raw. Jeśli chcesz pobrać skrypty lub style z innych społeczności Fandomu, potrzebny jest pełny adres URL. W przypadku JavaScript, pobieranie skryptów z zewnętrznych stron może stanowić zagrożenie bezpieczeństwa i zaleca się import tylko z witryn Fandomu.

Choć w URL można użyć wielu parametrów, poniższe są najczęściej używane:

Po użyciu powyższych parametrów, URL może wyglądać tak:

/index.php?action=raw&title=MediaWiki:Script.js&ctype=text/javascript

Implementacja

Po przygotowaniu URL, możesz użyć go na kilka sposobów:

mw.loader.load(modules, type)

• Jeśli type to "text/javascript" lub parametr jest pominięty, funkcja tworzy element <script> z atrybutem src ustawionym na podany URL, a następnie dodaje go do <head> dokumentu.
• Jeśli type to "text/css", tworzy element <link> z atrybutem rel="stylesheet" i href ustawionym na URL, a następnie dodaje go do <head>.
• Jeśli podasz nazwy modułów zamiast URL (string nie zaczyna się od "http://" ani "/"), funkcja działa jak mw.loader.using().
• Argument modules nie może być tablicą przy użyciu URL. Dla wielu modułów należy użyć jednej paczki w load.php lub wywołać osobno dla każdego URL przy index.php.
• Przy użyciu only w URL load.php, wywołanie tej funkcji wielokrotnie z tym samym URL spowoduje ponowne wykonanie skryptu, ponieważ moduł nie będzie samorejestrujący się i nie „pamięta” wcześniejszego załadowania.

@import

Zobacz metodę @import.

Ręczne wstrzyknięcie

Jeśli nie chcesz używać bibliotek, możesz samodzielnie dodać poniższy skrypt

// Skrypt JavaScript
var script = document.createElement("script");
script.src = url;
script.addEventListener("load", function() {
    // Kod tutaj wykona się po załadowaniu skryptu
});
document.head.append(script);

// Arkusz CSS
var link = document.createElement("link");
link.rel = "stylesheet";
link.href = url;
link.addEventListener("load", function() {
    // Kod tutaj wykona się po załadowaniu arkusza
});
document.head.append(link);

Starsze metody ładowania

Fandom udostępnia również starsze metody ładowania oparte o globalny kontekst — korzystanie z nich jest niezalecane.

importScript(nazwa)

Tworzy względny URL do artykułu nazwa i wywołuje mw.loader.load, co dodaje element <script> do <head>:

<script src="/index.php?title=''nazwa''&action=raw&ctype=text/javascript"></script>

importScriptURI(url)

Wywołuje mw.loader.load z podanym url, co dodaje element <script>:

<script src="''url''"></script>

importScriptPage(nazwa, wiki)

Tworzy pełny URL do skryptu nazwa pochodzącego z wiki, a następnie wywołuje mw.loader.load.

Jeśli wiki jest puste, działa jak importScript:

<script src="http://''wiki''.fandom.com/index.php?title=''nazwa''&action=raw&ctype=text/javascript"></script>

importStylesheet(title)

Tworzy względny URL do artykułu nazwa, a następnie tworzy i dodaje element <link> do <head>:

<link rel="stylesheet" type="text/css" href="/index.php?title=''nazwa''&action=raw&ctype=text/css">

importStylesheetURI(url, media)

Tworzy element <link> z podanym url, i opcjonalnym media, a następnie dodaje go do <head>:

<link rel="stylesheet" type="text/css" href="''url''" media="''media''">

importStylesheetPage(title, wiki)

Tworzy pełny URL do skryptu nazwa pochodzącego z wiki, a następnie dodaje <link>.

Jeśli wiki jest puste, działa jak importStylesheet:

<link rel="stylesheet" type="text/css" href="http://''wiki''.fandom.com/index.php?title=''nazwa''&action=raw&ctype=text/css">

appendCSS(css)

Tworzy element <style> z bezpośrednio wprowadzonymi regułami css i dodaje go do <head>:

<style type="text/css">''css''</style>

Zobacz również

• CSS i JS społeczności – jak tworzyć modyfikacje dla Twojej społeczności.
• Zaawansowane CSS i JS – więcej informacji dla chcących się zagłębić w świat edytowania CSS i JS.
• Dostosowywanie CSS i JS – strona zbierająca wszystkie szczegóły na temat CSS i JS.