引言
本頁說明在核心 Blockly 中呼叫函式及存取屬性的最佳做法。這些原則適用於建立 Blockly 的外掛程式，或是將 Blockly 整合至獨立應用程式。
子類別和擴充
Blockly 有多個可新增功能的模式，包括：
- 子類別 (例如建立新的轉譯器)
- Mixins (例如新增區塊擴充功能或變動器)
- 區塊定義 (例如程序區塊定義)
就本文件的目的而言，這三種情況都等同於子類別。
插入子類別
我們支援透過 Blockly.inject 方法取代特定類別。這些子類別必須擴充基本類別，或是實作對應的介面。
您可以將子類別傳遞至插入方法。
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
或者，您也可以使用 Blockly.registry 註冊類別，並使用註冊資料庫名稱插入類別。如果您要將插入選項儲存為純 JSON 格式，這項功能就能派上用場。
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
您可以替換下列類別：
| 註冊名稱 | 介面/基礎類別 |
|---|---|
blockDragger |
Blockly.IBlockDragger |
connectionChecker |
Blockly.IConnectionChecker |
connectionPreviewer |
Blockly.IConnectionPreviewer |
flyoutsVerticalToolbox |
Blockly.IFlyout |
flyoutsHorizontalToolbox |
Blockly.IFlyout |
metricsManager |
Blockly.IMetricsManager |
renderer |
Blockly.blockRendering.Renderer |
toolbox |
Blockly.IToolbox |
若要進一步瞭解如何使用介面，請參閱說明文件的「介面」一節。
能見度
我們使用 TypeScript 存取修飾符，將核心程式庫中的瀏覽權限標示為 public、private 或 protected。部分屬性可能會在 TsDoc 註解中使用 @internal 加註。
所有 public 和 protected 屬性皆記錄在 Blockly 網站的「參考資料」部分。您也可以透過讀取程式碼來確認瀏覽權限。
公開
任何標示 public 的項目都是我們公用 API 的一部分。模組中沒有瀏覽權限修飾符的任何屬性都會視為公開。
我們會嘗試不常變更公用 API，或在沒有理由和警告的情況下頻繁變更。例外狀況：我們可能會在其中一個版本中公開新的 API，並根據早期意見回饋在下一個版本中進行修改。之後，您可能會想考慮公開函式或屬性穩定版。
您可以從任何位置呼叫公開函式，並在簽章未變更的情況下覆寫子類別中的公開函式。
受保護的
受保護的函式和屬性只能由定義的類別或子類別存取。
子類別可在不變更類型簽章的情況下覆寫受保護的函式和屬性。
舉例來說，擴充基本轉譯器類別的自訂轉譯器可能會存取其受保護的屬性。
無論是哪種情況，請務必瞭解如何在程式碼的其餘部分使用該函式或屬性。
私人
只能透過與定義位於相同檔案中的程式碼存取。直接存取這些屬性可能會導致未定義的行為。
子類別不得覆寫不公開函式和屬性。
私人屬性可能會在不事先通知的情況下變更，因為這些屬性不屬於 Blockly 公用 API 的一部分。
Blockly 中的某些函式沒有瀏覽權限註解，因為這類函式不會從模組中匯出。這些函式基本上是本機變數，無法用於定義模組之外。這些屬性應視為等同於私人屬性。
內部
內部函式和屬性應用於核心程式庫中，但不要在外部使用。這些註解會標有 TsDoc @internal 註解。
內部屬性可能會在不事先通知的情況下隨時變更，因為這些屬性並不會被視為 Blockly 公用 API 的一部分。
內部屬性可從核心內的任何位置存取，且只要簽名未變更，即可在核心中的子類別覆寫該屬性。也不得從核心程式庫外部存取。
已淘汰
不得使用標示 @deprecated 的任何項目。大部分淘汰項目都會在主控台警告或 TSDoc 中納入偏好程式碼的指示。
如果可能，已淘汰的函式會記錄警告，其中包含預計刪除日期，以及建議呼叫的替代函式。
常見問題
如果我想使用的函式未公開，該怎麼辦？
提出核心 Blockly 的功能要求。加入使用案例的說明，以及您希望我們公開的內容說明。
我們會利用這項功能要求，討論是否要設為公開，或者透過其他方式取得相同的資訊。
如果我們決定公開發布，您或 Blockly 團隊就會做出適當的變更，並在下一個 Blockly 版本中發布。
如果您選擇在外掛程式中使用非公開成員，建議您將外掛程式標示為 Beta 版，並在 README 中加入資訊。
猴子修補呢？
查看猴子修補。
Monkeypatching 不安全，因為使用 Blockly API 的非公開 API ，修補程式可能會在未事先通知的情況下停止運作。外掛程式中的修補作業特別具有危險性，因為您的程式碼可能會與 Monkeypatch 相同的其他任何外掛程式互動不良互動。因此，我們強烈建議不要在應用程式和第三方外掛程式中使用 Monkeypatch，也不會在第一方外掛程式中接受該方法。
我可以覆寫公開函式嗎？
設定子類別時：是。否則，那就是猴子修補。
我可以覆寫受保護的函式嗎？
設定子類別時：是。否則，那就是猴子修補。
我可以覆寫內部或私人函式嗎？
不，那是猴子修補吧。
何時可以直接存取資源？何時該使用 getter 或 setter？
如要發布 getter 或 setter，請使用該 getter 或 setter，不要直接存取屬性。如果屬性不公開，請務必使用 getter 和 setter。
如果屬性沒有註解，該怎麼辦？
這項資訊預設為公開，但請放置一行，以便我們為您放置 getter/setter 配對。
如果函式沒有註解，該怎麼辦？
這項決定預設為公開。
如果還是不確定，該怎麼辦？
歡迎前往論壇提問，我們會在一個工作天內回覆您。