Crie um novo Item de Tecido

Este guia abrangente mostra-lhe como criar itens personalizados no Microsoft Fabric usando o Extensibility Toolkit. Pode escolher entre duas abordagens consoante a sua preferência e nível de experiência.

Pré-requisitos

Antes de criar um artigo personalizado, certifique-se de que tem:

• ✅ Completei o Guia de Configuração e tenho um ambiente de desenvolvimento a funcionar
• ✅ A sua carga de trabalho está a correr localmente e está acessível no Fabric
• ✅ Familiaridade com TypeScript e React (para personalização)

Escolha a Sua Abordagem

🤖 Abordagem Assistida por IA (Recomendada para Novos Desenvolvedores)

Use o GitHub Copilot para orientá-lo de forma interativa durante todo o processo. Perfeito para:

• Desenvolvedores novos ao Fabric Extensibility Toolkit
• Aprender os padrões da plataforma e as melhores práticas
• Obter explicações e orientação enquanto trabalhas

🛠️ Abordagem Manual Scripted (Recomendado para programadores experientes)

Usa o script automatizado do PowerShell para uma configuração rápida. Perfeito para:

• Desenvolvedores familiarizados com a estrutura do toolkit
• Criar múltiplos itens de forma eficiente
• Fluxos de trabalho de produção e automação

Criação de Itens Assistida por IA

Começar com o GitHub Copilot

O GitHub Copilot pode guiá-lo na criação de um item Fabric personalizado completo, seguindo todas as melhores práticas. A IA compreende os padrões do Extensibility Toolkit e vai ajudar-te a implementá-los corretamente.

Exemplos de Prompts que Funcionam

Aqui ficam sugestões comprovadas que o ajudarão a começar a criar itens:

Criação Básica de Itens:

@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

Item Complexo com Integração 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

Processo Típico Assistido por IA

A abordagem assistida por IA segue este padrão iterativo:

1. Fase inicial de planeamento

• A IA analisa os seus requisitos
• Sugere estrutura e componentes do item
• Cria um plano de desenvolvimento com todos

2. Geração de Componentes

• Cria o padrão de 4 ficheiros (Definição, Editor, Vazio, Fita)
• Implementa interfaces TypeScript adequadas
• Configura componentes da Fluent UI

3. Implementação de Funcionalidades

• Adiciona a sua funcionalidade específica
• Integra com APIs de Fabric
• Implementa um tratamento adequado de erros

4. Testes e Refinamento

• Testa o item no seu ambiente de desenvolvimento
• Corrige quaisquer problemas encontrados
• Otimiza o desempenho e a experiência do utilizador

Trabalhar com o Assistente de IA

Comece com 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 e 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?

Peça Explicações:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Boas Práticas para a Colaboração em IA

• Seja Específico: Forneça requisitos claros e contexto
• Revise Cada Passo: Compreenda o código gerado antes de avançar
• Faça Perguntas: Pede explicações para padrões que não compreende
• Teste Frequentemente: Execute e teste o item após cada alteração importante
• Seguimento: Peça refinamentos e melhorias

Ferramentas e Ambiente de Desenvolvimento de IA

Este repositório funciona excecionalmente bem com ferramentas de programação em pares de IA. Quer desenvolvas localmente ou em Codespaces do GitHub, podes usar o GitHub Copilot ou outros assistentes de IA para acelerar tarefas como editar componentes do React, atualizar rotas ou gerar andaimes de teste.

Áreas específicas de assistência à IA:

• Utilize IA para rascunhar componentes do editor/visualização de itens e depois adaptar-se aos padrões da API do servidor usados no Starter-Kit
• Peça à IA para resumir o manifesto da carga de trabalho e propor conjuntos mínimos de permissões
• Em Codespaces, o Copilot está disponível no navegador ou no ambiente de trabalho VS Code; Mantenha o servidor de desenvolvimento ativo para verem alterações instantaneamente

Iteração Rápida e Depuração

O framework de Extensibilidade foi concebido para um desenvolvimento rápido ao utilizar assistência de IA:

• Com o servidor de desenvolvimento e o DevGateway a funcionar, as alterações de código na tua aplicação são refletidas imediatamente quando abres o teu item dentro do Fabric
• Pode depurar usando as ferramentas de desenvolvimento do seu navegador enquanto a carga de trabalho está alojada no Fabric iFrame
• Itere rapidamente na interface, rotas e configuração de manifestos, e valide o comportamento de ponta a ponta no seu espaço de trabalho Fabric
• As ferramentas de IA podem ajudar a identificar e corrigir problemas em tempo real à medida que se desenvolve

Cronologia Esperada

• Item simples: 30-60 minutos com orientação da IA
• Item Complexo: 1-3 horas com múltiplas iterações
• Item Avançado: Meio dia com personalização extensa

🛠️ Abordagem Manual Scripted

Utilização do CreateNewItem.ps1 Script

A abordagem manual utiliza um script PowerShell automatizado que copia o modelo de item HelloWorld e configura-o para o seu novo item.

Início Rápido

1. Navegue até ao diretório de scripts:

   cd scripts\Setup
   

2. Executa o script de criação:

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

O que o script faz

Criação Automática de Ficheiros:

• ✅ Copia os 4 ficheiros principais dos componentes do template HelloWorld
• ✅ Renomeia ficheiros para corresponder ao nome do teu item
• ✅ Atualiza todas as referências internas e importações
• ✅ Cria ficheiros manifestos (configurações XML e JSON)
• ✅ Copia e renomeia os ativos de ícones

Estrutura de ficheiros gerada:

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

Passos Manuais Obrigatórios

Após executar o script, deve completar estes passos manuais de configuração:

1. Atualizar ficheiros 🚨 de ambiente CRÍTICOS

Adicione o seu novo item à ITEM_NAMES variável em TODOS os ficheiros do ambiente:

Ficheiros a atualizar:

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

Alteração de:

ITEM_NAMES=HelloWorld

Mudança para:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠️ Sem este passo, o teu item NÃO aparecerá na carga de trabalho!

2. Atualizar a configuração do Product.json

Adicione a configuração do seu item 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. Adicionar Cadeias de Localização

Atualizar ficheiros de tradução em Workload\Manifest\assets\locales\:

Em en-US.json (e outros ficheiros de localidade):

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

4. Adicionar Configuração de Roteamento

Atualize Workload\app\App.tsx para incluir o encaminhamento do seu novo item:

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

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

Etapas de verificação

Após completar todos os passos manuais:

1. Construa o projeto:

   npm run build
   

2. Reiniciar o servidor de desenvolvimento:

   .\scripts\Run\StartDevServer.ps1
   

3. Teste em Tecido:

   • Navegue para a sua carga de trabalho no Fabric
   • Verifica se o teu novo tipo de item aparece na janela de criação
   • Cria uma instância e verifica se carrega corretamente

Melhores Práticas e Diretrizes

Porque não renomear o HelloWorld?

O item HelloWorld serve como modelo de referência que recebe atualizações regulares da Microsoft. Principais razões para o manter inalterado:

• Atualizações e Melhorias: A Microsoft atualiza regularmente o HelloWorld com novas funcionalidades, correções de bugs e boas práticas
• Testes de Integração: A HelloWorld garante que o seu ambiente está a funcionar corretamente
• Documentação de Referência: Serve como documentação em tempo real para padrões de implementação
• Compatibilidade Retroativa: As atualizações mantêm a compatibilidade com as personalizações existentes

Fluxo de trabalho recomendado

1. Mantenha o HelloWorld intocado: Use-o como referência e item de teste
2. Criar Novos Itens: Use o script ou a assistência da IA para criar itens separados
3. Atualizações regulares: Retira periodicamente atualizações do repositório base
4. Fusão de Padrões: Aplique novos padrões do HelloWorld atualizado aos seus itens personalizados

Melhores Práticas de Desenvolvimento de Itens

Arquitetura dos Componentes:

• ✅ Siga o padrão de 4 componentes (Definição, Editor, Vazio, Fita)
• ✅ Use o contentor ItemEditor para um layout e comportamento consistentes
• ✅ Implementar estados de carregamento adequados e gestão de erros
• ✅ Siga padrões de design de UI fluentes

Gestão de Dados:

• ✅ Utilização saveWorkloadItem() para itens com dados complexos
• ✅ Uso getWorkloadItem() para carregamento com predefinidos de recurso.
• ✅ Implementar interfaces TypeScript adequadas no ficheiro de Definição
• ✅ Lida com os estados indefinidos/vazios com elegância

Experiência do Utilizador:

• ✅ Fornecer estados vazios claros para usuários iniciantes
• ✅ Use indicadores de carga adequados
• ✅ Implementar mensagens de erro úteis
• ✅ Siga os padrões de design de tecidos e as diretrizes de acessibilidade

Considerações sobre desempenho

• Carregamento Preguiçoso: Só carregar dados quando necessário
• Atualizações Eficientes: Use padrões React para minimizar re-renderizações
• Integração OneLake: Use createItemWrapper() para uma delimitação adequada
• Limites de Erro: Implementar o tratamento adequado de erros ao longo de todo o processo

Próximas Etapas

Depois de criado o seu item:

1. Personalize o Modelo de Dados: Atualize o ficheiro de Definição com as suas interfaces específicas
2. Implementar Funcionalidades Essenciais: Desenvolver a funcionalidade principal no componente Editor
3. Design Empty State: Crie uma experiência envolvente para o primeiro utilizador
4. Configurar Ações: Configurar ações da barra de ferramentas apropriadas para o seu fluxo de trabalho
5. Teste Cuidadosamente: Verifique todas as funcionalidades no seu ambiente de desenvolvimento
6. Prepare-se para a Produção: Siga o guia de publicação quando estiver pronto

Solução de problemas

Item não aparece na carga de trabalho:

• ✅ Verifique ITEM_NAMES em todos os ficheiros .env
• ✅ Verificar configuração do Product.json
• ✅ Reiniciar o servidor de desenvolvimento

Erros de compilação:

• ✅ Verifique interfaces TypeScript no ficheiro de Definição
• ✅ Verifique se todas as importações estão corretas
• ✅ Garantir que o encaminhamento está devidamente configurado

Erros em tempo de execução:

• ✅ Verifique a consola do navegador para mensagens de erro detalhadas
• ✅ Verificar integração e autenticação da API
• ✅ Teste primeiro com dados simplificados

Recursos adicionais

• Documentação de Controlo do ItemEditor
• Guia de Integração OneLake
• Utilização da API Fabric
• Requisitos de Publicação

Feliz codificação! 🚀