發布區塊程式庫

提供方塊定義程式庫的外掛程式，是與 Blockly 社群分享可重複使用的方塊的絕佳方式。為了讓您的區塊程式庫盡可能多用途且實用，我們制定了以下規範。

指南規範

讓使用者輕鬆安裝所有區塊，並讓使用者自行決定只安裝特定區塊或區塊片段。
- 讓一切都易於安裝：您可以提供可安裝單一區塊定義所需的每個部分 (例如變異器、擴充功能、混合、欄位等) 的函式。您也可以提供函式，一次安裝外掛程式提供的所有區塊。
- 讓使用者能夠選擇特定部分：您應分別匯出區塊定義的所有部分，這樣使用者就可以只匯入他們所需的部分，以便建立自己的類似自訂區塊。
請勿在外掛程式中使用副作用。
- 請勿將區塊、欄位、擴充功能和其他元件視為載入外掛程式的副作用而安裝。使用者應自行控管何時安裝哪些內容。這樣一來，使用者就能匯入所需的元件，而不必擔心不會安裝所需的元件。

請使用 JSON 欄位註冊表，而非直接例項化新欄位。

不建議使用 - 直接例項化新欄位：

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

建議 - JSON 欄位註冊：

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

使用欄位註冊功能後，使用者就能更輕鬆地取代區塊中使用的欄位實作，而無需變更區塊定義。

請勿對使用者已安裝的內容做出假設。
- 如果外掛程式需要自訂欄位或其他外掛程式，請在您提供的 install 函式中自行註冊這些欄位。
- Blockly 很快將提供工具，讓您在不發生錯誤的情況下註冊已註冊的項目。在此之前，建議您先檢查已註冊的項目，再自行註冊擴充功能、變換器、混合器或欄位。
- 明確指出外掛程式或區塊定義所需的任何必要條件或依附元件。
建議您為每個提供的區塊提供產生器函式。
- 提供立即可用的產生器函式，讓使用者可以更輕鬆地使用區塊，而無須瞭解其結構和設計。如果他們必須編寫自己的產生器函式，這可能會導致每位使用者都進行重複的工作。
- JavaScript 是 Blockly 中最常用的語言，因此如果您只選擇其中一種語言，建議您使用 JavaScript，除非您針對實作 Python 程式庫等特定語言建構區塊。
- 針對您無法導入產生器函式的語言，考慮發布「需要協助」問題，並接受使用者提供的相關拉取要求。
- 如果您為區塊提供安裝函式，可以接受選用的 generators 參數。如果使用者傳遞您支援的產生器例項，您可以自動安裝區塊程式碼產生器函式，並執行相關工作，例如新增保留字：
```
  // 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});
```

意見回饋

如果您對於如何在外掛程式中遵守這些規範有任何疑問，歡迎前往論壇與我們聯絡！我們很樂意查看您的方塊程式庫，並提供相關意見回饋。

請注意，並非所有提供區塊定義的第一方外掛程式都遵循這些規範，但新外掛程式會遵循這些規範，我們也打算遷移現有外掛程式。