Crear un nuevo elemento de tejido

En esta guía completa se muestra cómo crear elementos personalizados en Microsoft Fabric mediante el Kit de herramientas de extensibilidad. Puede elegir entre dos enfoques en función de su preferencia y nivel de experiencia.

Prerrequisitos

Antes de crear un elemento personalizado, asegúrese de que tiene:

• ✅ Completó la Guía de instalación y tiene un entorno de desarrollo en funcionamiento
• ✅ La carga de trabajo se ejecuta localmente y es accesible en Fabric
• ✅ Familiaridad con TypeScript y React (para la personalización)

Elegir su enfoque

🤖 Enfoque asistido por IA (recomendado para nuevos desarrolladores)

Use GitHub Copilot para guiarle a través de todo el proceso de forma interactiva. Perfecto para:

• Desarrolladores nuevos en Fabric Extensibility Toolkit
• Aprendizaje de los patrones de plataforma y los procedimientos recomendados
• Obtención de explicaciones e instrucciones a medida que trabaja

🛠️ Enfoque manual con scripts (recomendado para desarrolladores experimentados)

Use el script de PowerShell automatizado para la configuración rápida. Perfecto para:

• Desarrolladores familiarizados con la estructura del kit de herramientas
• Crear varios elementos de forma eficaz
• Flujos de trabajo de producción y automatización

🤖 Creación de artículos asistida por IA

Introducción a GitHub Copilot

GitHub Copilot puede guiarle a través de la creación de un elemento de Fabric personalizado completo siguiendo todos los procedimientos recomendados. La inteligencia artificial entiende los patrones del Kit de herramientas de extensibilidad y le ayudará a implementarlos correctamente.

Mensajes de ejemplo que funcionan

Estos son los avisos probados que le ayudarán a empezar a crear elementos:

Creación básica de elementos:

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

Requisitos específicos:

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

Elemento complejo con integración de 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

Proceso típico asistido por IA

El enfoque asistido por IA sigue este patrón iterativo:

1. Fase de planificación inicial

• La inteligencia artificial analiza sus requisitos
• Sugiere la estructura y los componentes de un elemento
• Crea un plan de desarrollo con todos

2. Generación de componentes

• Crea el patrón de 4 archivos (Definición, Editor, Vacío, Cinta)
• Implementa las interfaces de TypeScript adecuadas
• Configuración de componentes de la interfaz de usuario de Fluent

3. Implementación de características

• Agrega tu funcionalidad específica
• Se integra con las API de Fabric
• Implementa el control de errores adecuado

4. Pruebas y refinamiento

• Prueba el elemento en el entorno de desarrollo
• Corrige los problemas encontrados.
• Optimiza el rendimiento y la experiencia del usuario

Trabajando con el asistente de IA

Comience con requisitos claros:

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].

Iterar y refinar:

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?

Pedir explicaciones:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Procedimientos recomendados para la colaboración con IA

• Ser específico: proporcionar requisitos y contexto claros
• Revisar cada paso: Comprender el código generado antes de continuar
• Formular preguntas: Solicitar explicaciones de patrones que no comprenda
• Probar con frecuencia: ejecute y pruebe el elemento después de cada cambio importante
• Seguimiento: Solicitar mejoras y refinamientos

Herramientas y entorno de desarrollo de IA

Este repositorio funciona muy bien con herramientas de programación de pares de IA. Tanto si desarrolla localmente como en GitHub Codespaces, puede usar GitHub Copilot u otros asistentes basados en inteligencia artificial para acelerar tareas como editar componentes de React, actualizar rutas o generar esqueletos de pruebas.

Áreas específicas de asistencia de IA:

• Utiliza IA para redactar componentes de editor o vista de elementos, y después adapta a los patrones de API del sistema anfitrión utilizados en el Starter-Kit.
• Pida a la IA que resuma el manifiesto de carga de trabajo y proponga conjuntos de permisos mínimos.
• En Codespaces, Copilot está disponible en el explorador o en el escritorio de VS Code; mantener el servidor de desarrollo en ejecución para ver los cambios al instante

Iteración rápida y depuración

El marco de extensibilidad está diseñado para un desarrollo rápido al usar la asistencia de IA:

• Con el servidor de desarrollo y DevGateway en ejecución, los cambios de código en la aplicación se reflejan inmediatamente al abrir el elemento dentro de Fabric.
• Puede depurar mediante las herramientas de desarrollo del explorador mientras la carga de trabajo está hospedada en el iFrame de Fabric
• Iterar en la configuración de la interfaz de usuario, las rutas y el manifiesto rápidamente y validar el comportamiento de un extremo a otro en el área de trabajo de Fabric
• Las herramientas de inteligencia artificial pueden ayudar a identificar y corregir problemas en tiempo real a medida que desarrollas.

Escala de tiempo esperada

• Elemento simple: 30-60 minutos con instrucciones de IA
• Elemento complejo: 1-3 horas con varias iteraciones
• Elemento avanzado: Medio día con una amplia personalización

🛠️ Enfoque manual con scripts

Uso del script CreateNewItem.ps1

El enfoque manual usa un script de PowerShell automatizado que copia la plantilla de elemento HelloWorld y la configura para el nuevo elemento.

Quick Start

1. Vaya al directorio de scripts:

   cd scripts\Setup
   

2. Ejecute el script de creación:

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

Qué hace el script

Creación automatizada de archivos:

• ✅ Copia todos los 4 archivos de componentes principales de la plantilla HelloWorld
• ✅ Cambia el nombre de los archivos para que coincidan con el nombre del elemento.
• ✅ Actualiza todas las referencias internas e importaciones
• ✅ Crea archivos de manifiesto (configuraciones XML y JSON)
• ✅ Copia y cambia el nombre de los recursos del icono

Estructura de archivos generada:

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

Pasos manuales necesarios

Después de ejecutar el script, debe completar estos pasos de configuración manuales:

1. Actualizar archivos 🚨 de entorno CRÍTICOS

Agregue el nuevo elemento a la ITEM_NAMES variable en todos los archivos de entorno:

Archivos que se van a actualizar:

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

Cambiar de:

ITEM_NAMES=HelloWorld

Cambiar a:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ Sin este paso, el elemento NO aparecerá en la carga de trabajo.

2. Actualizar la configuración de Product.json

Agregue la configuración del elemento a 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. Agregar cadenas de localización

Actualice los archivos de traducción en Workload\Manifest\assets\locales\:

En en-US.json (y otros archivos de configuración regional):

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

4. Agregar configuración de enrutamiento

Actualice Workload\app\App.tsx para incluir el enrutamiento del nuevo elemento:

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

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

Pasos de comprobación

Después de completar todos los pasos manuales:

1. Compile el proyecto:

   npm run build
   

2. Reinicie el servidor de desarrollo:

   .\scripts\Run\StartDevServer.ps1
   

3. Prueba en Fabric:

   • Navegue a su "workload" en Fabric.
   • Compruebe que el nuevo tipo de elemento aparece en el cuadro de diálogo de creación
   • Creación de una instancia y comprobación de que se carga correctamente

Procedimientos recomendados y directrices

¿Por qué no cambiar el nombre de HelloWorld?

El elemento HelloWorld actúa como plantilla de referencia que recibe actualizaciones periódicas de Microsoft. Razones clave para mantenerlo sin cambios:

• Actualizaciones y mejoras: Microsoft actualiza periódicamente HelloWorld con nuevas características, correcciones de errores y procedimientos recomendados
• Pruebas de integración: HelloWorld garantiza que el entorno funciona correctamente
• Documentación de referencia: sirve como documentación activa para los patrones de implementación
• Compatibilidad con versiones anteriores: las actualizaciones mantienen la compatibilidad con las personalizaciones existentes

Flujo de trabajo recomendado

1. Mantener HelloWorld sin tocar: Úselo como referencia y elemento de prueba
2. Crear elementos nuevos: use el script o la asistencia de IA para crear elementos independientes.
3. Actualizaciones periódicas: extraiga periódicamente las actualizaciones del repositorio base.
4. Patrones de mezcla: aplicar nuevos patrones de HelloWorld actualizados a los elementos personalizados

Mejores prácticas de desarrollo de ítems

Arquitectura de componentes:

• ✅ Siga el patrón de 4 componentes (Definición, Editor, Vacío, Cinta)
• ✅ Uso del contenedor ItemEditor para un diseño y un comportamiento coherentes
• ✅ Implementar los estados de carga adecuados y el control de errores
• ✅ Seguir los patrones de diseño de la interfaz de usuario de Fluent

Administración de datos:

• ✅ Uso saveWorkloadItem() para elementos con datos complejos
• ✅ Uso getWorkloadItem() para cargar con valores predeterminados de reserva
• ✅ Implementación de interfaces typeScript adecuadas en el archivo de definición
• ✅ Gestionar estados sin definir o vacíos correctamente

Experiencia del usuario:

• ✅ Proporcionar estados vacíos claros para los usuarios que acceden por primera vez
• ✅ Usar indicadores de carga adecuados
• ✅ Implementación de mensajes de error útiles
• ✅ Seguir los patrones de diseño de Fabric y las directrices de accesibilidad

Consideraciones de rendimiento

• Carga diferida: solo carga los datos cuando sea necesario.
• Actualizaciones eficaces: usar patrones de React para minimizar los re-renderizados
• Integración de OneLake: usar createItemWrapper() para determinar el ámbito adecuado
• Límites de errores: implementar un manejo adecuado de errores throughout

Pasos siguientes

Una vez creado el elemento:

1. Personalizar el modelo de datos: actualizar el archivo de definición con sus interfaces específicas
2. Implementar características centrales: desarrolle la funcionalidad principal en el componente Editor.
3. Diseño de estado vacío: creación de una experiencia de usuario atractiva por primera vez
4. Configurar Acciones: establecer las acciones adecuadas de la cinta de opciones para tu flujo de trabajo
5. Prueba exhaustiva: comprobación de toda la funcionalidad en el entorno de desarrollo
6. Preparación para producción: siga la guía de publicación cuando esté lista.

Solución de problemas

El elemento no aparece en la carga de trabajo:

• ✅ Verificar ITEM_NAMES en todos los archivos .env
• ✅ Comprobación de la configuración de Product.json
• ✅ Reinicio del servidor de desarrollo

Errores de compilación:

• ✅ Comprobación de interfaces typeScript en el archivo de definición
• ✅ Comprobación de que todas las importaciones son correctas
• ✅ Asegurarse de que el enrutamiento está configurado correctamente

Errores en tiempo de ejecución:

• ✅ Comprueba la consola del navegador para ver mensajes de error detallados
• ✅ Comprobación de la integración y autenticación de API
• ✅ Prueba con datos simplificados primero

Recursos adicionales

• Documentación de ItemEditor Control
• Guía de integración de OneLake
• Uso de la API de Fabric
• Requisitos de publicación

¡Feliz codificación! 🚀