擴充 Microsoft Fabric 前端

您可以使用Microsoft網狀架構工作負載開發工具包來建置工作負載，並建立可擴充網狀架構體驗的自定義功能。 網狀架構平台的設計目的是與獨立軟體廠商 （ISV） 功能互通。 例如，您可以使用專案編輯器，在 Fabric 工作區專案的內容中內嵌 ISV 的前端，以建立原生且一致的用戶體驗。

在本文中，您會使用 Microsoft Fabric 工作負載開發範例存放庫 作為整合自定義 UX 工作負載 Web 應用程式與 Microsoft Fabric 的指南。 項目和詳細範例可協助您順暢地將自己的UI元件和動作整合到 Fabric 執行時間環境中，以有效率的實驗和自定義。

範例 UX 工作負載專案前端是標準 React Web 應用程式，其中包含工作負載用戶端 SDK 作為標準 npm 套件，以提供功能。

ISV 會在 Fabric 入口網站中的沙盒化 <iframe> 元素內裝載並執行專案。 它呈現ISV特定的UI體驗，包括專案編輯器。

SDK 提供所有必要的介面、API 和啟動程式函式，這些函式需要將一般 Web 應用程式轉換成可在網狀架構入口網站中順暢運作的微前端 Web 應用程式。

SDK 提供範例 UX 工作負載專案。 範例：

• 展示如何使用大部分可用的 SDK 呼叫。
• 示範以 Fluent UI 為基礎、符合 Fabric 外觀與風格的可擴充功能區範例。
• 允許輕鬆自定義。
• 可讓您在開啟 Fabric 開發人員模式時即時觀察 Fabric 中的變更。

必要條件

• UX 工作負載 Web 應用程式

  此套件建置在 Fluent UI 之上，專為 React 所設計。

• UX 工作負載前端資訊清單

  UX 工作負載前端指令清單是ISV提供的 JSON 資源。 檔案包含工作負載的基本資訊，包括工作負載 Web 應用程式的 URL，以及各種 UI 詳細數據，例如 ISV 專案的顯示名稱和相關聯的圖示。 ISV 可以使用指令清單檔來自定義使用者在 Fabric 入口網站中與項目互動時會發生什麼情況。

在此套件中，前端資訊清單檔案位於 套件 資料夾中。 指令清單檔案包含工作負載指令清單及其元件的詳細描述。

在 Fabric 中啟用工作負載開發功能

租戶管理員必須先在租戶設定中啟用工作負載開發功能。 此功能可以針對整個組織或組織內的特定群組啟用。 對於租用戶系統管理員，若要啟用特定群組的工作負載開發功能，請完成啟用開發租用戶設定中所述的步驟。

設定前端

若要設定範例專案前端：

1. 確認已安裝 Node.js 和 npm。 npm 安裝必須是版本 9 或更新版本。 否則，請安裝最新版本的 Node.js 和 npm。

2. 複製 Microsoft Fabric 工作負載開發範例存放 庫。

   下列清單描述套件目錄設定、元件和資源：

   • 套件：工作負載套件的位置。 套件包含前端資源，包括資訊清單和資源檔案。
   • src：工作負載程序代碼，其中包含下列資源：
     • index.ts：主要初始化檔案，包括 bootstrap 和 index.worker 和 index.ui iFrames（請參閱本文稍後的詳細數據）。
     • App.tsx：此檔案負責將路徑導向至頁面。 例如，/sample-workload-editor會被路由至 components 下的 SampleWorkloadEditor 函式。
     • assets：可在資訊清單中參照並顯示於 UI 中的影像檔案位置（.jpg、.jpeg 和 .png）。 例如， assets/github.jpg 在指令清單中設定為產品圖示。
     • 元件：UI 程式代碼的位置，包括編輯器檢視和其他範例所使用的檢視（功能區、驗證頁面和面板）。
     • 控制器：控制器會呼叫 SDK API。
     • models：供 UI 使用並用於與樣板後端通訊的合約和模型。
   • 工具：可用來建立設定和組態的元素。
     • webpack.config.js：使用此檔案來設定本機Node.js伺服器。
     • 網頁組態與資訊清單讀取器/處理器。
   • 驗證：範例會使用 validateSchema.js 來驗證產品和專案 JSON 檔案架構。 其已設定為在 npm start 上執行。

3. 在存放庫資料夾內，移至 Frontend 資料夾以安裝項目檔：

   <repository folder>\Frontend> npm install
   

4. 執行下列命令來啟動伺服器：

   <repository folder>\Frontend> npm start
   

   此命令會使用 webpack 啟動一個 本機 Node.js 伺服器，Microsoft Fabric 處於開發人員模式時會連線到此伺服器。

   如需伺服器啟動後顯示的連接埠詳細資訊，請參閱 localhost 伺服器說明。

   目前的連接埠為 60006。

   localhost 伺服器啟動後，請前往 URL 127.0.0.1:60006/manifests，以開啟在 Frontend/Package 資料夾中建立的彙總資訊清單。

   如果您修改 npm start 資料夾中的檔案，請再次執行 。

   此設定會保存在目前瀏覽器中。

   

“Hello world” 範例

若要執行 「hello world」 測試案例：

1. 啟動本地伺服器（請遵循開始使用中的步驟來執行前端和後端工作負載範例），並確定已啟用開發人員模式。

2. 在工作區功能表上，選取 [ 建立中樞 ] 圖示 （有時圖示位於 [顯示更多 省略號] 中。

   

3. 請選取 看見全部。

   

4. 在 範例工作負載 底下，選取 範例項目 卡片以建立項目。

   

新項目看起來類似下列範例：

探索各種控件，以查看 Fabric WorkloadClient API （工作負載 SDK） 功能：

• 開啟通知和對話框
• 移至頁面
• 取得主題和工作負載設定
• 執行動作

大部分可用的 SDK 功能都會設定為按鈕動作，或註冊為回呼。 結果通常是通知或消息框，顯示已叫用 API。

例如：

• 執行動作 會呼叫 action.execute() API，並使用名為 sample.Action 的動作。 此動作的功能是顯示通知。

• 選取功能區中的儲存以呼叫 dialog.open() API。 API 會開啟一個對話框，讓使用者輸入名稱，並將專案儲存在 Fabric 中。 如需對話框的詳細資訊，請參閱 CRUD 一節。

• [ 取得主題設定 ] 按鈕會顯示網狀架構主題組態清單（透過 theme.get（） API。

範例工作負載UI裝載於網頁開發人員模式中顯示的 Fabric 沙盒化 iframe 元素中。

注意

沙箱化 iframe 項目支援 屬性 allow-same-origin 和 allow-scripts。

如需沙盒和屬性的詳細資訊，請參閱 MDN Web Docs。

了解程式碼

下列各節說明程式代碼元素和相關考慮。

bootstrap()

啟動程序之前，檢查路徑，確認是否需要關閉此視窗。 如果您使用 驗證 API，則需要此步驟。

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
    window.close();
}

每個網狀架構工作負載應用程式都必須支援兩種模式的初始化：

• UI 模式：UI 模式中的應用程式會在可見的 iFrame 中載入。 它會監聽自身的路由變更，以渲染對應的 UI 元件，例如頁面、面板和對話方塊。

• 背景工作模式：背景工作模式中的應用程式會在隱藏的 iFrame 中執行。 不可見的 iFrame 主要用來接收外部命令，然後響應它們。

@ms-fabric/workload-client API 提供bootstrap()方法來簡化初始化步驟。 bootstrap() 方法會在內部偵測目前應用程式是否以 UI 模式或背景工作模式載入。 然後它會呼叫適當的初始化方法 （initializeUI 或 initializeWorker）。 初始化完成時， bootstrap() 通知 Fabric 微前端架構初始化成功或失敗。

bootstrap({
    initializeWorker: (params) =>
        import('./index.worker').then(({ initialize }) => initialize(params)),
    initializeUI: (params) =>
        import('./index.ui').then(({ initialize }) => initialize(params)),
});

index.worker

index.worker 是主要的 onAction 登錄項目。 它會處理 Fabric 主機傳送的事件，這些事件是由執行動作所觸發。

這些動作可由工作負載傳送至 Fabric，然後呼叫回 onAction 處理程式，或可由 Fabric 主機起始。 例如，當您選取 [ 建立範例專案 - 僅限前端] 時，Fabric 會觸發動作 open.createSampleWorkloadFrontendOnly，而 onAction 處理程式會起始開啟工作負載主要 UI 頁面。 目前的工作區 objectId 值也會傳遞至僅限前端的體驗。

序列會顯示在下列程式代碼範例中：

   workloadClient.action.onAction((message) => {
        switch (message.action) {
            /**
             * This opens the frontend-only experience, so you can experiment with the UI without using CRUD operations.
             * You can still save the item if the backend is connected and registered.
             */
            case 'open.createSampleWorkloadFrontendOnly':
                const { workspaceObjectId: workspaceObjectId1 } = data as ItemCreateContext;
                return workloadClient.page.open({
                    workloadName: 'Org.WorkloadSample',
                    route: {
                        path: `/sample-workload-frontend-only/${workspaceObjectId1}`,
                    },
                });

                // . . . elided for brevity . . .
            default:
                throw new Error('Unknown action received');
        }
    });

index.ui

initialize() 函式會轉譯內嵌 App 函數的 React DOM。 若要叫用 API 呼叫，請傳遞 workloadClient SDK 控制代碼，此控制代碼會在整個程式碼中使用。

FluentProvider 類別確保各種 FluentUI 控制之間的樣式一致性。 以下是範例：

ReactDOM.render(
      <FluentProvider theme={fabricLightTheme}>
           <App
               history={history}
               workloadClient={workloadClient}
           />
       </FluentProvider>,
       document.querySelector("#root")
   );

開發流程

• App 函式會將程式碼路由至 SampleWorkloadEditor。 此函式會為 React.JSX.Element 傳回一個值。
• 函式包含UI結構。 UI 結構包含功能區和頁面控件，例如按鈕和輸入欄位。
• 從使用者收集到的資訊會透過 React useState() hook 儲存。
• UI 控制項的處理常式會呼叫 SampleWorkloadController 函式，並傳遞相關的狀態變數。
• 為了支援 CRUD 作業，所建立/載入項目的狀態會與 承載變數的範例實作一起artifactItem儲存在 workspaceObjectId 中。

下列範例使用 notification.open（） API：

• 狀態：

     const [apiNotificationTitle, setNotificationTitle] = useState<string>('');
     const [apiNotificationMessage, setNotificationMessage] = useState<string>('');
  

• UI：

  這些範例會設定特定的 UI 元素：

  • 標題:

    <Field label="Title" validationMessage={notificationValidationMessage} orientation="horizontal" className="field">
        <Input size="small" placeholder="Notification Title" onChange={e => setNotificationTitle(e.target.value)} />
      </Field>
    

  • 傳送按鈕：

    <Button icon={<AlertOn24Regular />} appearance="primary" onClick={() => onCallNotification()} > Send Notification </Button>
    

  • 處理常式：

    function onCallNotification() {
      ... elided for brevity
       callNotificationOpen(apiNotificationTitle, apiNotificationMessage, undefined, undefined, workloadClient, setNotificationId);
    };
    

• 控制器：

    export async function callNotificationOpen(
      title: string,
      message: string,
      type: NotificationType = NotificationType.Success,
      duration: NotificationToastDuration = NotificationToastDuration.Medium,
      workloadClient: WorkloadClientAPI,
      setNotificationId?: Dispatch<SetStateAction<string>>) {
  
      const result = await workloadClient.notification.open({
          notificationType: type,
          title,
          duration,
          message
      });
      if (type == NotificationType.Success && setNotificationId) {
          setNotificationId(result?.notificationId);
      }
  }
  

CRUD 作業

雖然可以輕鬆支援僅限前端開發案例，但完整的端對端開發人員體驗需要儲存、讀取和編輯現有的工作負載項目。

後端 實作指南 詳細說明如何設定和使用後端。

當後端啟動並執行且 Org.WorkloadSample.SampleWorkloadItem 類型已在 Fabric 中註冊時，您可以在此類型上執行 CRUD 作業。

下列作業會使用 ItemCrud API 公開。

CREATE

若要對 create 進行範例呼叫，請使用下列範例，其中示範如何首次儲存工作負載項目：

 const params: CreateItemParams = {
        workspaceObjectId,
        payload: { itemType, displayName, description, workloadPayload: JSON.stringify(workloadPayload), payloadContentType: "InlineJson", }
    };
 const result: CreateItemResult = await workloadClient.ItemCrud.createItem(params);

我們的範例實作會將建立的項目儲存在 中 artifactItem。

專案會在目前選取的工作區中建立。 工作區必須指派給後端組態中設定的容量。 如需更多資訊，請參閱後端文件。

嘗試在不相容的工作區下建立項目失敗：

• 後端中的 onCreateFabricItem 回呼會阻塞 CREATE 呼叫。 此時失敗會導致作業失敗，而且 Fabric 中不會建立任何專案。 如需詳細資訊，請參閱後端的偵錯和疑難解答檔。

• 目前，儲存的項目不會自動出現在工作區中。 若要在工作區中檢視已儲存的專案，請重新整理頁面。

GET

當您在工作區檢視中選取現有的範例工作負載項目時，Fabric 會前往 artifacts>editor>path 中前端資訊清單所定義的路由：

"items": [
  {
   "name": "Org.WorkloadSample.SampleWorkloadItem",
   "editor": {
    "workload": "Org.WorkloadSample",
    "path": "/sample-workload-editor"
   },

當您叫 itemCrud.getItem用 時，會從網狀架構後端和工作負載後端載入數據。 來自這兩個來源的數據會載入至 artifactItem 開啟 GUI 的物件。

更新

若要更新現有的專案，請使用 itemCrud.updateItem。 工作負載承載會由工作負載後端更新。 在 Fabric 中，更新後只有該項目的 lastModifiedTime 會變更。

刪除

您可以在 Fabric 工作區檢視中呼叫 delete 作業，作為適用於所有項目的一般動作，或透過工作負載對 itemCrud.deleteItem 進行明確呼叫。

這兩種類型的呼叫都會經過工作負載後端的 onDeleteItem 回呼。

檢視驗證活動

在範例工作負載編輯器中，您可以檢視驗證活動。

使用驗證 API 之前，請先將應用程式設定為使用 Microsoft Entra ID 進行驗證。

也請確定您的 env.dev 檔案已正確設定。 如需詳細資訊，請參閱 設定工作負載本機資訊清單，並為您的應用程式取得權杖。

偵錯

若要查看背景工作程序和 UI iframe 元素，請在瀏覽器中按 F12 以開啟瀏覽器開發人員工具。 選取 來源 索引標籤。

您可以在 worker iframe 元素中設置中斷點，並查看傳入的動作上的主要 switch。 您也可以對 UI iframe 元素進行偵錯。 例如，您可以對 內的 SampleWorkloadEditor程式代碼進行偵錯。

Fluent UI 控制項

UX 工作負載使用 Fluent UI 控制項，以與 Fabric 保持視覺一致性，並簡化開發。 範例工作負載專案提供如何使用最常見控件的範例。

如需詳細資訊，請參閱 Fluent UI。

前端資訊清單自訂

前端指令清單描述工作負載的前端層面，包括產品外觀、名稱、視覺資產和可用動作。 前端指令清單是 Fabric 與工作負載之間的主要接觸點。

在我們的範例工作負載中，指令清單會以開發人員模式載入 Fabric。 指令清單區段、定義和指令清單範例會顯示在前端指令清單檔案中。

重新整理頁面後，對資訊清單項目、動作設定及視覺資產更新所做的變更會即時顯示。

用戶端 SDK 支援的 API

支援下列 API：

• 開啟通知
• 隱藏通知
• 面板.開啟
• panel.close
• action.onAction
• action.execute
• navigation.navigate
• navigation.onNavigate
• navigation.onBeforeNavigateAway
• navigation.onAfterNavigateAway
• page.open
• dialog.openDialog
• dialog.openMessageBox
• 對話方塊.關閉
• theme.get
• theme.onChange
• settings.get
• settings.onChange
• errorHandling.openErrorDialog
• errorHandling.handleRequestFailure
• itemCrud.createItem
• itemCrud.getItem
• itemCrud.updateItem
• itemCrud.deleteItem
• itemSchedule.runItemJob
• itemSchedule.cancelItemJob
• itemRecentRuns.open

如需詳細資訊，請參閱 @ms-fabric/workload-client 套件。

相關內容

• 工作負載開發工具包概觀
• 後端組態指南