Dodaj pole wtyczki do blokowania fabryki

Narzędzia dla programistów Blockly umożliwiają tworzenie bloków niestandardowych za pomocą bloków. Obsługuje pola opublikowane jako wtyczki, a nie tylko pola z podstawowej usługi Blockly. Jeśli masz utworzone pole niestandardowe, możesz je dodać do fabryki bloku bloków, postępując zgodnie z tym przewodnikiem. Aby można było dodać obsługę pola niestandardowego, musi ono zostać opublikowane w npm. Musisz też zobowiązać się do aktualizowania pola, aby nadążać za zmianami w Blockly. W przeciwnym razie w przyszłości możemy być zmuszeni do usunięcia go z Block Factory.

Programowanie w fabryce bloków

Kod źródłowy komponentu Block Factory znajduje się w repozytorium blockly-samples w katalogu examples/developer-tools.

Aby przesłać zmianę w narzędziach dla programistów w postaci próbek blokowych, musisz wykonać typowe czynności związane z tworzeniem w próbkach blokowych. W odróżnieniu od pracy z wtyczkami musisz jednak uruchomić polecenie npm install bezpośrednio z katalogu examples/developer-tools, a nie na poziomie głównym komponentów blockly-sample.

Zainstaluj wtyczkę

Aby fabryka bloków wyświetlała niestandardowe pole w podglądzie, musisz je zainstalować. Dodaj swoje pole jako zależność npm dla narzędzi programistycznych. Następnie zarejestruj ją lub wykonaj inne czynności konfiguracyjne na koncie developer-tools/src/blocks/index.ts.

Utwórz blok dla pola

Fabryka bloków wykorzystuje bloki do tworzenia bloków niestandardowych, więc potrzebujesz bloku reprezentującego pole niestandardowe.

Tworzenie definicji bloku

Musisz zaprojektować blok dla swojego pola. Jeśli chcesz uzyskać metadany, możesz go nawet zaprojektować w Block Factory. Blokada powinna umożliwiać użytkownikowi skonfigurowanie konfiguracji wymaganej przez pole, np. wartości domyślnych i nazwy. Dodaj tę definicję bloku do developer-tools/src/blocks/fields.ts i zaimportuj ją do developer-tools/src/blocks/index.ts.

Dodaj bryłę do zestawu narzędzi

Następnie musisz dodać ten blok do definicji zestawu narzędzi, aby udostępnić go użytkownikom. Definicja zestawu narzędzi znajduje się w zadaniu developer-tools/src/toolbox.ts. Blok należy dodać do kategorii „Pola”.

Generatory kodu

Fabryka bloków korzysta z systemu Generatora kodu, który dobrze znasz z Blockly. Każdy blok ma generator kodu blokowego dla każdego typu danych wyjściowych generowanych przez fabrykę bloków. Bloki nadrzędne gromadzą kod bloków podrzędnych i uzyskują odpowiednie dane wyjściowe. Aby dodać obsługę pola niestandardowego, do każdej z klas generatora kodu musisz dodać funkcje generatora kodu blokowego.

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 do pliku blocks/index.ts, aby wczytać do aplikacji funkcje generatora kodu blokowego.

Definicja JavaScriptu

javascriptDefinitionGenerator tworzy kod, który zostanie umieszczony w definicji JavaScriptu dla bloku zawierającego pole niestandardowe. Zwykle oznacza to, że generator kodu blokowego powinien zwracać wiersz kodu podobny do .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 razem. Argumenty w konstruktorze są pobierane z wartości ustawionych przez użytkownika w bloku pól. 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ąta przeciągnięty przez użytkownika z kategorii „Pola” w narzędziach Fabryka bloków zawiera 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 generatorze kodów blokowych 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.

Uwaga: jeśli wartość pola musi być ujęta w cudzysłów, np. podczas przekazywania nazwy pola do funkcji appendField użyj parametru generator.quote_ zamiast ręcznego umieszczania w cudzysłowach.

Definicja w formacie JSON

Pole jsonDefinitionGenerator jest podobne, ale zwraca część definicji bloku JSON, która odpowiada Twojemu polu. Zazwyczaj jest to obiekt JSON zawierający:

• type: odpowiada nazwie pola w rejestrze pól Blockly
• name: użytkownik może ustawić nazwę pola w bloku niestandardowym
• wszystkich innych właściwości niestandardowych wymaganych przez metodę inicjowania json pola.

Oto przykład jeszcze raz z pola 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);
};

Uwaga: generatory kodu blokowego zawsze zwracają ciągi znaków, więc zanim zwrócisz obiekt, przeformatuj go.

Nagłówki kodu

Generator nagłówków kodu tworzy dane wyjściowe nagłówków kodu pokazywane w fabryce bloków. Dane wyjściowe można przełączać między importami esmodule i tagami skryptu, w zależności od tego, jak użytkownik chce wczytać kod. Istnieją więc 2 różne instancje generatorów: po 1 dla każdego przypadku. Do każdego z nich musisz dodać generator kodu blokowego. Oto przykład dla słowa kluczowego 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 '';
};

Wykorzystują metodę addHeaderLine, która pozwala określić wiersz kodu, który powinien zostać wywołany przed użyciem pola w kodzie. Zazwyczaj obejmuje to zadania, takie jak zaimportowanie pola lub wczytanie go za pomocą tagu skryptu oraz wywołanie funkcji rejestrującej pole w rejestrze pól Blockly.

Wskazówka: jeśli Twój pakiet został opublikowany na npm, powinien być automatycznie dostępny w unpkg, czyli w wygodnym miejscu, z którego mogą wczytywać się tagi skryptów.

W przypadku tych 2 generatorów kodu blokowego cały kod należy dodać za pomocą wywołań funkcji addHeaderLine. Dzięki tej funkcji każdy wiersz nagłówka pojawia się tylko raz, nawet jeśli blok pola niestandardowego jest używany wiele razy w ramach jednego bloku niestandardowego. Generator kodu blokowego powinien zwrócić pusty ciąg znaków.

Krótkoterminowy generator prądu

Dysponujemy również generatorem, który tworzy kod pośredni generatora dla tego pola. W tym generatorze kodów blokowych będziesz napisać kod, który będzie generować kod, który pomoże użytkownikowi napisać kod generujący kod. Nie wiesz, co zrobić? To łatwiejsze, niż się wydaje!

Fragment generatora bloku niestandardowego zawiera gotową zmienną reprezentującą każde pole w bloku. Kolejnym krokiem jest TODO, który użytkownik musi dokończyć, aby połączyć wszystkie te zmienne w ostateczny ciąg znaków, który zwróci jego niestandardowy blok. Zwykle oznacza to, że generator kodu blokowego musi zwrócić wiersz, który tworzy tę zmienną niestandardową. Załóżmy, że użytkownik tworzy niestandardowy blok, który doda do jego tła promienie słoneczne. Dodają do bryły pole kąta i nadaj mu nazwę "SUN_DIRECTION". Ten blok generatora zawiera wiersz const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. To wiersz kodu, który nasz generator kodu blokowego dla pola kąta zwraca:

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ć ustandaryzowaną nazwę zmiennej, możesz wywołać generator.createVariableName i przekazać typ pola (np. angle, number itp.) wraz z nazwą pola użytkownika.

Przetestuj

Po utworzeniu wszystkich elementów powinno być możliwe uruchomienie Fabryki Bloków, uruchamiając polecenie npm start w katalogu blockly-samples/examples/developer-tools. Powinno być możliwe przeciągnięcie bryły z kategorii pola, dodanie jej do danych wejściowych na bryle i obserwowanie zmiany danych wyjściowych. Sprawdź, czy podgląd bloku wygląda poprawnie i czy kod każdej sekcji wyników jest prawidłowy.