外掛欄位屬性設定¶

外掛欄位可透過屬性設定與 UOF X 系統深度整合，包含簽核站點、條件站點、欄位計算、表單主旨、匯出、搜尋條件與上傳檔案等功能。

初始化設定¶

設定時機點¶

欄位屬性設定建議於 Angular 元件的 ngOnInit() 生命週期階段執行。

透過繼承基底元件 BpmFwPropsComponent，可使用 this.pluginUtils.initPluginSettings() 方法進行欄位屬性初始化。

基本使用方式¶

initPluginSettings() 支援彈性配置，可依需求選擇性設定參數：

props.component.ts - 完整設定範例

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeNodes: [{ name: '職務代理人', jsonPath: 'agent' }],               // 簽核站點
    toBeConditions: [{ name: '類別名稱', jsonPath: 'categoryName', type: 'Text' }], // 條件站點
    toBeCalculates: [{ name: '總金額', jsonPath: 'total' }],              // 欄位計算
    toBeSubjects: [{ name: '總金額', jsonPath: 'total' }],               // 表單主旨
    toBeExports: [{ name: '總金額', jsonPath: 'total' }],                // 表單匯出
    searchContentJsonPath: 'productName',                              // 搜尋條件
    fileJsonPath: ['attachments']                                      // 上傳檔案
  });
}

避免重複初始化¶

重要提醒

為避免初始化重複執行，建議在 exProps 尚未被設定 的情況下呼叫 initPluginSettings()：

避免重複初始化的範例

ngOnInit() {
  this.initExProps();
}

initExProps() {
  if (!this.exProps) {
    // 首次初始化時執行
    this.pluginUtils.initPluginSettings({
      toBeConditions: [...],
      toBeNodes: [...]
    });
  } else {
    // 已有設定時的處理邏輯
    // ...
  }
}

注意事項

當 exProps 已存在時，initPluginSettings() 將不會再次執行，導致新的設定無法生效。

解決方式： 若需重新初始化欄位屬性設定，請將該欄位自表單畫布中 移除並重新加入。

屬性設定說明¶

簽核站點 (toBeNodes)¶

將欄位值作為簽核站點，需搭配 User Select 選人元件使用。

設定完成後，在流程簽核站點的設定中，即可勾選「來自外掛欄位」並顯示可供選擇的選項。

簽核站點設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeNodes: [{ name: '職務代理人', jsonPath: 'agent' }]
  });
}

條件站點 (toBeConditions)¶

將欄位值作為條件站點時，需要額外提供 type 參數，系統會依據目標值的類型顯示不同的條件選項。

支援的類型：

Type	說明	適用情境
`Text`	文字	產品名稱、備註等文字欄位
`Numeric`	數值	金額、數量等數字欄位
`Department`	部門	部門選擇相關欄位
`Employee`	人員	人員選擇相關欄位

條件站點設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeConditions: [
      { name: '類別名稱', jsonPath: 'categoryName', type: 'Text' },
      { name: '申請金額', jsonPath: 'amount', type: 'Numeric' }
    ]
  });
}

欄位計算 (toBeCalculates)¶

讓 UOF X 提供的標準欄位「欄位計算」能夠選取外掛欄位的 value。

欄位計算設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeCalculates: [{ name: '總金額', jsonPath: 'total' }]
  });
}

表單主旨 (toBeSubjects)¶

設定後可在表單主旨設定中選擇該欄位作為主旨變數，動態產生主旨文字。

表單主旨設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeSubjects: [{ name: '總金額', jsonPath: 'total' }]
  });
}

表單匯出 (toBeExports)¶

由於欄位 value 本身為巢狀結構，而 Excel 檔案為平面表格形式，因此須將欲匯出的資料攤平成一般文字或數值格式。

舉例來說，若在使用者端「表單查詢」的匯出功能中，需要包含總金額 total 欄位，則必須在 initPluginSettings 中設定 toBeExports 參數。

表單匯出設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeExports: [{ name: '總金額', jsonPath: 'total' }]
  });
}

搜尋條件 (searchContentJsonPath)¶

設定後，可在使用者端的「表單查詢」中查詢指定欄位的內容。

搜尋條件設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    searchContentJsonPath: 'productName'  // 產品名稱可被搜尋
  });
}

上傳檔案 (fileJsonPath)¶

若表單中有使用上傳元件，必須設定對應的欄位，系統的檔案複製功能才會正確運作。

將協助系統正確識別並處理檔案欄位，例如在表單轉派或複製時保留檔案內容。

可同時設定多個欄位，對應多個上傳元件。

上傳檔案設定

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    fileJsonPath: ['attachments', 'docs']  // 支援多個檔案欄位
  });
}

實務範例¶

單層欄位值設定¶

props.component.ts - 單層屬性

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeSubjects: [{ name: '代理人', jsonPath: 'agent' }]
  });
}

write.component.ts - 對應的值變更

onFormValueChange() {
  const value = { agent: this.form.value.agent };
  this.valueChanges.emit(value);
}

多層屬性設定¶

若欄位值位於物件結構中（例如：product.name），可將 jsonPath 設定為對應的巢狀屬性路徑。

props.component.ts - 多層屬性

ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeSubjects: [{ name: '產品名稱', jsonPath: 'product.name' }]
  });
}

write.component.ts - 對應的巢狀結構

onFormValueChange() {
  const value = {
    product: {
      name: '產品名稱'
    }
  };
  this.valueChanges.emit(value);
}

隱藏值作為屬性¶

可以指定任何填寫 jsonPath 的位置為相對應隱藏值的名稱。

例如表單主旨中可選日期範圍 dateRange，並在 write 元件中儲存特殊組合：

隱藏值範例 - 日期範圍組合

// props.component.ts
ngOnInit() {
  this.pluginUtils.initPluginSettings({
    toBeSubjects: [{ name: '日期範圍', jsonPath: 'dateRange' }]
  });
}

// write.component.ts
form: FormGroup;

constructor(private fb: FormBuilder) {
  this.form = this.fb.group({ dateRange: [''] });
}

onDateChange() {
  // 組合開始和結束日期
  const startDate = '2023/06/08 9:00';
  const endDate = '2023/06/08 18:00';
  const combinedRange = `${startDate}~${endDate}`;

  this.form.get('dateRange')?.setValue(combinedRange);
  this.valueChanges.emit(this.form.value);
}

顯示結果： 2023/06/08 9:00~2023/06/08 18:00

下一步¶

回到開發地圖