Z tego dokumentu dowiesz się, jak utworzyć nową wtyczkę. Opisany w nim proces dotyczy tworzenia wtyczek własnych, ale możesz go użyć jako wskazówki przy tworzeniu wtyczek innych firm.
Omówienie wtyczek znajdziesz w artykule Wtyczki.
Krótkie wprowadzenie do tworzenia wtyczek znajdziesz w naszym filmie How to Build a Plugin (2021).
Własne listy odbiorców a listy odbiorców dostarczone przez firmę zewnętrzną
Docelowym użytkownikiem wtyczki jest programista, który znajduje i używa wtyczki za pomocą npm.
Wtyczki własne są obsługiwane przez zespół Blockly i publikowane w zakresie @blockly w npm. Zostały one zaprojektowane tak, aby można było ich używać w szerokim zakresie aplikacji Blockly, są stabilne i łatwe w obsłudze. Są one przechowywane w blockly-samples. Pole do ustawiania prędkości silnika może być używane w wielu projektach robotycznych i jest dobrym kandydatem na wtyczkę własną.
Wtyczki innych firm są utrzymywane i publikowane niezależnie. Mogą być bardziej złożone, eksperymentalne lub przeznaczone do węższego zakresu zastosowań Blockly. Pole do edytowania konkretnego obiektu zdefiniowanego przez schemat bazy danych lepiej sprawdzi się jako wtyczka innej firmy.
Kryteria własne
Wtyczki własne muszą spełniać te wymagania:
- Działać na wszystkich głównych platformach, chyba że zespół Blockly przyzna wyjątek.
- Chrome, Firefox, Safari, Edge
- Miej autora, który będzie gotowy do usuwania błędów w pierwszym roku.
- Nie modyfikuj kodu Blockly.
- Musi mieć jasno zdefiniowany i udokumentowany interfejs API.
- Nie wywołuj funkcji prywatnych ani pakietowych z podstawowego kodu Blockly, chyba że zespół Blockly przyzna Ci wyjątek.
- Zastępowanie funkcji pakietu w zdefiniowanej przez Ciebie podklasie jest dozwolone.
- Jeśli chcesz uzyskać zwolnienie, zgłoś to w formie problemu w repozytorium blockly-samples.
- Obejmują testy.
Procedura
Wtyczki przechodzą 4 etapy: sugestia, dyskusja, wdrożenie i publikowanie.
Sugestia
Wtyczka zaczyna się jako sugestia. Możesz zaproponować wtyczkę, tworząc nowy problem za pomocą szablonu Prośba o funkcję. Więcej informacji znajdziesz w artykule o tym, jak napisać prośbę o dodanie funkcji.
Oprócz podstawowych informacji o prośbie dotyczącej funkcji sugestia wtyczki powinna zawierać:
- Interfejs API, który wtyczka udostępnia.
- Interfejsy API, które należy dodać lub zmienić w podstawowej wersji Blockly, aby obsługiwać wtyczkę.
- zrzuty ekranu, GIF-y lub makiety, jeśli wtyczka zawiera elementy interfejsu;
- wyjaśnienie, dlaczego powinna to być wtyczka własna, a nie wtyczka innej firmy;
Zespół Blockly sprawdza sugestie na bieżąco i zamyka zgłoszenie lub potwierdza, że wtyczka byłaby dobrym rozwiązaniem.
Dyskusja
Następnie wtyczka przechodzi do fazy dyskusji. Ten etap obejmuje:
- Wyjaśnienie pożądanej funkcjonalności.
- Wyjaśnienie interfejsu API wtyczki.
- Planowanie wdrożenia.
- Planowanie testów.
- Omówienie zmian w interfejsie API w podstawowej wersji Blockly.
- Podziel duże wtyczki na etapy implementacji.
- Nazewnictwo wtyczek zgodne z naszymi konwencjami nazewnictwa.
- Potwierdzenie, że wszystkie kryteria dotyczące danych własnych zostaną spełnione.
Dyskusja zwykle odbywa się w wątku problemu w GitHubie. Im mniejszy zakres wtyczki, tym szybciej można przejść do fazy dyskusji. Większe wtyczki mogą przyciągać uwagę społeczności i wywoływać silne opinie na temat właściwego rozwiązania. Jeśli tak się stanie w przypadku Twojego problemu, gratulacje! Znaleziono coś, na czym ludziom zależy.
Celem jest podjęcie na koniec fazy dyskusji wszystkich najważniejszych decyzji projektowych i stworzenie jasnej listy kroków wdrożenia. Obie te kwestie powinny być udokumentowane w komentarzach do zgłoszenia.
Podczas dyskusji możemy zdecydować, że wtyczka powinna być wtyczką innej firmy, a nie wtyczką opublikowaną w zakresie @blockly. W takim przypadku wyjaśnimy, dlaczego tak się stało, i zamkniemy zgłoszenie.
Po zakończeniu dyskusji członek zespołu Blockly stwierdza, że jest gotowy do wdrożenia.
Implementacja
Etapy wdrażania obejmują:
- Uruchomienie
npx @blockly/create-package, aby skonfigurować wtyczkę i jej katalog na podstawie szablonu. Więcej informacji - Implementowanie podstawowej logiki wtyczki.
- Wdrażanie interfejsu, jeśli jest to konieczne.
- Testowanie wtyczki za pomocą platformy Mocha.
- Dokumentowanie wtyczki, w tym pliku
README.
Jeśli sugerowana wtyczka została zatwierdzona do wdrożenia i chcesz nad nią pracować, skomentuj zgłoszenie i zapytaj, czy nadal można wnieść w niej swój wkład.
Wdrożenie może być przeprowadzane równolegle przez wielu współtwórców. Wtyczkę możesz wdrożyć wspólnie na własnym rozwidleniu lub za pomocą żądań pull w tym repozytorium. Jeśli chcesz współpracować nad wtyczką w tym repozytorium, poproś zespół Blockly o utworzenie dla Ciebie gałęzi funkcji.
Wtyczki należy dodać do pliku
gh-pages/index.md
w gałęzi master repozytorium blockly-samples. Spowoduje to, że będą one widoczne w naszej witrynie z wtyczkami. Wtyczki własne powinny kierować do strony testowej. Do tej strony można też dodawać wtyczki innych firm, które mogą prowadzić do wybranego przez właściciela linku, np. do hostowanej wersji demonstracyjnej lub strony npm.
Publikowanie
Na koniec publikowanie. Zespół Blockly używa Lerna do zarządzania wersjami i publikowania wszystkich wtyczek.
W każdy czwartek publikujemy wszystkie wtyczki, które uległy zmianie od czasu ostatniej wersji. Jeśli chcesz, aby zmiana została opublikowana wcześniej, zaznacz to w żądaniu scalenia.
Witryna wtyczek jest też aktualizowana za każdym razem, gdy publikowane są wtyczki.
Wtyczki, które nie są gotowe do publikacji, powinny być oznaczone symbolem private w package.json. Może się tak zdarzyć, jeśli wtyczka korzysta ze zmiany w podstawowej wersji Blockly, która nie została jeszcze opublikowana. Core Blockly jest publikowany w ostatnim tygodniu każdego kwartału (raz na 3 miesiące).