Publikowanie bibliotek blokowych

Wtyczki, które udostępniają biblioteki definicji bloków, to świetny sposób na udostępnianie elementów wielokrotnego użytku społeczności Blockly. Opracowaliśmy te wskazówki, aby Twoja biblioteka blokowa była jak najbardziej wszechstronna i przydatna.

Wytyczne

Ułatwij użytkownikom instalowanie wszystkich bloków i umożliw im instalowanie tylko wybranych bloków lub ich części.
- Ułatwić instalację wszystkich elementów: możesz to zrobić, podając funkcję, która instaluje wszystkie elementy wymagane przez definicję pojedynczego bloku (np. modyfikatory, rozszerzenia, mieszanki, pola itp.). Możesz też udostępnić funkcję jednoczesnego instalowania wszystkich bloków oferowanych przez wtyczkę.
- Umożliwienie wyboru konkretnych części: wszystkie elementy definicji bloku należy eksportować osobno, aby użytkownik mógł zaimportować tylko te części, których potrzebuje do utworzenia własnego podobnego bloku niestandardowego.
Unikaj używania w pluginie efektów ubocznych.
- Bloki, pola, rozszerzenia i inne elementy nie powinny być instalowane jako efekt uboczny wczytywania wtyczki. Użytkownicy powinni mieć kontrolę nad tym, co i kiedy jest instalowane. Dzięki temu użytkownicy mogą importować potrzebne elementy bez obaw, że te, których nie potrzebują, nie zostaną zainstalowane.

Zamiast tworzyć nowe pola bezpośrednio, użyj rejestru pól JSON.

Nie zalecane – utworzenie nowego pola bezpośrednio:

  const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(new Blockly.FieldNumber(123), 'NAME');
    }
  }

Zalecane – rejestr pól JSON:

  export const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(Blockly.fieldRegistry.fromJson({
              name: 'field_number',
              value: 123,
            }), 'NAME');
    }
  }

Rejestr pól ułatwia użytkownikom zastępowanie implementacji pola używanego w bloku bez konieczności zmiany definicji bloku.

Nie zakładaj, że użytkownik ma już zainstalowaną aplikację.
- Jeśli Twoja wtyczka wymaga pola niestandardowego lub innej wtyczki, samodzielnie zarejestruj te pola w dostarczanej funkcji install.
- Wkrótce Blockly udostępni narzędzia, które umożliwią Ci bezbłędną rejestrację już zarejestrowanych produktów. Do tego czasu warto sprawdzić, co zostało już zarejestrowane, zanim samodzielnie zarejestrujesz rozszerzenie, mutator, składankę lub pole.
- Określ wyraźnie wszystkie wymagania wstępne i zależności wymagane przez definicje wtyczki lub bloku.
Zastanów się nad udostępnieniem funkcji generatora dla każdego z bloków.
- Udostępnianie funkcji generatora, które działają od razu po zainstalowaniu, ułatwia użytkownikom korzystanie z bloków bez konieczności zrozumienia ich struktury i projektu. Jeśli będą musieli napisać własne funkcje generatora, może to spowodować zbędne działania po stronie każdego użytkownika.
- JavaScript to najczęściej używany język w Blockly, więc jeśli wybierzesz tylko jeden język, zalecamy JavaScript, chyba że bloki są przeznaczone dla konkretnego języka, np. implementujesz bibliotekę Pythona.
- Rozważ opublikowanie zgłoszeń „Potrzebna pomoc” w przypadku języków, w których nie możesz zaimplementować funkcji generatora, i akceptowanie pull requestów dotyczących tych języków, jeśli użytkownik je prześle.
- Jeśli dla bloku podasz funkcję instalacji, możesz zaakceptować opcjonalny parametr generators. Jeśli użytkownik przekaże instancję generatora, którą obsługujesz, możesz automatycznie zainstalować funkcję generatora kodu blokowego i wykonywać powiązane czynności, takie jak dodawanie słów zarezerwowanych:
```
  // Your plugin's install function
  export const installMyCustomBlock(generators = {}) {
    Blockly.defineBlocks({my_custom_block: myCustomBlock});
    if (generators.javascript) {
      generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
      generators.javascript.addReservedWords('specialReservedWord');
    }
  }

  // How a user may install your block
  import {javascriptGenerator} from 'blockly/javascript';
  import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
  // installs the block definition and the javascript block-code generator
  installMyCustomBlock({javascript: javascriptGenerator});
```

Prześlij opinię

Jeśli masz pytania dotyczące tego, jak najlepiej przestrzegać tych wytycznych w pluginie, daj nam znać na forum. Chętnie poznamy Twoje biblioteki bloków i nasze opinie na ich temat.

Pamiętaj, że nie wszystkie wtyczki własne z definicjami blokad są obecnie zgodne z tymi wytycznymi, ale nowe wtyczki będą tak robić i planujemy migrację już istniejących.