创建新的构造项

本综合指南介绍如何使用扩展性工具包在 Microsoft Fabric 中创建自定义项。 可以根据偏好和体验级别在两种方法之间进行选择。

先决条件

在创建自定义项之前，请确保具备：

• ✅ 完成 设置指南 并使开发环境已就绪
• ✅ 工作负荷在本地运行，并且可在 Fabric 中访问
• ✅ 熟悉 TypeScript 和 React（用于自定义）

选择您的方法

🤖 AI 辅助方式（推荐给新开发人员）

使用 GitHub Copilot 以交互方式指导你完成整个过程。 非常适合：

• 初次接触 Fabric 扩展性工具包的开发人员
• 了解平台模式和最佳做法
• 在工作时获取说明和指南

🛠️ 手动编写脚本方法（建议面向经验丰富的开发人员）

使用自动化的 PowerShell 脚本快速设置。 非常适合：

• 熟悉工具包结构的开发人员
• 高效创建多个项目
• 生产工作流和自动化

---

🤖 AI辅助的物品创建

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 辅助方法遵循此迭代模式：

1. 初始规划阶段

• AI 分析你的需求
• 建议物品结构和组件
• 使用 todos 创建开发计划

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 工具（例如，人类 Claude）可以遵循相同的指导，但必须配置为读取存储库的指导文件或文档。

特定的 AI 援助领域：

• 使用 AI 来起草项编辑器/视图组件，然后适应 Starter-Kit 中使用的主机 API 模式
• 要求 AI 汇总工作负荷清单并建议最小权限集
• 在 Codespaces 中，Copilot 在浏览器或 VS Code 桌面版中可用;使开发服务器保持运行状态，立即查看更改

小窍门

如果有兴趣查看其他人生成的内容，请打开 扩展性示例 并将其部署到环境。 可在此处找到有助于入门的丰富项类型。

快速迭代和调试

使用 AI 协助时，扩展性框架专为快速开发而设计：

• 在开发服务器和 DevGateway 运行时，当你在 Fabric 中打开项目时，应用中的代码更改将立即反映
• 可以在 Fabric iFrame 中托管工作负载时使用浏览器的开发工具进行调试
• 快速迭代用户界面 (UI)、路由和 Manifest 配置，并在 Fabric 平台的工作区中验证端到端的操作行为。
• AI 工具有助于在开发时实时识别和修复问题

预期时间线

• 简单项：在 AI 指导下 30-60 分钟
• 复杂项：1-3 小时，需要多次迭代
• 高级项：半天的时间，提供广泛的定制化服务

---

🛠️ 手动编写脚本的方法

使用 CreateNewItem.ps1 脚本

手动方法使用自动 PowerShell 脚本来复制 HelloWorld 项模板，并为新项配置它。

快速入门

1. 导航到脚本目录：

   cd scripts\Setup
   

2. 运行创建脚本：

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

脚本的作用

自动创建文件：

• ✅ 从 HelloWorld 模板复制所有 4 个核心组件文件
• ✅ 重命名文件以匹配项目名称
• ✅ 更新所有内部引用和导入
• ✅ 创建清单文件（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} />} />

验证步骤

完成所有手动步骤后：

1. 生成项目：

   npm run build
   

2. 重启开发服务器：

   .\scripts\Run\StartDevServer.ps1
   

3. 在 Fabric 中测试：

   • 在 Fabric 中访问工作负荷
   • 验证新项目类型是否显示在“创建”对话框中
   • 创建实例并验证它是否正确加载

---

最佳做法和指南

为什么不重命名 HelloWorld？

HelloWorld 项目作为 引用模板 ，并从 Microsoft 接收定期更新。 保持其不变的关键原因：

• 更新和改进：Microsoft定期使用新功能、bug 修复和最佳做法更新 HelloWorld
• 集成测试：HelloWorld 可确保环境正常运行
• 参考文档：它充当实现模式的实时文档
• 向后兼容性：更新与现有自定义项保持兼容性

建议工作流

1. 保持 HelloWorld 未更改：将其用作参考和测试项目
2. 创建新项：使用脚本或 AI 帮助创建单独的项
3. 常规更新：定期从基本存储库拉取更新
4. 合并模式：将新模式从更新的 HelloWorld 应用到自定义项

项目开发最佳实践

组件体系结构：

• ✅ 遵循 4 组件模式（定义、编辑器、空白、功能区）
• ✅ 使用 ItemEditor 容器实现一致的布局和行为
• ✅ 实现正确的加载状态和错误处理
• ✅ 遵循 Fluent UI 设计模式

数据管理：

• ✅ 使用 saveWorkloadItem() 用于包含复杂数据的项
• ✅ 使用 getWorkloadItem() 加载时使用备用默认值
• ✅ 在定义文件中实现正确的 TypeScript 接口
• ✅ 优雅地处理未定义/空状态

用户体验：

• ✅ 为第一次使用的用户提供清晰的空状态
• ✅ 使用适当的加载指示器
• ✅ 实现有用的错误消息
• ✅ 遵循 Fabric 设计模式和辅助功能指南

性能注意事项

• 延迟加载：仅在需要时加载数据
• 高效更新：使用 React 模式来减少重新渲染
• OneLake 集成：使用 createItemWrapper() 以确保适当的范围
• 错误边界：在整个过程中实现正确的错误处理

---

后续步骤

创建项目后：

1. 自定义数据模型：使用特定接口更新定义文件
2. 实现核心功能：在编辑器组件中构建主要功能
3. 设计空状态：创建引人入胜的首次用户体验
4. 配置操作：为工作流设置适当的功能区操作
5. 全面测试：验证开发环境中的所有功能
6. 准备生产：准备好时，请遵循发布指南

Troubleshooting

项目未出现在工作负载中：

• ✅ 检查所有 .env 文件中的 ITEM_NAMES
• ✅ 验证 Product.json 配置
• ✅ 重启开发服务器

生成错误：

• ✅ 在定义文件中检查 TypeScript 接口
• ✅ 验证所有导入是否正确
• ✅ 确保正确配置路由

运行时错误：

• ✅ 检查浏览器控制台中是否有详细的错误消息
• ✅ 验证 API 集成和身份验证
• ✅ 首先使用简化的数据进行测试

其他资源

• ItemEditor 控件文档
• OneLake 集成指南
• Fabric API 用法
• 发布要求

快乐编程！ 🚀