擴充 Microsoft Fabric 前端

發行項
11/24/2024

您可以使用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 中啟用工作負載開發功能

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

工作負載開發租用戶切換的螢幕擷取畫面。

設定前端

若要設定範例專案前端：

確認已安裝 Node.js 和 npm。 npm 安裝必須是版本 9 或更新版本。否則，請安裝最新版本的 Node.js 和 npm。
複製 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伺服器。
  - Web 組態和指令清單讀取器/處理器。
- 驗證：範例會使用 validateSchema.js 來驗證產品和專案 JSON 檔案架構。其設定為在上 npm start執行。
在存放庫資料夾內，移至 Frontend 資料夾以安裝項目檔：
```
<repository folder>\Frontend> npm install
```
執行下列命令來啟動伺服器：
```
<repository folder>\Frontend> npm start
```
此命令會啟動本機Node.js伺服器（使用 webpack），Microsoft Fabric 在開發人員模式中連線到該伺服器。

如需伺服器啟動時所顯示之埠詳細數據的詳細資訊，請參閱本機主機伺服器附註。

目前的連接埠為 60006。

啟動 localhost 伺服器之後，請移至 URL 127.0.0.1:60006/manifests 以開啟在 Frontend/Package 資料夾中建立的匯總指令清單。

如果您變更 Frontend/Package 資料夾內的檔案，請再次執行npm start。

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

“Hello world” 範例

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

啟動本地伺服器（請遵循開始使用中的步驟來執行前端和後端工作負載範例），並確定已啟用開發人員模式。
在工作區功能表上，選取 [ 建立中樞 ] 圖示（有時圖示位於 [顯示更多 省略號] 中。
請選取 看見全部。
在 [範例工作負載] 底下，選取 [範例專案] 卡片以建立專案。

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

主要範例 UI 影像介面的螢幕快照。

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

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

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

例如：

執行 Action 會使用名為 sample 的動作來呼叫 action.execute（） API。動作。此動作的功能是顯示通知。
選取 功能區上的 [儲存 ] 以呼叫 dialog.open（） API。 API 會開啟一個對話框，讓使用者輸入名稱，並將專案儲存在 Fabric 中。如需對話框的詳細資訊，請參閱 CRUD 一節。
[ 取得主題設定 ] 按鈕會顯示網狀架構主題組態清單（透過 theme.get（） API。

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

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() 攔截儲存。
UI 控制件的處理程式會呼叫函式， SampleWorkloadController 並傳遞相關的狀態變數。
為了支援 CRUD 作業，所建立/載入項目的狀態會與承載變數的範例實作一起workspaceObjectId儲存在 artifactItem 中。

下列範例使用 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 會移至中前端指令清單artifactseditor>>path中定義的路由：

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

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

在工作區中開啟現有項目的螢幕擷取畫面。

UPDATE

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

DELETE

您可以在 [網狀架構] 工作區檢視中呼叫 delete 作業，作為所有專案可用的一般動作，或透過從工作負載明確呼叫至 itemCrud.deleteItem。

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

檢視驗證活動

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

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

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

偵錯

若要查看背景工作角色和UI iframe元素，請在瀏覽器中選取 F12 以開啟瀏覽器開發人員工具。 Select the Options tab.

Visual Studio Code 中偵錯檔案的螢幕快照。

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

Fluent UI 控制項

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

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

前端指令清單自定義

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

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

重新整理頁面之後，會實時顯示指令清單專案、動作設定和視覺效果資產更新的變更。

用戶端 SDK 支援的 API

不支援下列 API：

notification.open
notification.hide
panel.open
panel.close
action.onAction
action.execute
navigation.navigate
navigation.onNavigate
navigation.onBeforeNavigateAway
navigation.onAfterNavigateAway
page.open
dialog.openDialog
dialog.openMessageBox
dialog.close
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 套件。

共用方式為

擴充 Microsoft Fabric 前端

必要條件

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

設定前端

“Hello world” 範例

了解程式碼

bootstrap()

index.worker

index.ui

開發流程

CRUD 作業

CREATE

GET

UPDATE

DELETE

檢視驗證活動

偵錯

Fluent UI 控制項

前端指令清單自定義

用戶端 SDK 支援的 API

意見反應

其他資源

共用方式為

擴充 Microsoft Fabric 前端

必要條件

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

設定前端

“Hello world” 範例

了解程式碼

bootstrap()

index.worker

index.ui

開發流程

CRUD 作業

CREATE

GET

UPDATE

DELETE

檢視驗證活動

偵錯

Fluent UI 控制項

前端指令清單自定義

用戶端 SDK 支援的 API

相關內容

意見反應

其他資源