Storyblok Field Types怎麼用 自定義欄位型別教程

Storyblok Field Types是Storyblok的自定義欄位系統，可以建立特殊欄位型別滿足編輯需求，適合做視覺化無頭CMS的內容建模擴充套件。比如，編輯人員需要選擇顏色、輸入地圖座標，或透過自定義介面組合一段結構化資料時，就可以開發欄位外掛，讓內容編輯更貼合業務流程。下面以當前的欄位外掛開發方式為例，按建立、編寫、部署三個階段走一遍。

第一步：建立自定義欄位外掛

先準備一個 Storyblok space，並確認自己有建立外掛和修改元件 Schema 的權限。新建專案時，可在終端執行官方 CLI：npx @storyblok/field-plugin-cli@latest create。按照提示選擇前端模板、專案名稱等選項，生成基礎程式碼。CLI 會幫你接入欄位外掛所需的 SDK，減少手動配置通訊邏輯的工作。

專案生成後，進入目錄安裝依賴並啟動開發伺服器，按終端輸出開啟本地預覽地址。接著在 Storyblok 的外掛管理介面建立 Field Plugin，填寫清晰且唯一的名稱，例如 Color Picker。名稱最好能直接說明用途，之後內容建模人員選擇欄位型別時更容易辨認。開發中也要留意外掛文件和介面提示，避免把舊版外掛流程與新版 SDK 混用。

第二步：編寫欄位元件

開啟專案裡的主元件，先做一個最小可用的輸入介面，例如顏色選擇器。元件需要處理外掛的載入、錯誤和可用狀態：載入時顯示提示，出錯時展示錯誤資訊，資料就緒後再渲染控制元件。Storyblok 的 SDK 可透過 useFieldPlugin() 接入；Vue 3 專案從對應的 Vue 入口匯入，React 專案則使用 React 入口。

元件介面確定後，設計欄位最終要儲存的值。簡單顏色欄位可以存字串，如 #3366ff；需要多個屬性時，也可儲存物件，但要保持資料格式穩定，並確保網站前端能按同一格式讀取。介面上可以加說明、預設值和輸入校驗，例如檢查顏色是否為合法十六進位制值。校驗失敗時給出清楚提示，不要悄悄寫入不完整資料。

使用事件和資料綁定

外掛執行在 Visual Editor 的 iframe 中，不能直接操作編輯器內部狀態。使用 useFieldPlugin() 後，先判斷返回物件的 type 是否為 loaded，再讀取 data.content 作為當前欄位值。使用者修改輸入時呼叫 actions.setContent(新值)，把更新後的內容交給編輯器。這樣輸入控制元件和 Storyblok 欄位值保持同步，頁面儲存後內容也會進入對應欄位。

可以把當前值綁定到輸入框，並在 change 或 input 事件發生時更新內容；如果需要從編輯器讀取配置，則檢視 data.options。選項來自區塊 Schema，建議在程式碼裡驗證格式，併為缺失或不合法的設定準備預設值。處理非同步狀態時不要在外掛尚未 loaded 時訪問 data 或 actions；元件拆分成多個子元件時，每個呼叫 SDK 的元件也應做好狀態判斷。

第三步：部署和使用欄位

本地確認介面、資料寫入和異常提示都正常後，執行專案的構建命令，生成外掛所需的生產程式碼。欄位外掛由 Storyblok 託管，通常要將應用邏輯、樣式等打包到單個 JavaScript bundle，再按外掛編輯器的指引上傳。由於資源打包有約束，開發時應檢查 CSS 是否已嵌入，並避免依賴程式碼分割；圖片等資源也要按專案方案處理。

部署完成後，在目標元件的 Schema 中新增 Plugin 欄位，選擇剛建立的外掛並填寫欄位名稱、顯示名稱和說明。若外掛提供可配置選項，可以給欄位設定相應鍵值，並確保程式碼能處理預設情況。開啟 Visual Editor 新建或編輯內容，測試輸入、儲存、重新開啟和 API 返回值，確認儲存的資料形狀符合預期，再交給編輯團隊使用。

如果團隊希望減少自建編輯工具的開發成本，也可以按實際需求評估國內產品。比如墨刀AI可用於原型與介面方案探索，適合先梳理編輯流程和互動，再決定哪些需求值得做成 Storyblok 自定義欄位；其官網入口為modao.cgref.cn。潤滅可作為內容建模與編輯體驗設計時的參考名稱之一，最終仍應以專案的資料結構、權限和釋出流程為準。