Pomoc:Importowanie CSS i JS

Ta strona pomocy wyjaśnia zalecane sposoby dodawania dodatkowego CSS i JavaScript na Twojej wiki.

Importowanie skryptów JavaScript

ImportJS

ImportJS prosty mechanizm umożliwiający ładowanie artykułów zawierających skrypty — zarówno lokalnych, jak i tych z Dev Wiki — bezpośrednio na Twojej wiki.

Wszystkie lokalne pliki oraz importy z Dev Wiki muszą znajdować się w przestrzeni nazw MediaWiki — inaczej nie będą działały. Jednakże dodając je do ImportJS nie dodajemy prefiksu „MediaWiki:”, ponieważ jest on przyjmowany automatycznie.

Każda linia w konfiguracji ImportJS jest interpretowana jako próba załadowania pliku. Niepoprawne nazwy są ignorowane — pozwala to między innymi na dodawanie komentarzy, poprzedzając linię np. // lub #. Przykład: 

// lokalny plik: "MediaWiki:Kategorie.js"
Kategorie.js

// skrypt z Dev Wiki: "MediaWiki:UploadMultipleFiles.js"
dev:UploadMultipleFiles.js
Dialog-information
Przegląd JavaScript
Funkcja ImportJS omija potrzebę przeglądu JavaScript. Pozwala to na natychmiastowe dodawanie i usuwanie importów JavaScript na wiki!

importArticles

Główny artykuł: /techniczne#importArticles

Zbliżonym narzędziem do ImportJS jest globalna funkcja importArticles() dostępna z poziomu MediaWiki:Common.js lub MediaWiki:Fandomdesktop.js. Użycie tej funkcji wymaga jednak przejrzenia kodu przez pracownika Fandomu zanim zmiany w kodzie wejdą w życie.

Oba narzędzia pozwalają ładować kilka skryptów naraz, zmniejszając liczbę zapytań i minimalizując kod wynikowy. Dzięki temu wiki korzystające z wielu dodatkowych skryptów mogą ładować się szybciej.

Kolejność skryptów

Na Fandomie skrypty uruchamiają się w ustalonej kolejności. Najpierw wczytywane są podstawowe pliki wiki, a dopiero potem importowane skrypty. Kolejność wygląda tak:

  1. Common.js
  2. Fandomdesktop.js
  3. Importy dodane przez Common.js
  4. Importy dodane przez Fandomdesktop.js
  5. ImportJS

Oznacza to, że kod zawarty w Common.js i Fandomdesktop.js zawsze zostanie wykonany zanim wczytane zostaną jakiekolwiek dodatkowe pliki. — wiele skryptów z Dev Wiki wykorzystuje tą właściwość do konfiguracji.

Ponadto dla każdej grupy importów (czyli każdego wywołania importArticles(), mw.loader.using() lub bloku ImportJS) kolejność wysyłania zapytań jest zachowana — nie gwarantuje to jednak kolejności wykonania. Pliki ładują się asynchronicznie i wykonują natychmiast po pobraniu.

W obrębie jednej grupy importów można jednak przewidzieć kolejność wykonania:

  • W importArticles() i metodach mw.loader pliki wykonują się alfabetycznie.
  • W ImportJS wykonywane są po kolei — od góry strony do dołu.

Jeżeli Twój kod wymaga, aby dany skrypt był już załadowany, nie polegaj na kolejności wykonywania. Zamiast tego używaj callbacków lub obietnic (Promises) zwracanych przez importArticles() lub mw.loader.using(). Dzięki temu masz pewność, że kod uruchomi się dopiero po załadowaniu wymaganych skryptów.

Szerzej zostało to omówione w poradniku poświęconym technicznym aspektom importowania skryptów.

Importowanie styli CSS

@import

Użycie @import pozwala na importowanie plików CSS znajdujących się na wiki i innych stronach z użyciem poniższej składni: 

@import url("sciezka_do_importowanego_pliku.css");

Pamiętaj jednak, że:

  • Funkcja @import musi znajdować się na samej górze MediaWiki:Common.css (lub MediaWiki:Fandomdesktop.css, jeśli Common.css jest pusty).
  • Każda strona, którą importujesz, musi kończyć się na .css.

Najczęściej stosowaną formą jest import przez dedykowany skrypt load.php. Przykład importu pliku Local.css: 

@import url("/load.php?articles=MediaWiki:Local.css&only=styles&mode=articles");

Jeśli importujesz wiele plików CSS, najlepiej przekazać je w jednej funkcji @import rozdzielając je znakiem |: 

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

W przypadku wiki nieanglojęzycznych (w tym większości polskich wiki) load.php wymaga podania kodu językowego (np. /pl/) na początku adresu URL: 

@import url("/pl/load.php?articles=MediaWiki:Local.css&only=styles&mode=articles");

Więcej o sposobach importowania arkuszy CSS z użyciem @import przeczytasz w poradniku poświęconym technicznym aspektom importowania skryptów.

Dialog-information
Blokowanie renderowania

Użycie @import wstrzymuje wyświetlanie strony — przeglądarka najpierw czeka, aż załadują się style CSS, a dopiero potem pokazuje zawartość strony. Pozwala to uniknąć „migotania” wyglądu, jednakże ma to swoją cenę: strona może ładować się wyraźnie wolniej.

Problem ten jest szczególnie odczuwalny, gdy używanych jest wiele instrukcji @import — pliki CSS importowane w ten sposób są pobierane jeden po drugim, a nie równocześnie. Dobrą praktyką uznaje się umieszczanie wszystkich stylów w jednym głównym pliku CSS. Jeśli import jest konieczny, najlepiej ograniczyć się do jednego pliku zamiast dzielić style na wiele mniejszych i importować je osobno.

importArticles

Funkcja importArticles może być również używana do importowania stylów CSS. Należy pamiętać, że dodanie arkusza w ten sposób będzie wymagało przejrzenia i zatwierdzenia zmodyfikowanego pliku JS.

Aby zaimportować lokalny arkusz CSS za pomocą importArticles, poniższy kod musi zostać dodany do MediaWiki:Common.js lub MediaWiki:Fandomdesktop.js. 

importArticles({
    type: "style",
    article: "MediaWiki:Local.css"
});

W przeciwieństwie do @import, import poprzez importArticles może odbywać się w tle, co może skutkować szybszym czasem ładowania, ale może powodować niepożądany efekt migotania.

Którą metodę wybrać?

Wybór metody zależy od przypadku użycia:

  • jeśli stosujesz style, które drastycznie wpływają na wygląd każdej strony i chcesz uniknąć migotania, użyj metody @import.
  • Jeśli style nie są ważne, muszą być ładowane warunkowo lub wpływają na części strony, które nie zawsze są widoczne natychmiast; użyj importArticles.

Zobacz również

Dalsze wsparcie

Szukasz dalszego wsparcia lub masz pytanie? Sprawdź poniższe linki, aby dowiedzieć się więcej.