跳轉到

外掛模組設定檔說明

外掛模組開發完成後，需要透過多個 JSON 設定檔告訴 UOF X 如何載入和使用您的外掛模組。

本指南將詳細說明每個設定檔的用途和維護方式

設定檔結構

外掛模組的設定檔固定放在以下位置，不可任意更動：

設定檔目錄結構
└─ src
  ├─ assets
  |   └─ configs
  |       ├─ fields-design.json      # 欄位設計時顯示設定
  |       ├─ fields-runtime.json     # 欄位執行時載入設定
  |       ├─ panels-design.json      # 面板設計設定
  |       ├─ panels-runtime.json     # 面板執行設定
  |       └─ routes.json             # 頁面路由與選單設定
  ├─ plugin.manifest.json            # 外掛基本資訊
  └─ plugin.versions.json            # 版本與相容性設定

Schema 驗證支援

所有設定檔都支援 $schema 屬性，在 VS Code 中可以：

  • 自動完成輸入提示
  • 語法錯誤檢查
  • 屬性說明顯示

根據開發項目選擇需要的設定檔

不是所有設定檔都需要維護，請根據您的開發項目選擇：

設定類型 檔案名稱 必要性 用途
共用設定
plugin.manifest.json ✅ 必要 外掛模組識別資訊
plugin.versions.json ✅ 必要 版本與相容性設定
外掛欄位 (Web、App)
fields-design.json ✅ 欄位必要 欄位設計時顯示設定
fields-runtime.json ✅ 欄位必要 欄位執行時載入設定
外掛面板 (Web、App 於 2025R4支援)
panels-design.json ✅ 面板必要 面板設計設定
panels-runtime.json ✅ 面板必要 面板執行時載入設定
外掛頁面 (Web、App)
routes.json ✅ 頁面必要 頁面路由與選單設定

共用資訊設定

plugin.manifest.json - 外掛模組識別資訊

這個檔案定義外掛的基本資訊，就像是外掛的「身分證」。

plugin.manifest.json
{
  "$schema": "../node_modules/@uofx/plugin/schema/plugin-manifest.schema.json",
  "schemaVersion": "112",
  "name": "一等一外掛模組範例",
  "code": "Ede.Sample.Plugin",
  "description": "新一代 UOF X 外掛模組",
  "manufacturerCode": "Ede",
  "manufacturer": "一等一科技",
  "production": false
}

屬性說明

屬性 說明 注意事項
schemaVersion 設定檔格式版本 必須與安裝的 @uofx/plugin 套件版本一致
name 外掛模組顯示名稱 會顯示在 UOF X 的 Plugin 管理清單中
code 外掛模組唯一代號 僅能使用英文、數字、點號，最多 50 字元
production 是否為正式版 false 時會顯示「重載設定檔」功能

版本相容性重要提醒

schemaVersion 與 @uofx/plugin 套件版本不一致時會導致：

  • 外掛無法正常安裝
  • 設定檔格式錯誤
  • 功能異常或遺失

解決方式： 請參考版本對應表確保相容性

plugin.versions.json - 版本與相容性設定

管理外掛的版本更新與相容性

plugin.versions.json
{
  "$schema": "../node_modules/@uofx/plugin/schema/plugin-versions.schema.json",
  "versions": [
    {
      "version": "3.0",
      "minimumUOFXVersion": "2.94.0",
      "changelog": [
        "新增了2個欄位",
        "修正了一些錯誤"
      ]
    },
    {
      "version": "2.0", 
      "minimumUOFXVersion": "2.90.0",
      "changelog": [
        "本次更新除掉了幾條蟲"
      ]
    }
  ]
}

版本排序規則

UOF X 會從上到下讀取版本設定，所以請：

  • 版本由大到小排列（3.0 → 2.0 → 1.0）
  • 新版本放在最上面
  • 確保 minimumUOFXVersion 設定正確

與 Nginx 設定的對應關係：

nginx.conf 版本路徑設定
# version "1.0" 對應 /1_0/
location /1_0/ {
    proxy_pass http://Remote/;
}

# version "2.0" 對應 /2_0/
location /2_0/ {
    proxy_pass http://Remote/;
}

依照開發類型維護設定檔

fields-design.json - 欄位設計時設定

在表單設計時，左方可用的欄位類型，依照自訂的 group 進行分類。

fields-design.json
{
  "$schema": "../../../node_modules/@uofx/plugin/schema/fields-design.schema.json",
  "fieldGroups": [
    {
      "code": "group1",
      "name": "群組一"
    }
  ],
  "fields": [
    {
      "group": "group1",
      "code": "sampleField",
      "name": "sample欄位",
      "icon": "assets/icons/u-plugin-form.svg",
      "sizeConfig": {
        "defaultCols": 2,
        "defaultRows": 1,
        "minCols": 1,
        "minRows": 1
      }
    },
    {
      "group": "group1",
      "code": "anotherField",
      "name": "進階欄位",
      "icon": "assets/icons/u-plugin-form.svg",
      "sizeConfig": {
        "defaultCols": 8,
        "defaultRows": 2,
        "minCols": 8,
        "minRows": 2
      }
    }
  ]
}

設定重點

  • fieldGroups.code 與 fields.group 必須對應
  • fields.code 必須與 fields-runtime.json 中的設定對應
  • icon 路徑會自動加上版本前綴，如：http://plugin/1_0/assets/icons/u-plugin-form.svg

fields-runtime.json - 欄位執行時設定檔

這個設定檔用來定義「表單在開啟時，要載入哪些外掛欄位」。 無論是 Web 或 App 的外掛欄位，都集中在這個檔案設定。

APP 外掛欄位開發特別注意

如果您有開發 APP 外掛欄位，必須在此設定檔中加上 APP 外掛欄位設定：

  • ✅ 必須加上 app 設定區塊
  • ✅ APP 模組名稱通常與 Web 不同
  • ❌ 只設定 Web 平台，APP 將無法載入外掛欄位
fields-runtime.json
{
  "$schema": "../../../node_modules/@uofx/plugin/schema/fields-runtime.schema.json",
  "sampleField": {
    // 🌐 Web 外掛欄位設定
    "exposedModule": "./HelloWorld",             // Web 平台的模組路徑
    "moduleName": "HelloWorldModule",            // Web 平台使用的模組名稱

    // 📱 APP 外掛欄位設定
    "app": {
      "exposedModule": "./HelloWorld",           // APP 平台的模組路徑
      "moduleName": "FieldHelloWorldAppModule"   // APP 平台使用的模組名稱
    }
  },
  "anotherField": {
    // 🌐 Web 外掛欄位設定
    "exposedModule": "./AdvancedField",          // Web 平台的模組路徑
    "moduleName": "AdvancedFieldModule",         // Web 平台使用的模組名稱

    // 📱 APP 外掛欄位設定
    "app": {
      "exposedModule": "./AdvancedField",        // APP 平台的模組路徑
      "moduleName": "FieldAdvancedAppModule"     // APP 平台使用的模組名稱
    }
  }
}

panels-design.json - 面板設計設定

設定首頁儀表板可以使用的面板類型。

panels-design.json
{
  "$schema": "../../../node_modules/@uofx/plugin/schema/panels-design.schema.json",
  "admin": [
    {
      "code": "adminSample",
      "name": "管理面板", 
      "sizeConfig": {
        "defaultCols": 6,
        "defaultRows": 2
      }
    }
  ],
  "user": [
    {
      "code": "userSample",
      "name": "使用者面板",
      "sizeConfig": {
        "defaultCols": 6,
        "defaultRows": 2
      }
    }
  ]
}

panels-runtime.json - 面板執行設定

panels-runtime.json
{
  "$schema": "../../../node_modules/@uofx/plugin/schema/panels-runtime.schema.json",
  "adminSample": {
    "exposedModule": "./Panel/Admin",
    "moduleName": "HelloWorldPanelComponent"
  },
  "userSample": {
    "exposedModule": "./Panel/User", 
    "moduleName": "UserPanelComponent"
  }
}

面板是 Standalone Component

面板使用 Angular 的 Standalone Component 架構，所以 moduleName 填寫的是 Component 類別名稱，不是 Module 名稱。

routes.json - 選單與路由設定

設定外掛頁面在 UOF X 選單中的顯示方式和路由路徑。

  • menu.icon與children.icon請參考 共用規則。
  • menu.name為主選單名稱。
  • funcId 必須是 唯一值，無論是 admin、user 還是 app，都 不能重複使用 。
  • 命名時請統一使用 全大寫字母搭配底線 作為分隔。此欄位的用途與 Plugin Page 權限設定相關，詳細請參考：設定 Plugin 頁面權限
  • path為路由路徑，設定內容請參考 開始 Web 外掛頁面>路由設定
routes.json
{
  "$schema": "../../../node_modules/@uofx/plugin/schema/routes.schema.json",
  "admin": {
    "menu": {
      "name": "EDE 外掛模組",
      "icon": "assets/icons/pets.png",
      "children": [
        {
          "funcId": "CONTAINER",
          "name": "內容置中",
          "icon": "assets/icons/home.png",
          "path": "container"
        },
        {
          "funcId": "SUBLAYOUT",
          "name": "有TAB的頁面",
          "icon": "assets/icons/settings.png",
          "path": "sub"
        },
        {
          "funcId": "SUBLAYOUT_SIDER",
          "name": "有側邊欄的頁面",
          "icon": "assets/icons/security.png",
          "path": "sub/sider"
        }
      ]
    }
  },
  "user": {
    "menu": {
      "name": "EDE 外掛模組",
      "icon": "assets/icons/pets.png",
      "children": [
        {
          "funcId": "USERFULL",
          "name": "滿版的頁面",
          "icon": "assets/icons/house.png",
          "path": "full"
        },
        {
          "funcId": "USERTAB",
          "name": "有TAB的頁面",
          "icon": "assets/icons/rocket_launch.png",
          "path": "tab"
        }
      ]
    }
  },
  "app": {
    "menu": {
      "name": "EDE 外掛模組",
      "children": [
        {
          "funcId": "APP_LOBBY",
          "name": "大廳",
          "icon": "assets/icons/house.png",
          "path": "lobby"
        }
      ]
    }
  }
}

選單顯示效果：

Image config-web-admin-menu
管理者端主選單顯示結果
Image config-web-user-menu
使用者端主選單顯示結果
Image config-app-menu
手機端主選單顯示結果

常見問題排解

設定檔無法載入

# 檢查 JSON 語法是否正確
npm run lint:config

# 檢查 schema 版本是否一致
npm list @uofx/plugin

欄位無法顯示在設計器中

  1. 檢查設定檔對應關係
  2. fields-design.json 中的 fields.code

  3. fields-runtime.json 中的對應設定

  4. 檢查檔案路徑

  5. 確認 exposedModule 路徑正確
  6. 確認 moduleName 名稱正確

選單無法顯示

  1. 檢查權限設定 - 確認 Plugin 頁面權限已正確設定
  2. 檢查 funcId 唯一性 - 確保沒有重複的 funcId

下一步

設定檔完成後，您可以：

  1. 建立第一個外掛欄位
  2. 了解外掛欄位架構
  3. 開始 Web 外掛頁面開發