插件開發者指南
介紹
從 1.5 版本開始，可以透過將插件檔案放置在插件資料夾中，為Sweet Home 3D新增功能。這使得 Java 程式設計師能夠在不修改目前版本原始碼檔案（有利於向上相容）且不發布完整版程式（有利於減少程式體積）的情況下，開發和分發 Sweet Home 3D 的新功能。
本文檔介紹了創建插件所需的工具，然後展示瞭如何編寫一個插件來計算添加到房屋中的可移動家具的最大體積，最後提供了一些額外的信息，以幫助您進一步了解。
安裝開發工具
如果《甜蜜家園3D》面向的是一般使用者群體，那麼開發插件就需要特殊技能，您應該掌握如何使用整合開發環境（IDE）進行Java程式設計。在繼續之前，請注意以下事項。本指南示範如何使用Eclipse建立插件，但您可以使用您選擇的任何 IDE，或完全不使用 IDE。
下載並安裝 Eclipse
首先從https://www.eclipse.org/下載 Eclipse。名為「Eclipse IDE for Java Developers」的版本足以開發插件，但您可以下載任何版本用於 Java 開發。
下載完成後，安裝 Eclipse 非常簡單：只需解壓縮得到的壓縮包，打開 eclipse 資料夾，然後根據您的系統執行名為 .eclipse 的檔案即可。 eclipse.exe （在Windows系統下） eclipse.app （在 Mac OS X 系統下） eclipse （在 Linux 系統下）
首次運行時，Eclipse 會要求您選擇一個工作區資料夾，插件專案將儲存在該資料夾中。
完成後，選擇“文件”>新的>從選單中選擇“項目”以建立新項目，然後選擇Java>在新項目精靈中，選擇Java 項目，輸入項目名稱 VolumePlugin，然後按一下「完成」按鈕。最後，關閉「歡迎」選項卡，即可查看如圖 1 所示的工作區。
下載並安裝 Sweet Home 3D 庫
插件的開發是基於 Sweet Home 3D 的一些類，Eclipse 必須識別這些類別才能建立您的專案。將 Sweet Home 3D 類別新增至 Eclipse 的最簡單方法是從https://sourceforge.net/projects/sweethome3d/files/SweetHome3D/SweetHome3D-7.5/SweetHome3D-7.5.jar/download下載 Sweet Home 3D 的 JAR 可執行版本。下載完成後，將 SweetHome3D-7.5.jar 檔案拖曳到 Eclipse 的「套件資源管理器」視圖中的VolumePlugin專案圖示上，然後選擇「建置路徑」項目。>如圖 2 所示，在 SweetHome3D-7.5.jar 檔案的上下文功能表中將其新增至建置路徑。
建構路徑
編寫插件程式
現在你已經安裝了所需的工具，讓我們來看看如何為 Sweet Home 3D 編寫你的第一個外掛程式。
創建插件類
首先，選擇「檔案」選單，建立 com.eteks.sweethome3d.plugin.Plugin 的新子類別。>新的>Eclipse 中的類別選單項目。
在「新建 Java 類別」對話方塊中，輸入類別名稱 VolumePlugin，輸入套件名稱（此處選擇的套件為 com.eteks.test），並將 com.eteks.sweethome3d.plugin.Plugin 設定為 VolumePlugin 的父類別。完成後，按一下“完成” 。 Eclipse 將建立新類別的文件，其內容如下：
package com.eteks.test;
import com.eteks.sweethome3d.plugin.Plugin;
import com.eteks.sweethome3d.plugin.PluginAction;
public class VolumePlugin extends Plugin {
@Override
public PluginAction[] getActions () {
// TODO 自動產生的方法存根
返回空值；
}
}
如 TODO 註解所示，您現在必須修改 getActions 方法的實現，使其傳回一個能夠計算可移動家具體積的插件操作。將 return null; 替換為以下語句：
返回新的PluginAction [] {新的VolumeAction ()};
並選擇版本>使用 Eclipse 選單中的快速修復功能建立缺少的類別 VolumeAction，如圖 4 所示。
在出現的「新 Java 類別」對話方塊中，選取「封閉類型」複選框以建立 VolumePlugin 的內部類，然後按一下「完成」 。這將建立繼承自 com.eteks.sweethome3d.plugin.PluginAction 類別的 VolumeAction 類，包含一個空的 execute 方法：
public class VolumeAction extends PluginAction {
@Override
public void execute () {
// TODO 自動產生的方法存根
}
}
當使用者啟動插件操作時，Sweet Home 3D 將呼叫此方法；因此，您必須在此處實現如何計算家具的體積並顯示它：
public class VolumeAction extends PluginAction {
@Override
public void execute () {
float volumeInCm3 = 0;
// 計算邊界框的體積總和
家中每件可移動的家具
for (PieceOfFurniture piece : getHome (). getFurniture ()) {
如果 ( piece.isMovable ()) {
volumeInCm3 += piece.getWidth ()
* piece.getDepth()
* piece.getHeight ();
}
}
// 在訊息方塊中顯示結果（\u00b3 表示 3 的上標）
String message = String.format (
“家中可移動家具的最大體積為%.2f m⁻³。”
體積（立方公分）/ 1000000);
JOptionPane。 showMessageDialog （空，訊息）；
}
}
既然您已經指定了插件的功能，接下來必須描述使用者如何啟動此新操作。您可以選擇在選單中新增選單項，或在工具列中新增按鈕。這可以透過在建立插件操作時設定相應的屬性來實現。例如，如果您希望使用者透過「工具」選單中的「計算音量」選單項目來啟動音量操作，則需要為 VolumnAction 類別新增下列建構子：
public VolumeAction () {
putPropertyValue (Property.NAME, "計算體積");
putPropertyValue (Property.MENU, "工具");
// 預設啟用此操作
設定啟用（true）；
}
VolumePlugin插件類別已經編寫完成，幾乎可以作為 Sweet Home 3D 的插件使用了。最後還有兩件事要做：
- 建立ApplicationPlugin.properties描述文件，
- 將檔案合併到一個 JAR 檔案中。
建立插件描述文件
ApplicationPlugin.properties文件 描述外掛名稱、外掛程式類別、支援的 Sweet Home 3D 和 Java 最低版本要求； 以及法律相關內容。選擇文件>新的>文件來自 在 Eclipse 選單中，輸入檔名ApplicationPlugin.properties ，然後按一下「完成」 ，如圖所示。 如圖 5 所示。
然後在新文件中輸入以下描述並儲存：
名稱=可移動家具體積
類=com.eteks.test.VolumePlugin
描述= 計算家中可移動家具的體積
版本= 1.0
授權= GNU GPL
提供者= (C) 版權所有 2024 Space Mushrooms
applicationMinimumVersion = 1.5
javaMinimumVersion = 1.5
建立插件 JAR 文件
該插件 JAR 檔案包含由VolumePlugin.java檔案編譯產生的類別文件， 以及ApplicationPlugin.properties檔案。由於 Eclipse 會在您儲存 Java 檔案後立即進行編譯，因此您只需選擇“文件”即可。從選單中選擇“匯出…” ，然後選擇Java匯出對話框中的JAR 文件將顯示出來。在圖 6 所示的Jar 匯出精靈中，選擇項目檢查。 在方塊中輸入位於 Sweet Home 3D 外掛程式資料夾中的 JAR 檔案路徑。此資料夾取決於 在您的系統中如下操作：
- 在 Windows Vista / 7 / 8 / 10 / 11 系統中，此資料夾位於C:\Users\使用者\AppData\Roaming\eTeks\Sweet 首頁 3D\插件，
- 在 Windows XP 及更早版本的 Windows 系統中，此資料夾位於C:\Documents and Settings\使用者\Application Data\eTeks\Sweet 首頁 3D\插件，
- 在 macOS 系統中，它位於Library/Application Support/eTeks/Sweet Home 3D/ plugins子資料夾中。 使用者資料夾
- 在 Linux 和其他 Unix 系統中，它是使用者資料夾下的子資料夾.eteks/sweethome3d/ plugins 。
測試插件
您開發的外掛程式可以在 Sweet Home 3D 中運行，無論是Java Web Start版本、安裝程式版本，還是您先前下載的SweetHome3D-7.5.jar檔案。由於最新版本是可執行 JAR 文件，您可以透過雙擊運行它，或使用以下命令運行它：
您開發的外掛程式可以在 Sweet Home 3D 中運行，無論是Java Web Start版本、安裝程式版本，還是您先前下載的SweetHome3D-7.5.jar檔案。由於最新版本是可執行 JAR 文件，您可以透過雙擊運行它，或使用以下命令運行它：
java -jar /path/to/SweetHome3D-7.5.jar
只要你在進行測試，你可能更喜歡用這個命令運行 Sweet Home 3D，以便在控制台中讀取插件執行期間拋出的異常的堆疊追蹤。
啟動 Sweet Home 3D 後，您將看到如圖 7 所示的新選單及其專案：
如果您選擇在使用者指南中建立的「首頁」範例中的新選單項，您將得到以下結果：
偵錯插件
如果您需要在 Eclipse 中偵錯插件，請按照以下步驟建立偵錯配置：
- 選擇運行>從選單中選擇“調試配置…” ，然後在可用配置清單中選擇“Java 應用程式”項目。 在「偵錯組態」對話方塊中，按一下左上角的「新建」按鈕，然後輸入組態名稱。
- 點選主類別文字欄位右側的「搜尋…」按鈕，然後雙擊SweetHome3DBootstrap類
在所提議的類別中。
- 點選「類別路徑」選項卡，在「類別路徑」清單中選擇「使用者條目」項目的「VolumePlugin（預設類別路徑）」子項，然後點選「刪除」按鈕。
- 點選類別路徑清單中的「使用者條目」項，點選「新增 JAR…」按鈕，選擇 SweetHome3D-7.5.jar 項並確認您的選擇。
- 選擇「來源」選項卡，按一下「新增…」按鈕，在「新增來源」對話方塊中雙擊「Java 項目」項，在「專案選擇」彈出視窗中選擇「VolumePlugin」項目並確認您的選擇。
- 最後，點擊「調試」按鈕，以調試模式啟動 Sweet Home 3D。程式運行後，打開VolumePlugin.java文件，在execute方法中設定斷點，然後選擇「工具」。從 Sweet Home 3D 選單計算體積。 Eclipse 將在選定位置停止。 設定斷點，即可逐步執行程式並檢查變數值。
每次修改插件原始程式碼後，請務必在啟動建立的偵錯配置之前產生插件 JAR 檔案。為了加快 Eclipse 中的 JAR 匯出速度，請前往 JAR 匯出精靈的第二步，並選擇「將此 JAR 的描述儲存到工作區」選項。這將在專案中新增項，其中包含一個上下文選單項目「建立 JAR」 。
部署插件
準備好後，您只需將插件複製到其他 Sweet Home 3D 用戶的插件資料夾中，即可將插件部署到他們的電腦上。從 1.6 版本開始，如果插件檔案的副檔名為 .sh3p（只需將檔案副檔名從 .zip 變更為 .sh3p），也可以透過雙擊該檔案將其安裝到 Sweet Home 3D 的插件資料夾中。如果您雙擊 .sh3p 檔案無法啟動 Sweet Home 3D（在 Linux 系統下這種情況很常見），您還可以使用以下命令在終端機視窗中安裝插件（其中 SweetHome3D （是 Sweet Home 3D 安裝程式提供的可執行檔的名稱）：
/path/to/ SweetHome3D /path/to/plugin.sh3p
要停止使用某個插件，請從插件資料夾中刪除該插件的文件，然後重新啟動 Sweet Home 3D。
如果您希望您的外掛程式能夠與本網站提供的所有Sweet Home 3D 安裝程式相容，請確保其與 Java 5 相容，方法是選擇…1.5在「專案」對話方塊的「Java 編譯器」部分中的「編譯器相容等級」欄位中。> Eclipse 的「屬性」選單項目。
如果您使用的 Java 編譯器版本不再相容於 Java 1.5，請嘗試使用至少 Java 1.8，Sweet Home 3D 的最新版本仍然使用 Java 1.8。javaMinimumVersion在ApplicationPlugin.properties請相應地修改您的插件檔案。
更進一步
第一個插件的程式設計已經向您展示了整體框架。以下是一些補充信息，將有助於您進一步學習。
Sweet Home 3D API – Javadoc
開發新插件最有用的文件是使用 javadoc 工具產生的Sweet Home 3D API （應用程式介面）。
如果您希望外掛程式向上相容未來版本的 Sweet Home 3D，請僅使用com.eteks.sweethome3d.plugin 、 com.eteks.sweethome3d.model 、 com.eteks.sweethome3d.tools和com.eteks.sweethome3d.viewcontroller套件中的類別。這足以滿足任何基於 Sweet Home 3D 中提供的房屋數據的插件的程式需求。
程式其他層對應的軟體包資訊僅供參考，請勿依賴其 API，因為其未來可能會發生變化，且無法保證向上相容性（無論如何，您在上述軟體包中都不會看到對com.eteks.sweethome3d.swing 、 com.eteks.sweethome3d.j3d 、 com.eteks .
模型類別架構
Sweet Home 3D 是基於 MVC（模型-視圖-控制器）架構，因此了解其模型層的組織結構至關重要。圖 13（也提供PDF 版本）展示了com.eteks.sweethome3d.model套件 1.5 版本中與該模型層相符的幾乎所有類別和介面。
(click on a class to view its javadoc)
模型層的核心類別是HomeApplication類別 (10)，它是SweetHome3D應用程式主類別的抽象超類別。此類別的實例可以存取目前正在編輯的Home實例 (7)，以及儲存目前使用的長度單位(12)、家具目錄(14) 和紋理目錄(15) 的使用者偏好設定物件 (11)，使用者可以從中選擇家具(17) 和紋理(18)。
Home實例 (7) 儲存使用者在住宅方案中所建立的所有物件：
- 實作了PieceOfFurniture介面 (16) 的HomePieceOfFurniture物件 (13) 的列表，
- 牆壁物品收藏（9），
- 房間物件列表（5），
- DimensionLine物件集合（2），
- Label物件集合（3）。
這些物件實作了Selectable介面 (1) 以及ObserverCamera物件 (4)，後者儲存虛擬訪客模式下攝影機的位置。所有由 Model 物件管理的外部信息，例如家具的圖標和 3D 模型 (16) 或紋理圖像 (20)，都透過Content介面 (19) 訪問，該介面由URLContent類別和com.eteks.sweethome3d.tools包中的其他類別實現。
這張 UML 圖應該可以幫助您了解 Sweet Home 3D 模型中有哪些類別以及如何存取它們，但您可能會注意到圖中沒有列出建構函數和修改器（或者如果您喜歡，也可以稱為設定器）。這只是因為空間有限，但您可以在插件類別中毫無問題地使用它們。另請注意，對模型現有物件的任何修改都會透過PropertyChangeEvent 、 CollectionEvent (8) 或SelectionEvent (6) 通知到顯示的元件，從而使所有變更都能立即反映在螢幕上。
出於效能考慮，Sweet Home 3D 模型並非線程安全。對該模型物件的所有修改都應在事件分發執行緒中進行。
插件類別架構
插件類別的架構比模型層的架構更容易理解。 com.eteks.sweethome3d.plugin套件僅包含三個類別，其中您只需要使用Plugin和PluginAction類，如圖 14 所示（也可查看PDF 版本）。
(click on a class to view its javadoc)
應用程式啟動時會建立一個PluginManager實例 (1)，該實例會搜尋使用者插件資料夾中已安裝的插件。每次編輯新主頁時，該管理器都會為啟動時找到的每個插件實例化並配置一個Plugin物件 (3)。然後，它會呼叫getActions方法來檢索所有將作為選單項目和/或工具列按鈕新增至主頁視窗的動作(4)。每個操作都是PluginAction的實例，其結構類似Action類，包含execute方法和可修改的屬性(2)。
請注意， Plugin類別透過其getUndoableEditSupport方法允許您存取UndoableEditSupport實例。一旦您在PluginAction實例的 execute 方法中修改了房屋或其物件（家具、牆壁等），您也應該將UndoableEdit物件提交給 getUndoableEditSupport 方法傳回的 UndoableEditSupport 實例，否則使用者將無法正確撤銷/重做您所做的變更。
本土化
如果您打算為 Sweet Home 3D 使用者社群開發插件，請嘗試在地化插件中顯示的操作名稱、選單或您建立的對話方塊中的字串（或至少準備好在地化內容）。 PluginAction 類別的兩個建構子可以幫助您使用 .properties 檔案組織操作屬性的翻譯。如果您需要翻譯外掛程式中的其他字串（例如測試外掛程式中顯示的對話方塊），請使用ResourceBundle Java 類別重複使用這些 .properties 檔案。
如果您希望限制屬性檔案的數量，您甚至可以將操作屬性和其他字串的值寫入插件的 ApplicationPlugin.properties描述檔中。
如果您想要一個使用此架構的範例，請從https://www.sweethome3d.com/plugins/ExportToSH3F-1.0.sh3p下載Export to SH3F插件，並解壓縮它（此外掛程式檔案還包含插件的原始程式碼）。
如同在幫助論壇中所述，此外掛程式會建立一個 SH3F 文件，其中包含您在 Sweet Home 3D 家具目錄中匯入的所有家具。
貢獻插件
您可以將您編寫的插件發佈到插件貢獻追蹤系統中，與 Sweet Home 3D 用戶社群分享。
透過插件，Sweet Home 3D 可以添加許多功能，從導入器到導出器，還可以添加能夠修改房屋數據的插件，例如 Michel Mbem 開發的Home Rotator 插件，以及 Hans Dirkse 編寫的《插件和擴展教程》 （PDF）和“插件和工具”頁面中列出的其他插件。