創建新的布料物品

這份完整指南教你如何利用 Extensibility Toolkit 在 Microsoft Fabric 中建立自訂項目。你可以根據自己的偏好和經驗程度在兩種方式中做選擇。

先決條件

在製作客製化物品前，請確保你具備：

✅ 完成設定指南，並擁有可運作的開發環境
✅ 你的工作負載是在本地執行，並且可以在 Fabric 中存取
✅ 熟悉 TypeScript 和 React（用於自訂）

選擇你的方法

AI輔助方法（建議新手開發者使用）

使用 GitHub Copilot 可以互動式引導你完成整個流程。適合：

針對剛開始使用 Fabric Extensibility Toolkit 的開發者
學習平台模式與最佳實務
工作時獲得解釋和指導

🛠️ 手動腳本化方法（建議有經驗的開發者使用）

使用自動化的 PowerShell 腳本來快速設定。適合：

熟悉工具包結構的開發者
有效率地製作多件物品
生產工作流程與自動化

🤖 人工智慧輔助之物品製作

開始使用 GitHub Copilot

GitHub Copilot 可以依照所有最佳實務，引導你建立完整的自訂 Fabric 項目。 AI 了解擴充套件工具的模式，並會幫助您正確地實施。

有效的範例提示

以下是經過驗證的題目，能幫助你開始創作物品：

基本道具製作：

@fabric create a new item called MyDataReport that shows data analysis reports

具體要求：

@fabric create a custom item for managing data pipelines with these features:
- Pipeline configuration interface
- Status monitoring dashboard  
- Error handling and retry logic

包含 OneLake 整合的複雜項目：

@fabric create an item called DataExplorer that:
- Browses OneLake files in the left panel
- Shows file preview in the center
- Saves user preferences and settings

AI 協助的典型過程

AI 輔助方法遵循以下迭代模式：

1. 初步規劃階段

AI 會分析你的需求
建議物品結構與組成部分
制定包含待辦事項的發展計畫

2. 元件產生

建立四檔模式（定義、編輯器、空、色帶）
實作正確的 TypeScript 介面
設定 Fluent UI 元件

3. 功能實作

新增你專屬的功能
與 Fabric API 整合
實施正確的錯誤處理

4. 測試與精進

在你的開發環境中測試該項目
能解決發現的任何問題
優化效能與使用者體驗

與 AI 助理合作

先從明確的要求開始：

I want to create a [ItemType] item that [primary purpose]. 
The item should have [list key features].
Users should be able to [list main actions].

反覆與精煉：

The item looks good, but I need to add [specific feature]

How can I integrate this with OneLake storage?

Can you add error handling for when the API is unavailable?

詢問說明：

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

AI 協作的最佳實務

具體說明：提供明確的要求與背景
檢視每個步驟：在進行前先了解所產生的程式碼
提問：請為你不懂的模式尋求解釋
頻繁測試：每次重大變更後執行並測試該項目
追蹤進度：請求修正及改進

AI 開發工具與環境

此資料庫與 AI 配對程式設計工具搭配得非常出色。無論你是在本地開發還是在 GitHub Codespaces 中開發，你都可以使用 GitHub Copilot 或其他 AI 助理來加速編輯 React 元件、更新路由或建立測試支架等任務。

小提示

Starter-Kit 存放庫已啟用 AI，並包含 GitHub Copilot 指示，可引導您調整 Hello World 項目以符合您的需求。其他 AI 工具（例如 Anthropic Claude）可以遵循相同指引，但必須設定為讀取資料庫的指引檔案或文件。

具體的人工智慧協助領域：

用 AI 來草擬項目編輯器/檢視元件，然後調整到 Starter-Kit 中使用的主機 API 模式
請 AI 總結工作量清單並建議最小權限集
在 Codespaces 中，Copilot 可在瀏覽器或 VS Code 桌面中使用;保持開發伺服器運作，這樣就能立即看到變更

小提示

如果你有興趣看看別人做了什麼，打開 Extensibility Samples 並將其部署到你的環境。在那裡您可以找到可幫助您入門的豐富項目類型。

快速迭代與除錯

擴充性框架設計用於使用 AI 協助時的快速開發：

當開發伺服器和 DevGateway 都運行時，當你在 Fabric 裡開啟你的項目時，應用程式中的程式碼變更會立即反映出來
你可以用瀏覽器的開發工具除錯，而工作負載則託管在 Fabric iFrame 中
快速迭代 UI、路由與清單配置，並驗證 Fabric 工作空間中的端到端行為
AI 工具能在開發過程中即時識別並修正問題

預期時間表

簡單項目：30-60分鐘，搭配 AI 指導
複雜項目：1-3小時，多次迭代
進階道具：半天制，可大量自訂

🛠️ 手動腳本化方法

使用 CreateNewItem.ps1 腳本

手動方式使用自動化的 PowerShell 腳本，複製 HelloWorld 項目範本並配置為你的新項目。

快速入門

前往腳本目錄：
```
cd scripts\Setup
```

執行創建腳本：

.\CreateNewItem.ps1 -ItemName "MyCustomItem"

劇本的作用

自動檔案建立：

✅ 從 HelloWorld 範本複製所有四個核心元件檔案
✅ 將檔案重新命名以符合你的物品名稱
✅ 更新所有內部參考與匯入資料
✅ 建立清單檔案（XML 與 JSON 配置）
✅ 複製與重新命名圖示資產

生成檔案結構：

Workload/app/items/MyCustomItemItem/
├── MyCustomItemDefinition.ts         # Data model and interfaces
├── MyCustomItemEditor.tsx            # Main editor component
├── MyCustomItemEditorEmpty.tsx       # First-time user experience
├── MyCustomItemEditorRibbon.tsx      # Action buttons and toolbar
└── MyCustomItem.scss                 # Styling

Workload/Manifest/items/MyCustomItem/
├── MyCustomItemItem.xml              # Item type definition
└── MyCustomItemItem.json             # Item configuration

Workload/Manifest/assets/images/
└── MyCustomItemItem-icon.png         # Item icon

必須執行的手動步驟

執行腳本後， 您必須 完成以下手動設定步驟：

1. 更新環境檔案 🚨 重要

將你的新項目加入所有環境檔案中的變數 ITEM_NAMES ：

待更新檔案：

Workload\.env.dev
Workload\.env.test
Workload\.env.prod

變更來源：

ITEM_NAMES=HelloWorld

變更為：

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ 如果沒有這個步驟，你的商品就不會出現在工作負載裡！

2. 更新 Product.json 設定

請將您的項目配置加入：Workload\Manifest\Product.json

{
  "items": [
    {
      "name": "HelloWorldItem",
      // ... existing config
    },
    {
      "name": "MyCustomItemItem",
      "displayName": "My Custom Item",
      "description": "Description of what your item does",
      "contentType": "MyCustomItem",
      "configurationSections": []
    }
  ]
}

3. 新增定位字串

更新翻譯檔案：Workload\Manifest\assets\locales\

在 en-US.json （及其他區域設定檔案）：

{
  "MyCustomItemItem": {
    "displayName": "My Custom Item",
    "description": "Description of your custom item"
  }
}

4. 新增路由配置

更新 Workload\app\App.tsx 包含新項目的路由：

// Add import
import { MyCustomItemEditor } from "./items/MyCustomItemItem/MyCustomItemEditor";

// Add route in the Routes section
<Route path="/MyCustomItemItem-editor" element={<MyCustomItemEditor {...props} />} />

驗證步驟

完成所有手動步驟後：

建構專案：
```
npm run build
```
重新啟動開發伺服器：
```
.\scripts\Run\StartDevServer.ps1
```
布料測試：
- 在 Fabric 中導覽你的工作量
- 確認你的新物品類型是否出現在建立對話框中
- 建立一個實例並確認載入正確

最佳實務與指引

為什麼不把 HelloWorld 改名？

HelloWorld 項目作為 參考範本 ，定期收到 Microsoft 的更新。保持不變的主要原因：

更新與改進：Microsoft 定期更新 HelloWorld 新功能、錯誤修正及最佳實務
整合測試：HelloWorld 確保您的環境運作正常
參考文件：作為實作模式的即時文件
向下相容性：更新維持與現有自訂的相容性

試題開發最佳實務

元件架構：

✅ 遵循四成分模式（定義、編輯器、空、色帶）
✅ 使用 ItemEditor 容器來保持一致的版面配置和行為
✅ 實作正確的載入狀態與錯誤處理
✅ 遵循 Fluent UI 的設計模式

資料管理：

✅ 使用 saveWorkloadItem() 具有複雜資料的項目
✅ 使用 getWorkloadItem() 來載入預設的備用值
✅ 在定義檔案中實作適當的 TypeScript 介面
✅ 優雅地處理未定義或空狀態

使用者體驗：

✅ 為首次使用者提供清晰的空狀態
✅ 使用適當的載重指示器
✅ 實現有用的錯誤訊息
✅ 遵循 Fabric 的設計模式與無障礙指引

效能考量

延遲加載：只有在需要時才載入資料
高效更新：使用 React 模式來減少重新渲染
OneLake 整合：使用createItemWrapper() 以正確設定範圍
錯誤邊界：全程實施正確的錯誤處理

後續步驟

商品完成後：

自訂資料模型：更新定義檔案，並使用您的特定介面
實作核心功能：在編輯器元件中建構主要功能
設計空白狀態：打造引人入勝的首次使用者體驗
設定動作：為您的工作流程設定適當的功能區動作
徹底測試：驗證開發環境中的所有功能
準備製作：準備好後依照出版指南進行

故障排除

該物品未出現在工作負載中：

✅ 檢查所有 .env 檔案中的 ITEM_NAMES
✅ 驗證 Product.json 配置
✅ 重新啟動開發伺服器

建置錯誤：

✅ 檢查定義檔案中的 TypeScript 介面
✅ 確認所有匯入資料都正確
✅ 確保路由設定正確

執行時錯誤：

✅ 請查看瀏覽器主控台查看詳細錯誤訊息
✅ 驗證 API 整合與認證
✅ 先用簡化資料測試

其他資源

快樂編碼！ 🚀

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-15

共用方式為

創建新的布料物品

先決條件

選擇你的方法

AI輔助方法（建議新手開發者使用）

🛠️ 手動腳本化方法（建議有經驗的開發者使用）

🤖 人工智慧輔助之物品製作

開始使用 GitHub Copilot

有效的範例提示

AI 協助的典型過程

與 AI 助理合作

AI 協作的最佳實務

AI 開發工具與環境

快速迭代與除錯

預期時間表

🛠️ 手動腳本化方法

使用 CreateNewItem.ps1 腳本

快速入門

劇本的作用

必須執行的手動步驟

1. 更新環境檔案 🚨 重要

2. 更新 Product.json 設定

3. 新增定位字串

4. 新增路由配置

驗證步驟

最佳實務與指引

為什麼不把 HelloWorld 改名？

推薦工作流程

試題開發最佳實務

效能考量

後續步驟

故障排除

其他資源

意見反應

其他資源