From de5c456ebded0e038adbf23db34cc290c8829180 Mon Sep 17 00:00:00 2001 From: Florian Merz Date: Thu, 11 Feb 2021 14:49:24 +0100 Subject: unslug pl: move --- files/pl/conflicting/mozilla/add-ons/index.html | 369 ++++++++++++++++++++++++ 1 file changed, 369 insertions(+) create mode 100644 files/pl/conflicting/mozilla/add-ons/index.html (limited to 'files/pl/conflicting/mozilla/add-ons') diff --git a/files/pl/conflicting/mozilla/add-ons/index.html b/files/pl/conflicting/mozilla/add-ons/index.html new file mode 100644 index 0000000000..fc05606e60 --- /dev/null +++ b/files/pl/conflicting/mozilla/add-ons/index.html @@ -0,0 +1,369 @@ +--- +title: Tworzymy rozszerzenie +slug: Tworzymy_rozszerzenie +tags: + - Dodatki + - Rozszerzenia +translation_of: Mozilla/Add-ons +translation_of_original: Building_an_Extension +--- +

Wprowadzenie

+ +

Ten przewodnik przeprowadzi Cię przez kilka kroków potrzebnych do stworzenia bardzo prostego rozszerzenia, które doda do Firefoksa panel na pasku statusu z tekstem "Witaj Świecie!"

+ +
Uwaga! Ten artykuł dotyczy tworzenia rozszerzenia dla Firefoksa 1.5 i późniejszych. Istnieją także przewodniki na temat budowy rozszerzeń dla starszych wersji Firefoksa.
+ +

Przygotowanie środowiska programowania

+ +

Rozszerzenia są spakowane i rozpowszechniane w plikach ZIP lub paczkach z rozszerzeniem pliku xpi (wymawiane jak “zippy”). Układ zawartości wewnątrz pliku XPI może wyglądać następująco:

+ +
extension.xpi:
+              /install.rdf
+              /components/*
+              /components/cmdline.js
+              /defaults/
+              /defaults/preferences/*.js
+              /plugins/*
+              /chrome.manifest
+              /chrome/icons/default/*
+              /chrome/
+              /chrome/content/
+
+
+ +

Z tego powodu najłatwiej będzie układać pliki źródłowe w podobny sposób, chyba że chcesz napisać coś w stylu pliku Makefile lub skryptu powłoki, aby spakować wszystkie swoje pliki. Nawet, jeśli jesteś gotów to zrobić, testowanie rozszerzenia będzie znacznie łatwiejsze, jeśli ułożysz swoje pliki w powyższy sposób, ze względu na sposób pracy systemu Dodatków Firefoksa 1.5.

+ +

Zaczynajmy. Utwórz gdzieś na swoim dysku folder dla Twojego rozszerzenia, np. C:\extensions\my_extension\ lub ~/extensions/my_extension/. (Uwaga: Używaj tylko małych liter) Wewnątrz tego folderu tworzymy kolejny o nazwie chrome, następnie wewnątrz chrome tworzymy folder content. (W systemach Uniksowych można zazwyczaj stworzyć wszystkie trzy foldery za pomocą polecenia mkdir -p chrome/content wydanego w głównym katalogu rozszerzenia.)

+ +

Wewnątrz głównego folderu rozszerzenia, obok folderu chrome, tworzymy dwa puste pliki tekstowe: chrome.manifest oraz install.rdf.

+ +

Przykładowo:

+ +
#!/bin/sh
+h=$HOME/moExt
+mkdir -p $h/my_extension/chrome/content
+touch $h/my_extension/chrome.manifest $h/my_extension/install.rdf
+
+ +

Więcej wskazówek na temat tego jak przygotowywać środowisko programistyczne można znaleźć w artykule Przygotowanie środowiska programowania rozszerzenia.

+ +

Tworzenie manifestu instalacji

+ +

Otwieramy plik install.rdf, który utworzyliśmy w głównym katalogu rozszerzenia i wpisujemy tam:

+ +
<?xml version="1.0"?>
+
+<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+     xmlns:em="http://www.mozilla.org/2004/em-rdf#">
+
+  <Description about="urn:mozilla:install-manifest">
+    <em:id>sample@foo.net</em:id>
+    <em:version>1.0</em:version>
+    <em:type>2</em:type>
+
+    <!-- Target Application this extension can install into,
+         with minimum and maximum supported versions. -->
+    <em:targetApplication>
+      <Description>
+        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
+        <em:minVersion>1.0+</em:minVersion>
+        <em:maxVersion>1.5.0.*</em:maxVersion>
+      </Description>
+    </em:targetApplication>
+
+    <!-- Front End MetaData -->
+    <em:name>Sample!</em:name>
+    <em:description>A test extension</em:description>
+    <em:creator>Your Name Here</em:creator>
+    <em:homepageURL>http://www.foo.com/</em:homepageURL>
+  </Description>
+</RDF>
+
+ + + +

Zobacz Manifesty Instalacji, gdzie znajdziesz kompletną listę wymaganych i opcjonalnych właściwości.

+ +

Zapisz plik.

+ +

Rozszerzanie przeglądarki przy użyciu języka XUL

+ +

Interfejs użytkownika w Firefoksie napisany jest w XUL i JavaScript. XUL jest językiem zgodnym z językiem XML, pozwala on na tworzenie elementów interfejsu użytkownika takich jak: przyciski, menu, paski narzędzi itp. Akcje użytkownika są powiązane z funkcjami przy użyciu języka JavaScript.

+ +

Aby rozszerzyć możliwości przeglądarki, zmieniamy interfejs użytkownika poprzez dodanie lub modyfikację kontrolek. Możemy dodać elementy interfejsu poprzez wstawienie nowych elementów DOM XUL do okna przeglądarki i zmodyfikowanie ich poprzez dodanie skryptów i uchwytów zdarzeń.

+ +

Przeglądarka jest zaimplementowana w pliku XUL o nazwie browser.xul ($FIREFOX_INSTALL_DIR/chrome/browser.jar zawiera content/browser/browser.xul). W browser.xul znajdziemy pasek stanu, który wygląda mniej więcej tak:

+ +
<statusbar id="status-bar">
+ ... <statusbarpanel>s ...
+</statusbar>
+
+ +

<statusbar id="status-bar"> jest punktem wiązania dla nakładki XUL.

+ +
Nakładki XUL
+ +

Nakładki XUL są metodą na dołączanie w locie elementów interfejsu XUL do gotowych dokumentów XUL. Nakładka XUL to plik o rozszerzeniu .xul określający fragmenty w języku XUL, które mają zostać dołączone do określonego punktu wiązania w dokumencie głównym. Fragmenty te mogą określać elementy interfejsu, które mają zostać dodane, usunięte lub zmodyfikowane.

+ +

Przykładowy dokument nakładki XUL {{ Ref(1) }}

+ +
<?xml version="1.0"?>
+<overlay id="sample"
+         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
+ <statusbar id="status-bar">
+  <statusbarpanel id="my-panel" label="Witaj świecie!"/>
+ </statusbar>
+</overlay>
+
+ +

Element <statusbar> nazwany status-bar określa "punkt wiązania" w oknie przeglądarki, do którego chcemy się podpiąć.

+ +

Element podrzędny ("dziecko") <statusbarpanel> jest nowym elementem interfejsu, który chcemy wstawić wewnątrz elementu będącego punktem wiązania.

+ +

Skopiuj przykładowy kod podany powyżej i zapisz go w pliku o nazwie sample.xul wewnątrz katalogu chrome/content, który wcześniej utworzyłeś.

+ +

Aby dowiedzieć się więcej na temat wiązania elementów interfejsu i modyfikowania interfejsu użytkownika przy zastosowaniu Nakładek, czytaj dalej.

+ +

Chrome URI

+ +

Pliki XUL są częścią "Pakietów Chrome" - paczek komponentów interfejsu użytkownika, które są ładowane przy użyciu URI chrome://. Zamiast ładować przeglądarkę z dysku używając URI file:// (ponieważ położenie Firefoksa w systemie może się zmieniać w zależności od platformy i systemu), twórcy Firefoksa wymyślili w jaki sposób tworzyć URI dla zawartości plików XUL, o których wie zainstalowana aplikacja.

+ +

URI dla okna przeglądarki to: chrome://browser/content/browser.xul Spróbuj wpisać to URI do paska adresu w Firefoksie!

+ +

Chrome URI składa się z kilku części:

+ + + +

Tak więc, chrome://foo/skin/bar.png ładuje plik bar.png z sekcji skin rozszerzenia foo.

+ +

Kiedy ładujesz zawartość używając Chrome URI, Firefox używa rejestru Chrome do przetłumaczenia tych identyfikatorów URI na właściwe pliki źródłowe na dysku (lub w archiwach JAR).

+ +

Tworzenie Manifestu Chrome

+ +

Więcej informacji o manifeście Chrome i obsługiwanych przez niego właściwościach znajdziesz w dokumentacji Manifestu Chrome.

+ +

Otwórz plik o nazwie chrome.manifest, który stworzyłeś obok katalogu chrome w głównym katalogu rozszerzenia.

+ +

Dodaj poniższy kod:

+ +
content     sample    chrome/content/
+
+ +

(Nie zapomnij o ukośnikach "/"! Bez nich pakiet nie zostanie zarejestrowany.)

+ +

Dane w pliku określają:

+ +
    +
  1. typ zawartości przechowywanej w pakiecie chrome,
    2. +
  2. nazwę pakietu chrome (używaj wyłącznie małych liter w nazwie rozszerzenia ("sample"), ponieważ Firefoks/Thunderbird nie obsługuje mieszanych wielkości liter w wersji 2 oraz wcześniejszych - {{ Bug(132183) }}),
    3. +
  3. położenie plików pakietu chrome.
    4. +
+ +

Zatem powyższa linia informuje, że dla pakietu sample możemy znaleźć pliki zawierające dane typu content (zawartość) w lokalizacji chrome/content, podanej względem położenia pliku chrome.manifest.

+ +

Zauważ, że pliki zawartości, lokalizacji i motywu muszą być zawarte wewnątrz folderów content, locale oraz skin wewnątrz twojego podkatalogu chrome.

+ +

Zapisz plik. Kiedy załadujesz Firefoksa z twoim rozszerzeniem (dalej w tym przewodniku), ten plik umożliwi zarejestrowanie Twojego pakietu chrome.

+ +

Rejestrowanie nakładki

+ +

Chcemy, aby Firefox łączył Twoją nakładkę z oknem przeglądarki, zawsze gdy jest ono wyświetlane. Dodaj tą linię do twojego pliku chrome.manifest :

+ +
overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul
+
+ +

Mówi ona Firefoksowi, żeby połączył sample.xul i browser.xul, gdy browser.xul jest ładowany.

+ +

Test

+ +

Po pierwsze, musimy powiedzieć przeglądarce Firefox o Twoim rozszerzeniu. W starych, złych czasach Firefoksa 1.0 oznaczało to spakowanie rozszerzenia jako XPI i zainstalowanie go przez interfejs użytkownika, co było naprawdę nieprzyjemne. Teraz jest to znacznie prostsze.

+ +
    +
  1. Otwórz swój folder profilu,
    2. +
  2. Otwórz folder extensions (stwórz go, jeśli nie istnieje),
    3. +
  3. Stwórz nowy plik tekstowy i umieść w nim ścieżkę do folderu twojego rozszerzenia, np. C:\extensions\myExtension\ lub ~/extensions/myExtension. Zapisz plik z identyfikatorem twojego rozszerzenia jako jego nazwą, np. sample@foo.net.
    4. +
+ +

(Nie zapomnij o ukośniku "/"! Bez niego rozszerzenie nie zostanie zarejestrowane.)

+ +

Teraz jesteś gotowy do testowania swojego rozszerzenia!

+ +

Uruchom Firefoksa. Firefox wykryje plik z odnośnikiem do katalogu Twojego rozszerzenia i zainstaluje rozszerzenie. Kiedy pojawi się okno przeglądarki, powinieneś zobaczyć tekst "Witaj świecie!" z prawej strony paska statusu.

+ +

Możesz teraz wrócić i zmienić plik .xul, uruchomić ponownie Firefoksa - zmiany powinny się pojawić.

+ +<center> +

grafika:Helloworld_status_bar.PNG

+ +

grafika:Helloworld_extensions_wnd.PNG

+</center> + +

Pakowanie

+ +

Teraz, gdy twoje rozszerzenie działa, możesz je spakować w celu umożliwienia dystrybucji i instalacji.

+ +

Spakuj jako archiwum zip zawartość katalogu rozszerzenia (nie sam folder rozszerzenia) i zmień rozszerzenie pliku zip na rozszerzenie .xpi. W Windows XP możesz to łatwo zrobić przez zaznaczenie wszystkich plików i podfolderów w katalogu rozszerzenia, kliknięcie prawym przyciskiem myszy i wybranie "Wyślij do -> Folder skompresowany (zip)". Plik .zip zostanie utworzony. Teraz tylko zmień nazwę i gotowe!

+ +

Teraz wgraj plik .xpi na serwer i upewnij się, że jest obsługiwany jako application/x-xpinstall. Możesz podlinkować plik i umożliwić ludziom ściąganie i instalowanie Twojego rozszerzenia w Firefoksie.

+ +

Zastosowanie addons.mozilla.org

+ +

Mozilla Update jest witryną służącą do rozpowszechniania rozszerzeń, gdzie możesz umieścić swoje rozszerzenie za darmo. Rozszerzenie będzie przechowywane w sieci mirrorów Mozilli gwarantując możliwość ściągnięcia go, nawet jeżeli będzie ono bardzo popularne. Witryna Mozilli umożliwia także użytkownikom łatwiejszą instalację i automatyczne uaktualnienia do nowych wersji po ich udostępnieniu przez Ciebie. W dodatku Mozilla Update pozwala użytkownikom komentować i dostarczać opinie na temat twojego rozszerzenia. Rozpowszechnianie swoich rozszerzeń za pomocą Mozilla Update jest bardzo zalecane!

+ +

Odwiedź http://addons.mozilla.org/developers/, załóż konto i zacznij rozpowszechnianie swoich rozszerzeń!

+ +

Uwaga: Twoje rozszerzenie może być szybciej udostępnione i częściej ściągane, jeśli masz jego dobry opis i ekranowe zrzuty rozszerzenia w akcji.

+ +

Rejestrowanie rozszerzeń w rejestrze Windows

+ +

W systemie Windows informacja o rozszerzeniach może być dodana do rejestru, wtedy rozszerzenia będą automatycznie instalowane następnym razem, gdy aplikacja (Firefox/Thunderbird) uruchamia się. To umożliwia instalatorom innych aplikacji łatwe integrowanie się z Firefoksem i innymi aplikacjami Mozilli poprzez rozszerzenia. Zobacz Dodawanie rozszerzeń poprzez rejestr systemu Windows w celu uzyskania dalszych informacji.

+ +

Więcej o nakładkach XUL

+ +

Poza dołączaniem kontrolek interfejsu użytkownika do punktów łączenia możesz użyć fragmentów XUL w Nakładkach do:

+ + + +
<statusbarpanel position="1" .../>
+
+<statusbarpanel insertbefore="other-id" .../>
+
+<statusbarpanel insertafter="other-id" .../>
+
+ +

Tworzenie nowego komponentu interfejsu użytkownika

+ +

Możesz tworzyć swoje własne okna i okienka dialogowe jako oddzielne pliki .xul, dostarczać nową funkcjonalność poprzez implementację akcji w plikach .js, używać metod DOM do manipulowania kontrolkami interfejsu użytkownika. Możesz używać stylów w plikach .css do dołączania obrazków, ustawiania kolorów itp.

+ +

Zobacz dokumentację XUL, znajdziesz w niej więcej zasobów dla programistów XUL.

+ +

Pliki domyślne

+ +

Domyślne pliki, których używasz do stworzenia profilu użytkownika powinny być umieszczone w katalogu defaults/ w głównym folderze hierarchii katalogów Twojego rozszerzenia. Pliki domyślnych preferencji .js powinny być przechowywane w defaults/preferences/ - kiedy umieścisz je tutaj, będą one automatycznie ładowane przez system preferencji Firefoksa podczas startu tak, że będziesz miał do nich dostęp używając Preferencji API.

+ +

Przykładowy plik domyślny preferencji:

+ +
pref("extensions.sample.username", "Joe"); //tekst
+pref("extensions.sample.sort", 2); //liczba
+pref("extensions.sample.showAdvanced", true); //wartość logiczna
+
+ +

Komponenty XPCOM

+ +

Firefox obsługuje komponenty XPCOM w rozszerzeniach. Możesz łatwo stworzyć swoje własne komponenty w JavaScript lub C++ (używając SDK Gecko).

+ +

Wszystkie pliki .js lub .dll umieszczamy w katalogu components/ - zostaną one automatycznie zarejestrowane przy pierwszym uruchomieniu Firefoksa po instalacji rozszerzenia.

+ +

Aby uzyskać więcej informacji, zobacz Jak stworzyć komponent XPCOM w Javascripcie, Jak stworzyć binarny komponent XPCOM używając Visual Studio oraz Tworzenie komponentów XPCOM.

+ +

Linia poleceń aplikacji

+ +

Jednym z możliwych zastosowań komponentów XPCOM wykonanych specjalnie do tego celu jest dodanie agenta linii poleceń do Firefoksa lub Thunderbirda. Możesz użyć tej techniki do uruchamiania swojego rozszerzenia jako aplikacji:

+ +
 firefox.exe -myapp
+
+ +

Zobacz Chrome:Linia poleceń i dyskusję na forum, aby poznać szczegóły.

+ +

Lokalizacja

+ +

Dla obsługi więcej niż jednego języka, powinieneś rozdzielić teksty napisów od reszty zawartości Twojego rozszerzenia używając do tego encji i plików własności. Dużo łatwiej zrobić to podczas tworzenia rozszerzenia niż wracać do tego później.

+ +

Informacje o lokalizacji dla Twojego rozszerzenia są przechowywane w katalogu locale. Na przykład, dla dodania lokalizacji do naszego przykładowego rozszerzenia, stwórz katalog "locale" w chrome (gdzie ulokowany jest katalog "content") i dodaj następującą linię do pliku chrome.manifest:

+ +
locale sample sampleLocale chrome/locale/
+
+ +

Dla stworzenia lokalizowalnej wartości atrybutu w XUL wstaw te wartości do pliku .dtd, który powinien być umieszczony w katalogu locale i wyglądać tak:

+ +
<!ENTITY  button.label     "Click Me!">
+<!ENTITY  button.accesskey "C">
+
+ +

I następnie dołącz go na początku Twojego dokumentu XUL (ale pod "<?xml version"1.0"?>"), tak jak poniżej:

+ +
<!DOCTYPE window SYSTEM "chrome://sample/locale/filename.dtd">
+
+ +

gdzie: window jest wartością atrybutu localName, głównego elementu dokumentu XUL, a wartość własności SYSTEM jest identyfikatorem chrome URI pliku encji. Dla naszego prostego rozszerzenia, głównym elementem jest overlay.

+ +

Aby użyć encji, zmodyfikuj swój kod XUL, tak żeby wyglądał jak ten (poniższa linia musi być zawarta wewnątrz elementu <statusbar id="status-bar"> z poprzedniego przykładu):

+ +
<button label="&button.label;" accesskey="&button.accesskey;"/>
+
+ +

Rejestr Chrome załaduje plik encji z pakietu lokalizacyjnego odpowiadającego wybranej lokalizacji.

+ +

Dla łańcuchów znaków, których używasz w skrypcie, utwórz plik tekstowy .properties, który w każdej linii ma łańcuchy znaków w formacie:

+ +
key=value
+
+ +

i następnie użyj: nsIStringBundleService/nsIStringBundle lub znacznika <stringbundle> w celu załadowania wartości do skryptu.

+ +

Zrozumienie przeglądarki

+ +

Użyj Inspektora DOM (nie jest on częścią Standardowej instalacji Firefoksa; musisz go zainstalować z użyciem instalacji Użytkownika i wybrać Narzędzia programistyczne jeśli nie ma składnika "Inspektor DOM" w menu Narzędzia w twojej przeglądarce) do zbadania okna przeglądarki lub każdego innego okna XUL, które chcesz zmodyfikować.

+ +

Użyj przycisku "Wybierz węzeł do zbadania poprzez kliknięcie na nim" z paska narzędzi położonego u góry na lewo Inspektora DOM do kliknięcia na element (węzeł) w oknie przeglądarki. Kiedy to zrobisz widok drzewa hierarchii DOM w oknie Inspektora DOM przeniesie się na węzeł, na który kliknąłeś.

+ +

Użyj prawego panelu Inspektora DOM w celu znalezienia punktów łączenia z identyfikatorami, których możesz użyć przy wstawianiu swoich elementów z nakładek. Jeśli nie możesz znaleźć elementu z identyfikatorem, do któregoś mógłbyś się podłączyć, być może będziesz musiał dołączyć skrypt do swojej nakładki i wstawiać swoje elementy, kiedy zdarzenie load zostanie odpalone w głównym oknie XUL.

+ +

Debugowanie rozszerzeń

+ +

Analityczne narzędzia do debugowania

+ + + +

Debugowanie printf

+ + + +

Zaawansowane debugowanie

+ + + +

Szybki start

+ +

Możesz zastosować narzędzie Kreator rozszerzeń do generowania prostych rozszerzeń, które potem możesz modyfikować.

+ +

Rozszerzenie Hello World podobne do tych, które można wygenerować Kreatorem Rozszerzeń jest opisane linijka po linijce w innym przewodniku MozillaZine Knowledge Base.

+ +

Dalsze informacje

+ +
* Rozszerzenia - FAQ
+* Rozszerzenia
+
+ +
+

{{ Note(1) }}Dwie uwagi do tego punktu:

+ + -- cgit v1.2.3-54-g00ecf