Plugin 套件指南

必要安裝項目

範例專案裡已經有預設安裝

此套件為開發外掛模組的必要安裝項目，包含所有核心功能和工具。

安裝

在外掛模組的 Angular 專案中執行下列指令：

npm install @uofx/plugin

版本相容性對照

版本相容性警告

不同版本可能造成安裝或更新後出現內容錯誤或遺失的狀況。請依照下表確認套件版本與配置檔版本的相容性。

套件版本 (@uofx/plugin)	配置檔版本 (plugin-manifest.json)
4.3.3	112
4.1.0	104

---

功能總覽

類別	說明
UofxPluginPage	用於開發外掛頁面
UofxPluginPanel	用於開發外掛面板
UofxPluginAuthorize	權限控制裝飾器，限制特定使用者才能存取頁面或功能
UofxPluginApiService	透過呼叫 API 提供取得使用者資訊、公司資訊，以及外部連線代理

---

UofxPluginPage

用於開發外掛**頁面**的基底類別，提供路徑與外掛設定存取能力。

匯入

import { UofxPluginPage } from '@uofx/plugin';

可用屬性

屬性名稱	類型	說明
pluginSetting.entryHost	string	外掛模組的根路徑與版本號組合
pluginSetting.pluginCode	string	外掛模組代號
baseUrl.admin	string	管理者大廳路徑 /admin
baseUrl.adminPlugin	string	管理者外掛模組路徑 /admin/plugin/{codePath}
baseUrl.user	string	使用者大廳路徑 /user
baseUrl.userPlugin	string	使用者外掛模組路徑 /user/plugin/{codePath}
baseUrl.appPlugin	string	APP 外掛模組路徑 /home/plugin/{codePath}

使用範例

取得 Entry Host

取得 entryHost 並設定為 API Service 的 Server URL：

import { UofxPluginPage } from '@uofx/plugin';

@Component({
  selector: 'uofx-web-setting',
  templateUrl: './setting-page.component.html'
})
export class SettingPage extends UofxPluginPage implements OnInit {
  constructor(private apiService: APIService) {
    super();
  }

  ngOnInit() {
    this.apiService.serverUrl = this.pluginSetting.entryHost;
  }
}

麵包屑導覽

透過 baseUrl 組合路徑，不必擔心相對路徑問題：

@Component({
  selector: 'uofx-web-setting',
  template: `<uofx-breadcrumb [items]="breadCrumbItems"></uofx-breadcrumb>`
})
export class SettingPage extends UofxPluginPage implements OnInit {
  breadCrumbItems: Array<MenuItem> = [
    { label: '大廳', routerLink: [this.baseUrl.admin] },
    { label: '內容置中' }
  ];

  ngOnInit() {
    console.log(this.baseUrl.adminPlugin);
    // 輸出: /admin/plugin/edesampleplugin
  }
}

---

UofxPluginPanel

用於開發外掛 面板 的基底類別，提供與 UofxPluginPage 相同的路徑與設定屬性。

匯入

import { UofxPluginPanel } from '@uofx/plugin';

可用屬性

與 UofxPluginPage 相同，請參考上方屬性表。

使用範例

取得 Entry Host

import { UofxPluginPanel } from '@uofx/plugin';

@Component({
  selector: 'uofx-web-panel',
  templateUrl: './panel.component.html'
})
export class PanelComponent extends UofxPluginPanel implements OnInit {
  constructor(private apiService: APIService) {
    super();
  }

  ngOnInit() {
    this.apiService.serverUrl = this.pluginSetting.entryHost;
    console.log('目前外掛模組代號:', this.pluginSetting.pluginCode);
  }
}

取得路徑並組合 routerLink

@Component({
  selector: 'uofx-web-panel',
  template: `<a [routerLink]="adminUrl">前往管理頁面</a>`
})
export class PanelComponent extends UofxPluginPanel implements OnInit {
  adminUrl: string;

  ngOnInit() {
    this.adminUrl = this.baseUrl.adminPlugin;
    // 輸出: /admin/plugin/edesampleplugin
  }
}

---

UofxPluginAuthorize

權限控制裝飾器，可限制特定使用者才能存取頁面或執行特定方法。

匯入

import { UofxPluginAuthorize } from '@uofx/plugin';

使用方式

使用方式	語法	說明
類別裝飾器	@UofxPluginAuthorize('FUNCTION_ID')	限制整個元件的存取權限
方法裝飾器	@UofxPluginAuthorize('METHOD_ID')	限制特定方法的執行權限

使用範例

可自訂 functionId 名稱：

@UofxPluginAuthorize({ functionId: 'LOBBY' })
export class LobbyPage extends UofxPluginPage { }

---

UofxPluginApiService

提供外掛模組存取系統資料的 API 服務，包含使用者資訊、公司資訊查詢，以及外部連線代理功能。

匯入

在模組中註冊 provider：

import { UofxPluginApiService } from '@uofx/plugin/api';

@NgModule({
  providers: [UofxPluginApiService]
})
export class YourPluginModule { }

可用方法

方法名稱	參數	回傳類型	說明
getCorpInfo()	無	Observable<CorpInfo>	取得公司基本資訊
getUserInfo(userId)	userId: string	Observable<UserInfo>	取得指定使用者的員工資訊
externalProxy(model)	PlugExternalProxyReqModel	Observable<any>	透過系統代理呼叫外部 API

使用範例

import { UofxPluginApiService } from '@uofx/plugin/api';

@Component({
  selector: 'app-data-component',
  templateUrl: './data.component.html'
})
export class DataComponent implements OnInit {
  empNo: string;
  companyInfo: PlugCorpInfoModel;

  constructor(
    private pluginService: UofxPluginApiService,
    private cdr: ChangeDetectorRef
  ) { }

  ngOnInit() {
    this.loadCorpInfo();
    this.loadSpecificUserInfo();
  }

  /** 取得公司資訊 */
  loadCorpInfo() {
    this.pluginService.getCorpInfo().subscribe({
      next: (corpInfo) => {
        this.companyInfo = corpInfo;
        console.log('公司資訊:', corpInfo);
      }
    });
  }

  /** 載入特定使用者資訊 */
  loadSpecificUserInfo() {
    this.pluginService.getUserInfo('USER001').subscribe({
      next: (userInfo) => {
        this.empNo = userInfo.employeeNumber;
        console.log('使用者員工編號:', this.empNo);
      }
    });
  }
}

---

外部連線代理 (External Proxy)

透過 externalProxy 方法，可在外掛模組中呼叫已在系統設定的外部連線，由系統統一代理轉發，無需在前端暴露 API 的憑證。

PlugExternalProxyReqModel 屬性

屬性名稱	類型	說明
connCode	string	外部連線設定的連線代號
method	'GET' | 'POST' | 'PUT' | 'DELETE'	HTTP 方法
apiUrl	string	實際要呼叫的 API 完整 URL，例如 https://api.example.com/v1/resource
requestBody	string	HTTP 請求內容，為 JSON 格式的字串

使用步驟

步驟 1 — 在 UOF X 新增外部連線設定

請先至 UOF X 的「外部連線設定」功能，建立一筆外部連線設定並取得連線代號（connCode）。

詳細設定方式請參考：外部連線設定說明

搭配 ApiSignatureMiddleware.cs 驗證簽章

範例專案提供的 ApiSignatureMiddleware.cs 可驗證來自 UOF X 的請求標頭。 建立外部連線時，可在 Header 中帶入以下欄位，並搭配 UOF X 內建函式產生對應的值：

Key	Value	說明
x-ClientId	自行命名	可識別的外部系統代號
x-Timestamp	UofxGetUnixTimeMilliseconds()	時間戳記（毫秒）
x-Nonce	UofxGetGuid()	隨機碼，不允許重複使用
x-Signature	UofxEncrypt("{x-ClientId}{x-Timestamp}{x-Nonce}", "HMACSHA512")	HMACSHA512 簽章

步驟 2 — 在外掛模組中呼叫

import { UofxPluginApiService, PlugExternalProxyReqModel } from '@uofx/plugin/api';

export class DataComponent {
  constructor(private pluginService: UofxPluginApiService) { }

  callExternalApi() {
    this.pluginService.externalProxy(<PlugExternalProxyReqModel>{
      connCode: 'MY_CONN_CODE',          // 連線代號
      method: 'POST',                    // GET | POST | PUT | DELETE
      apiUrl: `${this.pluginSetting?.entryHost}/your-api-url`,
      requestBody: JSON.stringify({ key: 'value' })
    }).subscribe({
      next: (result) => console.log('結果:', result),
      error: (err) => console.error('錯誤:', err)
    });
  }
}

---

下一步

回到開發地圖