Publikowanie bibliotek blokowych

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

Wytyczne

• Zadbaj o to, aby użytkownicy mogli ułatwić instalowanie wszystkich bloków, a także umożliwić im instalowanie tylko wybranych bloków.
  • Zapewnij łatwość instalacji: możesz to zrobić, udostępniając funkcję instalującą każdy element definicji pojedynczego bloku (np. mutatory, rozszerzenia, składanki, pola itp.). Możesz też udostępnić funkcję, która zainstaluje wszystkie bloki dostępne przez wtyczkę.
  • Musisz mieć możliwość wyboru konkretnych części: wszystkie elementy definicji bloków należy wyeksportować oddzielnie, aby użytkownik mógł zaimportować tylko te elementy, których potrzebuje do utworzenia własnego, podobnego bloku niestandardowego.
• Unikaj stosowania efektów ubocznych we wtyczce.
  • Bloków, pól, rozszerzeń i innych elementów nie należy instalować jako efekt uboczny ładowania wtyczki. Użytkownicy powinni kontrolować, które elementy są instalowane i kiedy. Dzięki temu użytkownicy będą mogli importować potrzebne im elementy bez obawy, że elementy, których nie potrzebują, zostaną zainstalowane.

• Zamiast tworzyć instancję nowych pól bezpośrednio, użyj rejestru pól JSON.

  • Niezalecane – bezpośrednie tworzenie instancji nowego pola:

      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żytkownikowi zastąpienie implementacji pola używanego w bloku bez konieczności zmiany definicji bloku.

• Nie należy sugerować, co użytkownik zainstalował.

  • Jeśli wtyczka wymaga pola niestandardowego lub innej wtyczki, zarejestruj te pola samodzielnie w udostępnionej funkcji install.
  • Wkrótce Blockly udostępni narzędzia, które pozwolą Ci bezbłędnie rejestrować już zarejestrowane elementy. Do tego czasu możesz sprawdzić, co zostało już zarejestrowane, zanim zarejestrujesz rozszerzenie, mutator, składankę lub pole tekstowe.
  • Jasno określ wszelkie wymagania wstępne i zależności wymagane przez wtyczkę lub definicje bloków.

• Rozważ udostępnienie funkcji generatorów dla każdego z dostarczanych przez siebie bloków.

  • Udostępnienie gotowych funkcji generatorów ułatwia użytkownikom korzystanie z bloków bez konieczności poznania ich struktury i budowy. Jeśli użytkownik będzie musiał napisać własne funkcje generatora, może to spowodować, że każdy użytkownik wykona nadmiarowe czynności.
  • Najczęściej używanym językiem w Blockly jest JavaScript. Jeśli więc wybierzesz tylko jeden język, zalecamy stosowanie JavaScriptu, chyba że bloki są tworzone dla konkretnego języka, np. do implementacji biblioteki Pythona.
  • Rozważ opublikowanie problemów z poszukiwaną pomocą w przypadku języków, w których nie możesz zaimplementować funkcji generatora, i zaakceptuj żądania pull,

  • Jeśli podasz funkcję instalacji blokady, możesz zaakceptować opcjonalny parametr generators. Jeśli użytkownik przekazuje obsługiwaną przez Ciebie instancję generatora, możesz automatycznie zainstalować tę funkcję i wykonać powiązane czynności, na przykład dodawać zarezerwowane słowa:

      // 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, jak postępować zgodnie z tymi wytycznymi we wtyczce, daj nam znać na forum. Chętnie zapoznamy się z Twoimi bibliotekami blokowymi i przekażemy Ci opinie na ich temat.

Pamiętaj, że nie wszystkie wtyczki własne, które podają definicje blokad, są obecnie zgodne z tymi wytycznymi, ale planujemy przenieść istniejące wtyczki.