Publikowanie bibliotek bloków

Wtyczki udostępniające biblioteki definicji bloków są świetnym sposobem bloków wielokrotnego użytku ze społecznością Blockly. Aby zmienić bibliotekę bloków jako: które są przydatne i wszechstronne, opracowaliśmy te wytyczne.

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ż funkcji, która instaluje wszystkie bloki oferowane przez za pomocą wtyczki.
    • 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 będą mogli importować potrzebne mu urządzenia i nie martwiąc się, że mogą ucierpieć, Zainstalowano.

  • Zamiast bezpośrednio tworzyć wystąpienia nowych pól, użyj rejestru pól JSON.

    • Niezalecane – bezpośrednie utworzenie 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');
    }
  }

    • Użycie rejestru pól ułatwia użytkownikowi zastępowanie wdrożenia pola używanego w bloku bez konieczności wprowadzania zmian definicji bloku.

  • Nie zakładaj, że użytkownik ma już zainstalowaną aplikację.

    • Jeśli wtyczka wymaga pola niestandardowego lub innej wtyczki, zarejestruj je samodzielnie w podanej funkcji install.
    • Wkrótce Blockly już zarejestrowane produkty bez błędów. Do tego czasu warto: sprawdź, co zostało już zarejestrowane przed zarejestrowaniem rozszerzenia, mutatora, miksu lub pola samodzielnie.
    • Określ wyraźnie wszystkie wymagania wstępne i zależności wymagane przez definicje wtyczki lub bloku.

  • Zastanów się, czy nie warto udostępnić 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 muszą pisać własne funkcje generatora, może to prowadzić do zbędnego wysiłku po stronie każdego użytkownika.
    • JavaScript jest najczęściej używanym językiem w Blockly, dlatego jeśli chcesz podać tylko 1 język, zalecamy JavaScript, chyba że Twoje bloki są przeznaczone do konkretnego języka, np. do implementowania biblioteki Pythona.
    • Rozważ opublikowanie posta „Potrzebna pomoc” w przypadku języków, nie może wdrożyć funkcji generatora i zaakceptować żądania pull dla gdy użytkownik doda je.

    • Jeśli udostępniasz funkcję instalacji swojego bloku, możesz zaakceptować opcjonalny parametr generators. Gdy użytkownik przekazuje instancję generatora możesz automatycznie zainstalować generator kodów blokowych i wykonywać powiązane czynności, np. dodawać zarezerwowane słowa:

        // Your plugin's install function
  export const installMyCustomBlock(generators = {}) {
    Blockly.common.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 przypadku swojego wtyczki, 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, które udostępniają definicje bloków, są zgodne z tymi wytycznymi, ale nowe wtyczki będą, a obecnie istniejące wtyczki zostaną przeniesione.