Wstęp
Na tej stronie opisujemy sprawdzone metody wywoływania funkcji i uzyskiwania dostępu do właściwości w głównej aplikacji Blockly. Zasady te dotyczą tworzenia wtyczek do Blockly i integrowania Blockly z samodzielną aplikacją.
Podklasyfikacje i rozszerzanie
Blockly ma wiele paradygmatów dodawania funkcji, w tym:
- Podklas (np. tworzenie nowego mechanizmu renderowania)
- Składanki (np. dodanie rozszerzenia blokującego lub mutatora)
- Definicje bloków (np. definicje bloków procedur)
W tym dokumencie wszystkie 3 przypadki są równoważne z klasyfikacją podklasy.
Wstrzykiwanie podklas
Niektóre klasy można zastępować za pomocą metody Blockly.inject. Te podklasy muszą rozszerzać klasę podstawową lub implementować odpowiedni interfejs.
Swoją podklasę możesz przekazać do metody injection.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
Możesz też zarejestrować swoją klasę za pomocą Blockly.registry i użyć nazwy rejestru do wstrzyknięcia klasy. Jest to przydatne, jeśli opcje wstrzykiwania
przechowujesz w czystym formacie JSON.
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
Można zastąpić te zajęcia:
| Nazwa rejestracji | Klasa interfejsu/klasa podstawowa |
|---|---|
blockDragger |
Blockly.IBlockDragger |
connectionChecker |
Blockly.IConnectionChecker |
connectionPreviewer |
Blockly.IConnectionPreviewer |
flyoutsVerticalToolbox |
Blockly.IFlyout |
flyoutsHorizontalToolbox |
Blockly.IFlyout |
metricsManager |
Blockly.IMetricsManager |
renderer |
Blockly.blockRendering.Renderer |
toolbox |
Blockly.IToolbox |
Więcej informacji o korzystaniu z interfejsów znajdziesz w sekcji dotyczącej interfejsów w dokumentacji.
Widoczność
Do oznaczania widoczności w głównej bibliotece jako public, private lub protected używamy modyfikatorów dostępu TypeScript.
Niektóre usługi mogą być oznaczone adnotacją @internal w komentarzach w TsDoc.
Wszystkie właściwości public i protected są opisane w sekcji References na stronie Blockly. Widoczność możesz też sprawdzić, odczytując kod.
publiczna
Wszystko oznaczone jako public jest częścią naszego publicznego interfejsu API. Każda właściwość w module,
która nie zawiera modyfikatora widoczności, jest uznawana za publiczną.
Staramy się nie zmieniać naszego publicznego interfejsu API często ani bez wyraźnego powodu i ostrzeżenia. Wyjątek: możemy opublikować nowy interfejs API w jednej wersji i zmodyfikować go w kolejnej w odpowiedzi na opinie. Potem możesz uznać funkcję publiczną lub właściwość za stabilną.
Funkcje publiczne można wywoływać z dowolnego miejsca i zastępować je w podklasach, o ile podpis się nie zmieni.
chroniony
Dostęp do chronionych funkcji i właściwości jest możliwy tylko przez klasy lub podklasę definiującą.
Podklasy mogą zastępować chronione funkcje i właściwości bez zmiany podpisów typów.
Na przykład niestandardowy mechanizm renderowania, który rozszerza podstawową klasę mechanizmu renderowania, może uzyskać dostęp do jej chronionych właściwości.
W każdym przypadku musisz dowiedzieć się, jak funkcja lub właściwość są używane w pozostałej części kodu.
private
Dostęp do tych danych można uzyskać tylko za pomocą kodu w tym samym pliku co definicja. Bezpośredni dostęp do tych właściwości może powodować niezdefiniowane działanie.
Podklas nie mogą zastępować funkcji i właściwości prywatnych.
Właściwości prywatne mogą ulec zmianie bez ostrzeżenia, ponieważ nie są uważane za część publicznego interfejsu API Blockly.
Niektóre funkcje w Blockly nie mają adnotacji widoczności, ponieważ nie są eksportowane z modułu. Są to w zasadzie zmienne lokalne i nie można ich używać poza ich modułem definiującym. Powinny być one uważane za równoważne z nieruchomościami prywatnymi.
wewnętrzne
Funkcje i właściwości wewnętrzne powinny być używane w głównej bibliotece, ale nie poza nią. Są one oznaczone adnotacją TsDoc @internal.
Właściwości wewnętrzne mogą ulec zmianie bez ostrzeżenia, ponieważ nie są uważane za część publicznego interfejsu API Blockly.
Właściwości wewnętrzne są dostępne z dowolnego miejsca w obrębie rdzeni i są zastępowane w podklasach w podstawowym, dopóki podpis się nie zmieni. Nie można uzyskać do nich dostępu spoza podstawowej biblioteki.
wycofano
Nie należy używać niczego, co jest oznaczone jako @deprecated. Większość wycofanych funkcji obejmuje wskazówki dotyczące preferowanego kodu umieszczonego w ostrzeżeniu w konsoli lub w dokumencie pomocy.
Tam, gdzie będzie to możliwe, wycofywane funkcje będą logowały ostrzeżenie zawierające planowaną datę usunięcia i zalecenie zastosowania funkcji zastępczej.
Najczęstsze pytania
Co zrobić, jeśli funkcja, której chcę użyć, nie jest publiczna?
Zgłoś prośbę o dodanie funkcji w głównej aplikacji Blockly. Opisz swój przypadek użycia i opisz, co mamy opublikować.
Będziemy korzystać z tej funkcji, aby porozmawiać o tym, czy je udostępnić publicznie, czy też, czy istnieją inne sposoby na uzyskanie tych samych informacji.
Jeśli zdecydujemy się udostępnić je publicznie, Ty lub zespół Blockly wprowadzicie odpowiednią zmianę, która zostanie udostępniona w kolejnej wersji aplikacji Blockly.
Jeśli zdecydujesz się używać wtyczki, która nie jest publiczna, możesz oznaczyć ją jako beta i umieścić te informacje w README.
A co z własnym instalowaniem poprawek?
Więcej informacji na temat monkeypatching.
Stosowanie pojedynczych poprawek jest niebezpieczne, ponieważ poprawki mogą bez powiadomienia przestać działać z powodu wykorzystania niepublicznych fragmentów interfejsu Blockly API. Instalowanie poprawek we wtyczce jest szczególnie niebezpieczne, ponieważ Twój kod może słabo współdziałać z innymi wtyczką, która wprowadza te poprawki. Z tego powodu zdecydowanie odradzamy stosowanie poprawek do aplikacji i wtyczek innych firm oraz nie akceptujemy tego rozwiązania we własnych wtyczkach.
Czy mogę zastąpić funkcje publiczne?
Podczas podziału na podklasy: tak. W przeciwnym razie: nie, to tylko poprawki.
Czy mogę zastąpić chronione funkcje?
Podczas podziału na podklasy: tak. W przeciwnym razie: nie, to tylko poprawki.
Czy mogę zastąpić funkcje wewnętrzne lub prywatne?
Nie, to tylko poprawki.
Kiedy mogę uzyskać bezpośredni dostęp do właściwości? Kiedy należy używać metody getter lub setera?
Jeśli publikujemy metodę pobierającą lub ustawiającą, użyj jej zamiast bezpośredniego dostępu do właściwości. Jeśli właściwość nie jest publiczna, zdecydowanie używaj metod pobierania i ustawiania.
Co zrobić, jeśli usługa nie ma adnotacji?
Domyślnie jest on publiczny, ale prosimy o kontakt w razie potrzeby użycia pary getter/setter.
Co zrobić, jeśli funkcja nie ma adnotacji?
Domyślnie jest on publiczny.
Co zrobić, jeśli nadal nie masz pewności?
Zadaj pytanie na forum, a my skontaktujemy się z Tobą w ciągu jednego dnia roboczego.