外掛程式

外掛程式是一組獨立的程式碼，可為 Blockly 新增功能。舉例來說，您可以新增自訂欄位、定義新主題或提供自訂轉譯器。外掛程式通常會透過 npm 進行封裝及發布。

注意： BlocklyOptions 物件具有 plugins 屬性，可用於插入自訂 Blockly 行為 的類別。雖然這些類別可實作為外掛程式，但這並非必要，且兩者之間沒有關聯。

如需外掛程式的簡介，請參閱「外掛程式總覽講座 (2021 年)」。

如要建立自己的外掛程式，請參閱「新增外掛程式」一文。

第一方和第三方外掛程式

第一方外掛程式由 Blockly 團隊支援，並在 npm 的 @blockly 範圍下發布。這些元件可用於各式各樣的 Blockly 應用程式。

第三方外掛程式則由獨立的維護者維護及發布。這些應用程式可能較複雜、較實驗性，或僅適用於較狹窄的 Blockly 應用程式。

尋找外掛程式

• 請造訪 Blockly 外掛程式和示範，查看第一方外掛程式的即時示範。

• 在 npm 中搜尋 keyword:blockly-plugin。範圍為 @blockly 的外掛程式由 Blockly 團隊發布。如要取得更廣泛的結果，請搜尋 keyword:blockly 或 blockly。

• 請參閱 GitHub 上的 blockly-samples/plugins 目錄，這是第一方外掛程式的存放區。每個外掛程式都有一個說明文件，說明其行為和預期用途。

安裝外掛程式

建議您使用 npm 或 yarn 等套件管理工具安裝外掛程式。這樣一來，您就能輕鬆接收更新。

• 使用套件管理工具安裝外掛程式

  npm

  npm install @blockly/field-angle
  

  紗線

  yarn add @blockly/field-angle
  

• 在沒有套件管理員的情況下安裝外掛程式

  unpkg

  <script src="https://unpkg.com/@blockly/field-angle"></script>
  

  您也可以複製包含外掛程式的 GitHub 存放區。對於第一方外掛程式，則為 blockly-samples。

請查看外掛程式的 README，瞭解是否有其他安裝說明。

使用外掛程式

每個外掛程式都不同，因此請參閱外掛程式的 README，瞭解如何使用該外掛程式。以下範例說明如何使用 @blockly/field-angle 外掛程式：

1. 匯入外掛程式中的程式碼。這取決於您安裝外掛程式的方式。

   npm 或 yarn

   import Blockly from 'blockly';
   import {registerFieldAngle} from '@blockly/field-angle';
   

   unpkg

   您不需要使用 import 陳述式。

   已複製的存放區

   import {registerFieldAngle} from 'path/to/plugin';
   

2. 視需要初始化外掛程式。提供自訂欄位的外掛程式通常需要您註冊欄位：

   registerFieldAngle();
   

3. 使用外掛程式。

   Blockly.common.defineBlocksWithJsonArray([
     {
       type: "my_angle_block",
       message0: "%1 degrees",
       args0: [
         {
           // Use @blockly/field-angle.
           type: "field_angle",
           name: "FIELDNAME",
           value: 45,
         },
       ],
       output: null,
       style: 'math_blocks'
     },
   ]);
   

   

外掛程式版本

blockly-samples 中的外掛程式會使用語意化版本編號，這需要破壞性變更才能使用新的主要版本。任何猴子修補程式核心的新外掛程式都會具有 0 的主要版本，以表示初始開發。

大多數外掛程式會將 blockly 套件納入為 peerDependency，而非 dependency。這是因為我們假設您已安裝 Blockly。(如果不使用 Blockly 就使用外掛程式，就沒有意義)。這可讓您自行管理 Blockly 版本，但您也必須檢查外掛程式的 package.json，以判斷所需的 Blockly 最低版本。如果外掛程式更新後需要新版 Blockly，系統會將其視為破壞性變更，並提高主要版本。

在應用程式的 package.json 中新增外掛程式時，預設會在版本前方加上反尖號：

"dependencies": {
  "@blockly/field-angle": "^5.0.12"
}

這樣一來，npm 就能安裝列出的版本或更高版本的次要版本，因此 5.0.20 或 5.1.0 版本可正常運作，但 6.0.1 等新的主要版本則無法運作。更新至 Blockly 新版本時，建議您檢查是否有任何外掛程式可更新至新的主要版本。