Narzędzia deweloperskie Blockly umożliwiają tworzenie bloków niestandardowych za pomocą bloków. Obsługuje pola publikowane jako wtyczki, a także pola dostępne w podstawowej wersji Blockly. Jeśli masz utworzone pole niestandardowe, możesz dodać do niego obsługę w Fabryce bloków, korzystając z tego przewodnika. Zanim dodasz obsługę pola niestandardowego, musisz opublikować je w npm. Musisz też zobowiązać się do aktualizowania tego pola, aby nadążać za zmianami w Blockly. W przeciwnym razie w przyszłości możemy usunąć je z Block Factory.
Tworzenie w Block Factory
Kod źródłowy fabryki bloków znajduje się w repozytorium blockly-samples w katalogu examples/developer-tools.
Aby przesłać zmianę w Narzędziach dla programistów w blockly-samples, musisz wykonać typowe czynności związane z programowaniem w blockly-samples. W przeciwieństwie do pracy z wtyczkami musisz uruchomić npm
install bezpośrednio z katalogu examples/developer-tools, a nie z katalogu głównego blockly-samples.
Instalowanie wtyczki
Aby Fabryka bloków wyświetlała niestandardowe pole w podglądzie, musi je zainstalować. Dodaj pole jako zależność npm narzędzi dla programistów. Następnie zarejestruj urządzenie lub wykonaj inne niezbędne czynności konfiguracyjne w developer-tools/src/blocks/index.ts.
Tworzenie bloku dla pola
Fabryka bloków używa bloków do tworzenia bloków niestandardowych, więc potrzebujesz bloku, który będzie reprezentować Twoje pole niestandardowe.
Tworzenie definicji bloku
Musisz zaprojektować blok dla swojego pola. Jeśli chcesz, możesz nawet zaprojektować go za pomocą narzędzia Block Factory. Blok powinien umożliwiać użytkownikowi skonfigurowanie ustawień wymaganych przez pole, takich jak wartości domyślne i nazwa. Dodaj tę definicję bloku do developer-tools/src/blocks/fields.ts i zaimportuj ją w developer-tools/src/blocks/index.ts.
Dodawanie bloku do listy narzędzi
Następnie musisz dodać ten blok do definicji przybornika, aby był dostępny dla użytkowników. Definicja skrzynki narzędziowej znajduje się w developer-tools/src/toolbox.ts. Blok powinien zostać dodany do kategorii „Pola”.
Generatory kodu
Fabryka bloków działa na podstawie systemu Generator kodu, który znasz już z Blockly. Każdy blok ma generator kodu bloku dla każdego typu danych wyjściowych generowanych przez fabrykę bloków, a bloki nadrzędne składają kod bloków podrzędnych w odpowiednie dane wyjściowe. Aby dodać obsługę niestandardowego pola, musisz dodać funkcje generatora kodu blokowego dla każdej z klas generatora kodu.
Utwórz plik dla bloku pól w katalogu output-generators/fields. Do tego pliku dodasz generatory kodu blokowego dla każdego z tych generatorów. Zaimportuj ten plik w pliku blocks/index.ts, aby funkcje generatora kodu blokowego zostały załadowane do aplikacji.
Definicja JavaScript
Symbol javascriptDefinitionGenerator tworzy kod, który będzie uwzględniony w definicji JavaScriptu dla bloku zawierającego Twoje pole niestandardowe. Zwykle oznacza to, że generator kodu blokowego powinien zwrócić wiersz kodu, który wygląda tak:.appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). Pamiętaj, że ten wiersz kodu nie zawiera średnika, ponieważ dane wejściowe zawierające wiele pól będą miały kilka wywołań funkcji appendField połączonych ze sobą. Argumenty w konstruktorze są pobierane z wartości ustawionych przez użytkownika w bloku pola. Oto przykład generatora kodu blokowego dla FieldAngle:
javascriptDefinitionGenerator.forBlock['field_angle'] = function (
block: Blockly.Block,
generator: JavascriptDefinitionGenerator,
): string {
const name = generator.quote_(block.getFieldValue('FIELDNAME'));
const angle = block.getFieldValue('ANGLE');
return `.appendField(new FieldAngle(${angle}), ${name})`;
};
Blok kątowy, który użytkownik przeciągnął z kategorii „Pola” w przyborniku Block Factory, ma 2 pola:
FIELDNAME: użytkownik może ustawić nazwę pola w bloku niestandardowym.ANGLE: użytkownik może ustawić domyślną wartość kąta.
W tym generatorze kodu blokowego pobieramy domyślną wartość kąta i przekazujemy ją jako jedyny argument do konstruktora FieldAngle. Nazwa pola jest zawsze przekazywana jako drugi argument do funkcji appendField.
Definicja formatu JSON
Polecenie jsonDefinitionGenerator jest podobne, ale zwraca część definicji bloku JSON, która odpowiada Twojemu polu. Zwykle jest to obiekt JSON, który zawiera:
type: odpowiada nazwie pola w rejestrze pól Blockly.name: użytkownik może ustawić nazwę pola w bloku niestandardowym.- wszystkie inne właściwości niestandardowe wymagane przez metodę inicjowania JSON pola.
Oto przykład z właściwości FieldAngle:
jsonDefinitionGenerator.forBlock['field_angle'] = function (
block: Blockly.Block,
generator: JsonDefinitionGenerator,
): string {
const code = {
type: 'field_angle',
name: block.getFieldValue('FIELDNAME'),
angle: block.getFieldValue('ANGLE'),
};
return JSON.stringify(code);
};
Nagłówki kodu
Generator nagłówków kodu tworzy dane wyjściowe nagłówków kodu widoczne w Block Factory. Dane wyjściowe można przełączać między importami modułów ES a tagami skryptów w zależności od tego, jak użytkownik chce wczytać kod. W rzeczywistości istnieją 2 różne instancje generatora: po jednej dla każdego przypadku. Dla każdego z nich musisz dodać generator kodu blokowego. Oto przykład właściwości FieldAngle:
importHeaderGenerator.forBlock['field_angle'] = function (
block: Blockly.Block,
generator: CodeHeaderGenerator,
): string {
generator.addHeaderLine(
`import {registerFieldAngle, FieldAngle} from '@blockly/field-angle';`,
);
generator.addHeaderLine(`registerFieldAngle();`);
return '';
};
scriptHeaderGenerator.forBlock['field_angle'] = function (
block: Blockly.Block,
generator: CodeHeaderGenerator,
): string {
generator.addHeaderLine(
`<script src="https://unpkg.com/@blockly/field-angle"></script>`,
);
generator.addHeaderLine(`registerFieldAngle();`);
return '';
};
Te generatory mają metodę o nazwie addHeaderLine, która umożliwia określenie wiersza kodu, który ma być wywoływany przed użyciem pola w kodzie. Zwykle obejmuje to takie działania jak importowanie pola lub wczytywanie go za pomocą tagu skryptu, a także wywoływanie funkcji, która zarejestruje pole w rejestrze pól Blockly.
W przypadku tych 2 generatorów bloków kodu cały kod należy dodawać za pomocą wywołań funkcji addHeaderLine. Ta funkcja sprawi, że każdy wiersz nagłówka będzie wyświetlany tylko raz, nawet jeśli blok pól niestandardowych jest używany wielokrotnie w jednym bloku niestandardowym. Generator kodu bloku powinien zwrócić pusty ciąg.
Atrapa generatora
Na koniec mamy generator, który tworzy stub generatora dla pola. W tym generatorze kodu blokowego będziesz pisać kod, który generuje kod, który pomaga użytkownikowi pisać kod, który generuje kod. Masz już mętlik w głowie? To łatwiejsze, niż się wydaje.
W szablonie generatora bloku niestandardowego znajduje się gotowa zmienna
reprezentująca każde pole w bloku. Następnie TODO użytkownik musi
połączyć wszystkie te zmienne w ciąg kodu, który będzie zwracać jego
blok niestandardowy. Oznacza to, że generator kodu blokowego musi zwykle tylko zwrócić wiersz, który tworzy tę zmienną niestandardową. Załóżmy, że użytkownik tworzy blok niestandardowy, który doda promienie słoneczne do obszaru roboczego. Dodają do bloku pole kąta i nadają mu nazwę "SUN_DIRECTION". Stub generatora dla tego bloku będzie zawierać wiersz const angle_sun_direction =
block.getFieldValue("SUN_DIRECTION");. To jest wiersz kodu, który musi zwrócić nasz generator bloków kodu dla pola kąta:
generatorStubGenerator.forBlock['field_angle'] = function (
block: Blockly.Block,
generator: GeneratorStubGenerator,
): string {
const name = block.getFieldValue('FIELDNAME');
const fieldVar = generator.createVariableName('angle', name);
return `const ${fieldVar} = block.getFieldValue(${generator.quote_(
name,
)});\n`;
};
Aby uzyskać standardową nazwę zmiennej, możesz wywołać funkcję generator.createVariableName i przekazać typ pola (np. angle, number itp.) wraz z nazwą pola podaną przez użytkownika.
Przetestuj
Po napisaniu wszystkich tych części możesz uruchomić BlockFactory, wpisując npm start w katalogu blockly-samples/examples/developer-tools. Powinno być możliwe przeciągnięcie bloku z kategorii pól, dodanie go do wejścia bloku i obserwowanie zmiany danych wyjściowych. Sprawdź, czy podgląd bloku wygląda prawidłowo i czy kod w poszczególnych sekcjach wyjściowych jest poprawny.