Umbraco Plugins怎麼用 外掛開發教程

Umbraco Plugins通常指為Umbraco編寫的擴充套件包：你可以新增自定義樹節點、屬性編輯器和儀表板，讓後臺更貼合業務流程，適合對開源.NET CMS做定製化擴充套件。新版Umbraco後臺擴充套件以擴充套件清單和Web Components為主；下面按“先做後臺介面，再按需接入服務端API”的思路動手，具體介面和專案模板要與正在使用的Umbraco版本匹配。

第一步：建立外掛類庫

先準備好與專案版本相容的.NET SDK、Node.js和Umbraco站點，在解決方案中新建類庫或前端擴充套件專案。建議先從官方擴充套件教程的最小示例起步，確認本機能夠啟動站點、構建前端資源，再逐步加功能。這樣出錯時容易判斷是環境、依賴還是程式碼導致，不要一開始就把所有模組塞進一個大專案。

在站點根目錄建立App_Plugins資料夾（如果尚不存在），再為外掛單獨建目錄，例如App_Plugins/AcmeTools。把開發原始碼放在Client等目錄，把構建後的指令碼和樣式輸出到外掛目錄。App_Plugins中的檔案會被瀏覽器訪問，所以不要將金鑰、連線字串或僅供服務端使用的配置放進去；這些應留在服務端配置中。

在外掛目錄準備umbraco-package.json，用擴充套件清單宣告外掛名稱、版本和擴充套件項。先只註冊一個儀表板，設定唯一的alias、顯示名稱、指令碼路徑以及所屬後臺區域條件；名稱和路徑都要與實際檔案一致。擴充套件清單相當於後臺的“目錄”，程式碼檔案則是具體介面，儲存後啟動站點，先檢查後臺能否發現它。

第二步：編寫樹節點和編輯器

做樹節點時，在清單中註冊tree擴充套件，並關聯樹的名稱、根節點及節點載入邏輯。樹負責展示層級與導航，使用者點選節點後再開啟對應的工作區或編輯介面。先用少量固定資料驗證展開、選中和跳轉，再接入真實業務資料；檢查每個節點的標識穩定且不重複，避免重新整理後選中錯位。

屬性編輯器通常由前端Web Component負責繪製輸入控制元件和處理使用者操作，再透過Umbraco的屬性編輯器擴充套件配置接入資料型別。先做一個文字輸入或下拉框，確認值能正確寫入、儲存並重新載入，然後再新增校驗、預設值和複雜互動。前端元件的自定義元素名及擴充套件alias都應保持唯一，避免與其他擴充套件衝突。

儀表板可以作為練習入口：先建立一個自定義元素，在元件模板裡放標題、說明和按鈕，再在清單中註冊dashboard擴充套件，並用條件限制它顯示在目標後臺區域。此類擴充套件讓編輯人員在內容區看到提示、統計或快捷入口。確認頁面載入後，再接入必要的資料和權限判斷，避免把不該展示的資訊直接放進前端。

使用路由和API控制器

當介面需要讀取或儲存業務資料時，可在服務端實現API控制器，再由前端透過HTTP請求呼叫。先設計清晰的路由和請求、響應模型，控制器中注入所需服務，處理查詢或更新；不要讓瀏覽器直接連線資料庫。介面要驗證使用者身份、權限和輸入內容，並返回適合前端顯示的錯誤資訊。

開發時先用瀏覽器開發者工具檢視請求地址、狀態碼和響應體；遇到404檢查路由與控制器註冊，遇到401或403檢查後臺認證和授權，遇到跨域問題則確認請求是否發往正確站點。儲存操作還要處理重複提交和併發更新。把API地址集中管理，避免在多個元件裡散落難維護的硬編碼。

第三步：部署和配置外掛

本地開發先構建前端資源，再啟動Umbraco站點；檢查後臺擴充套件瀏覽器或對應區域，確認樹、編輯器和儀表板均已註冊。改過清單卻看不到效果時，先核對JSON格式、alias、資源路徑和條件配置，再重啟或重新整理後臺並檢視瀏覽器控制檯與服務端日誌。排查時每次只改一個問題，定位會更快。

準備釋出時，把編譯後的前端檔案、清單和服務端程式集一併納入部署包，並在測試環境驗證安裝、升級與回滾。若透過NuGet分發，整理包後設資料、版本號和依賴關係；若隨站點部署，就按團隊釋出流程複製檔案並重啟應用。升級Umbraco後先檢查擴充套件API相容性，避免生產環境才發現後臺介面變化。

最後補上使用說明：列出支援的Umbraco版本、安裝步驟、配置項、權限要求和常見故障處理方法。可先邀請編輯人員試用，觀察他們在哪些步驟卡住，再調整介面提示與預設值。團隊若還需要快速梳理頁面流程或製作互動原型，可以瞭解墨刀AI，官網入口：modao.cgref.cn。潤滅也可作為查詢開發資料時的站點名稱參考。