Na tej stronie znajdziesz sprawdzone metody wywoływania funkcji i dostępu do właściwości w głównym środowisku Blockly. Te zasady dotyczą tworzenia wtyczek do Blockly oraz integrowania Blockly z samodzielną aplikacją.
Widoczność
Używamy modyfikatorów dostępu TypeScript, aby oznaczyć widoczność w bibliotece podstawowej jako public, private lub protected.
Niektóre właściwości mogą być oznaczone symbolem @internal w komentarzach TsDoc.
Wszystkie właściwości public i protected są opisane w sekcji Odniesienia na stronie Blockly. Możesz też sprawdzić widoczność, odczytując kod.
publiczna
Wszystko oznaczone jako public należy do publicznego interfejsu API. Każda usługa w module, która nie ma modyfikatora widoczności, jest uważana za publiczną.
Staramy się nie zmieniać publicznego interfejsu API zbyt często ani bez ważnego powodu i ostrzeżenia. Wyjątek: możemy udostępnić nowy interfejs API w jednej wersji, a w następnej zmodyfikować go w odpowiedzi na wczesne opinie. Po tym możesz uznać publiczną funkcję lub usługę za stabilną.
Funkcje publiczne mogą być wywoływane z dowolnego miejsca i przesłonięte w podklasach, o ile ich sygnatura się nie zmienia.
chroniony
Funkcje i właściwości chronione są dostępne tylko dla definiującej je klasy lub podklasy.
Podklasy mogą zastąpić chronione funkcje i właściwości bez zmiany sygnatur typów.
Na przykład niestandardowy renderujący, który rozszerza podstawową klasę renderującego, może uzyskiwać dostęp do jej chronionych właściwości.
W każdym przypadku musisz zrozumieć, jak funkcja lub właściwość jest używana w pozostałym kodzie.
prywatne
Dostęp do nich mają tylko kody w tym samym pliku co definicja. Bezpośrednie uzyskiwanie dostępu do tych właściwości może spowodować nieokreślone działanie.
Podklasy nie mogą zastępować prywatnych funkcji ani właściwości.
Właściwości prywatne mogą ulec zmianie bez ostrzeżenia, ponieważ nie są one uważane za część publicznego interfejsu API Blockly.
Niektóre funkcje w Blockly nie mają adnotacji widoczności, ponieważ nie są eksportowane z ich modułu. Te funkcje są w istocie zmiennymi lokalnymi i nie można ich używać poza modułem, w którym zostały zdefiniowane. Należy je uznać za równoważne z własnościami prywatnymi.
wewnętrzne
Funkcje i właściwości wewnętrzne są przeznaczone do użytku w głównej bibliotece, ale nie na zewnątrz. Są one oznaczone adnotacją @internal w TsDoc.
Właściwości wewnętrzne mogą ulec zmianie bez ostrzeżenia, ponieważ nie są one uważane za część publicznego interfejsu API Blockly.
Do właściwości wewnętrznych można uzyskać dostęp z dowolnego miejsca w jądrze i zastąpić je w podklasach w jądrze, o ile podpis się nie zmieni. Nie można ich otwierać poza główną biblioteką.
wycofano
Nie należy używać elementów oznaczonych symbolem @deprecated. Większość wycofanych funkcji zawiera wskazówki dotyczące preferowanego kodu, które można znaleźć w oszacowaniu w konsoli lub w dokumentacji TSDoc.
W miarę możliwości funkcje przestarzałe będą rejestrować ostrzeżenie, które zawiera datę planowanego usunięcia i zalecenie użycia funkcji zastępczej.
Najczęstsze pytania
Poniżej znajdziesz odpowiedzi na najczęstsze pytania, które pojawiły się w związku z Blockly.
Co zrobić, jeśli funkcja, której chcę użyć, nie jest publiczna?
Prześlij prośbę o dodanie funkcji w podstawowej wersji Blockly. Dołącz opis przypadku użycia i oświadczenie, że chcesz, abyśmy udostępnili dane publicznie.
Użyjemy tej funkcji, aby omówić, czy dane powinny być publiczne, czy istnieją inne sposoby uzyskania tych informacji.
Jeśli zdecydujemy się na udostępnienie funkcji, Ty lub zespół Blockly wprowadzicie odpowiednie zmiany, które zostaną zastosowane w kolejnych wersjach Blockly.
Jeśli zdecydujesz się użyć w pluginie niepublicznego elementu, rozważ oznaczenie plugina jako wersji beta i uwzględnienie tej informacji w README.
A co z monkeypatchingiem?
Dowiedz się więcej o monkeypatchingu.
Modyfikowanie kodu za pomocą monkeypatchingu jest niebezpieczne, ponieważ łaty mogą przestać działać bez powiadomienia z powodu używania niepublicznych części interfejsu Blockly API. Wstawianie poprawek w pluginie jest szczególnie niebezpieczne, ponieważ Twój kod może nie działać prawidłowo z żadnym innym wtyczką, która zawiera te same poprawki. Z tego powodu zdecydowanie odradzamy stosowanie monkeypatchingu w aplikacjach i wtyczkach innych firm. Nie akceptujemy go również w wtyczkach firm zewnętrznych.
Czy mogę zastąpić funkcje publiczne?
Podczas tworzenia podklas: tak. W przeciwnym razie: nie, to jest monkeypatching.
Czy mogę zastąpić chronione funkcje?
Podczas tworzenia podklas: tak. W przeciwnym razie: nie, to jest monkeypatching.
Czy mogę zastąpić funkcje wewnętrzne lub prywatne?
Nie, to jest monkeypatching.
Kiedy mogę uzyskać bezpośredni dostęp do usług? Kiedy należy używać metody gettera lub settera?
Jeśli opublikujemy metodę getter lub setter, 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 get i set.
Co zrobić, jeśli usługa nie ma adnotacji?
Domyślnie jest to publiczne, ale daj nam znać, jeśli chcesz, abyśmy wprowadzili parę metod getter/setter.
Co zrobić, jeśli funkcja nie ma adnotacji?
Domyślnie jest ona publiczna.
Co zrobić, jeśli nadal nie mam pewności?
Zadaj pytanie na forum, a skontaktujemy się z Tobą w ciągu kilku dni.