Wprowadzenie
Na tej stronie opisujemy sprawdzone metody wywoływania funkcji i uzyskiwania dostępu do w podstawowej usłudze Blockly. Te zasady dotyczą tworzenia wtyczek Blockly lub integrowanie Blockly z samodzielną aplikacją
Podklasy i rozszerzanie
Blockly ma wiele schematów dodawania funkcji, takich jak:
- Podklasy (np. tworzenie nowego mechanizmu renderowania)
- Składanki (np. dodawanie rozszerzenia blokowego lub mutatora)
- Definicje blokad (np. definicje bloków procedur)
Na potrzeby tego dokumentu wszystkie 3 przypadki są równoważne podklasyfikacji.
Wstrzykiwanie podklas
Niektóre zajęcia można zastępować metodą Blockly.inject. Te
podklasy muszą albo rozszerzać klasę bazową, albo implementować odpowiadającą jej klasę bazową
za pomocą prostego interfejsu online.
Swoją klasę podrzędną możesz przekazać do metody wstrzykiwania.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
Możesz też zarejestrować się na zajęcia za pomocą Blockly.registry i użyć
nazwę rejestru, aby wstrzyknąć klasę. Jest to przydatne, jeśli przechowujesz zastrzyki
jako czystego kodu JSON.
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
Te klasy można zastąpić:
| 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 za pomocą dokumentu.
Widoczność
Używamy modyfikatorów dostępu TypeScript.
aby oznaczyć widoczność w bibliotece podstawowej jako public, private lub protected.
Niektóre miejsca zakwaterowania mogą mieć adnotacje @internal w swoich
Komentarze w TsDoc.
Wszystkie właściwości public i protected są udokumentowane w
Sekcja Odnośniki na stronie Blockly. Możesz też
aby sprawdzić widoczność, odczytując kod.
publiczna
Wszystkie elementy oznaczone jako public są częścią naszego publicznego interfejsu API. Dowolna właściwość w module
bez modyfikatora widoczności jest uznawany za publiczny.
Staramy się nie zmieniać publicznego interfejsu API często i bez uzasadnionego powodu. . Wyjątek: możemy udostępnić publicznie nowy interfejs API w jednej wersji i wprowadzić zmiany w następnej wersji na podstawie wstępnych opinii. Po tym terminie możesz funkcji publicznej lub stabilnej własności.
Funkcje publiczne można wywoływać z dowolnego miejsca i zastępować je w podklasach jako o ile podpis nie ulegnie zmianie.
chronione
Dostęp do chronionych funkcji i właściwości może uzyskać tylko klasa definiująca lub podklasa.
Podklasy mogą zastępować funkcje i właściwości chronione bez zmiany podpisów typów.
Na przykład niestandardowy mechanizm renderowania, który rozszerza podstawową klasę mechanizmu renderowania, może jej właściwościach chronionych.
W każdym przypadku upewnij się, że wiesz, jak funkcja lub właściwość są w pozostałej części kodu.
prywatne
Dostęp do nich można uzyskać tylko za pomocą kodu w tym samym pliku co definicja. Bezpośrednio uzyskanie dostępu do tych właściwości może spowodować niezdefiniowane zachowanie.
Podklasy nie mogą zastępować funkcji ani właściwości prywatnych.
Właściwości prywatne mogą ulec zmianie bez ostrzeżenia, ponieważ stanowią część publicznego interfejsu API Blockly.
Niektóre funkcje w Blockly nie mają adnotacji dotyczących widoczności, ponieważ nie są eksportowane z modułu. Te funkcje są zasadniczo zmiennymi lokalnymi i nie można ich używać poza modułem definiującym odbiorców. Należy je wziąć pod uwagę w postaci właściwości prywatnych.
wewnętrzne
Funkcje i właściwości wewnętrzne powinny być używane w ramach platformy
z biblioteki, ale nie z zewnątrz. Są one oznaczone w dokumencie TsDoc @internal.
adnotacja.
Właściwości wewnętrzne mogą ulec zmianie bez ostrzeżenia, ponieważ stanowią część publicznego interfejsu API Blockly.
Właściwości wewnętrzne są dostępne z dowolnego miejsca w rdzeniu i mogą być zastępowane w podklasy, o ile podpis się nie zmieni. Nie mogą być spoza podstawowej biblioteki.
wycofano
Nie należy używać żadnych elementów oznaczonych jako @deprecated. Większość wycofanych funkcji to:
zgodnie z instrukcjami w preferowanym kodzie, w ostrzeżeniu w konsoli lub w pliku TSDoc.
Tam, gdzie to możliwe, wycofane funkcje będą rejestrować ostrzeżenie zawierające planowanej daty usunięcia oraz zalecenia dotyczące wywoływania funkcji zastępczej.
Najczęstsze pytania
Co zrobić, jeśli funkcja, której chcę użyć, nie jest publiczna?
Prześlij prośbę o dodanie funkcji na rdzeniu Blockly. Opisz swój przypadek użycia i wyjaśnij, co które mamy udostępnić publicznie.
Za pomocą tej funkcji spytamy, czy materiał ma zostać udostępniony publicznie, czy istnieją inne sposoby uzyskania tych samych informacji.
Jeśli zdecydujemy się je upublicznić, Ty lub zespół Blockly odpowiednia zmiana. Zostanie ona udostępniona w kolejnej wersji Blockly.
Jeśli chcesz użyć we wtyczce niepublicznego członka, zastanów się nad oznaczeniem
w wersji beta i umieść te informacje w README.
A co z małpami?
Dowiedz się więcej na temat monkeypatching.
Stosowanie poprawek jest niebezpieczne, ponieważ poprawki mogą przestać działać bez powiadomienia do niepublicznych fragmentów interfejsu Blockly API. Instalowanie poprawek we wtyczce jest szczególnie niebezpieczny, ponieważ kod może źle wchodzić w interakcje z innymi która wprowadza poprawki tego samego kodu. Z tego powodu zdecydowanie odradzamy stosowania poprawek w aplikacjach i wtyczkach innych firm; nie akceptuje go we własnych wtyczkach.
Czy mogę zastąpić funkcje publiczne?
Podczas tworzenia podklasy: tak. A w przeciwnym razie: nie, to tylko małpa łatka.
Czy mogę zastąpić funkcje chronione?
Podczas tworzenia podklasy: tak. A w przeciwnym razie: nie, to tylko małpa łatka.
Czy mogę zastąpić funkcje wewnętrzne lub prywatne?
Nie, to jakaś łatka.
Kiedy uzyskam bezpośredni dostęp do nieruchomości? Kiedy należy użyć metody getter lub setera?
Jeśli zostanie opublikowana metoda pobierania lub setera, użyj jej zamiast bezpośrednio dostęp do usługi. Jeśli obiekt nie jest publiczny, zdecydowanie użyj metody getter i setery.
Co zrobić, jeśli usługa nie ma adnotacji?
Domyślnie jest on publiczny, ale jeśli chcesz umieścić .
Co zrobić, jeśli funkcja nie ma adnotacji?
Domyślnie jest ona publiczna.
A jeśli nadal nie mam pewności?
Zadaj pytanie na forum Skontaktujemy się z Tobą, zwykle w ciągu jednego dnia roboczego.