Tworzenie nowego elementu Fabric

W tym kompleksowym przewodniku pokazano, jak tworzyć elementy niestandardowe w usłudze Microsoft Fabric przy użyciu Zestawu Narzędzi Rozszerzalności. Możesz wybrać między dwoma podejściami na podstawie preferencji i poziomu doświadczenia.

Wymagania wstępne

Przed utworzeniem elementu niestandardowego upewnij się, że masz:

• ✅ Zakończono Przewodnik instalacji i środowisko programistyczne działa poprawnie
• ✅ Twoje zadanie działa lokalnie i jest dostępne w Fabric
• ✅ Znajomość języków TypeScript i React (na potrzeby dostosowywania)

Wybierz swoje podejście

🤖 Podejście wspomagane przez AI (zalecane dla nowych programistów)

Użyj narzędzia GitHub Copilot, aby interaktywnie przeprowadzić Cię przez cały proces. Idealny dla:

• Deweloperzy nowi w zestawie narzędzi do rozszerzalności sieci szkieletowej
• Poznawanie wzorców platformy i najlepszych rozwiązań
• Uzyskiwanie wyjaśnień i wskazówek podczas pracy

🛠✔ Ręczne podejście skryptowe (zalecane dla doświadczonych deweloperów)

Użyj zautomatyzowanego skryptu programu PowerShell do szybkiej konfiguracji. Idealny dla:

• Deweloperzy zaznajomieni ze strukturą zestawu narzędzi
• Wydajne tworzenie wielu elementów
• Produkcyjne przepływy pracy i automatyzacja

Tworzenie elementów wspomagane przez AI

Wprowadzenie do narzędzia GitHub Copilot

GitHub Copilot może poprowadzić cię przez proces tworzenia kompletnego niestandardowego elementu w Fabric, zgodnie ze wszystkimi najlepszymi praktykami. Sztuczna inteligencja rozumie wzorce zestawu narzędzi rozszerzalności i pomoże ci je poprawnie zaimplementować.

Przykładowe podpowiedzi, które działają

Oto sprawdzone wskazówki, które umożliwią zaczęcie tworzenia elementów:

Tworzenie podstawowego elementu:

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

Określone wymagania:

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

Złożony element z integracją usługi 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

Typowy proces wspomagany przez AI

Podejście wspomagane przez sztuczną inteligencję jest zgodne z tym wzorcem iteracyjnym:

1. Początkowa faza planowania

• Sztuczna inteligencja analizuje wymagania
• Sugeruje strukturę elementów i składniki
• Tworzy plan rozwoju z zadaniami do wykonania

2. Generowanie składników

• Tworzy wzorzec 4-plików (Definicja, Edytor, Pusty, Wstążka)
• Implementuje odpowiednie interfejsy języka TypeScript
• Konfigurowanie składników interfejsu użytkownika Fluent

3. Implementacja funkcji

• Dodaje określone funkcje
• Integruje się z API Fabric
• Implementuje prawidłową obsługę błędów

4. Testowanie i dopracowanie

• Testuje element w środowisku projektowym
• Rozwiązuje wszelkie znalezione problemy
• Optymalizuje wydajność i środowisko użytkownika

Praca z asystentem sztucznej inteligencji

Zacznij od jasnych wymagań:

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

Iterowanie oraz udoskonalanie:

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?

Zapytaj o wyjaśnienia:

Explain why you chose this pattern for the ribbon actions

What's the difference between ItemEditor and ItemEditorDefaultView?

Najlepsze rozwiązania dotyczące współpracy ze sztuczną inteligencją

• Bądź konkretny: Podaj jasne wymagania i kontekst
• Przejrzyj każdy krok: Omówienie wygenerowanego kodu przed kontynuowaniem
• Zadawanie pytań: żądanie wyjaśnień wzorców, które nie są zrozumiałe
• Często testuj: uruchamianie i testowanie elementu po każdej istotnej zmianie
• Kontynuacja: Poproś o doprecyzowanie i ulepszenia

Narzędzia programistyczne i środowisko sztucznej inteligencji

To repozytorium działa wyjątkowo dobrze z narzędziami do programowania par sztucznej inteligencji. Niezależnie od tego, czy programujesz lokalnie, czy w usłudze GitHub Codespaces, możesz użyć narzędzia GitHub Copilot lub innych asystentów sztucznej inteligencji, aby przyspieszyć zadania, takie jak edytowanie składników react, aktualizowanie tras lub generowanie szkieletu testowego.

Konkretne obszary pomocy w zakresie sztucznej inteligencji:

• Użyj sztucznej inteligencji do szkicowania komponentów edytora/widoku elementów, a następnie dostosuj je do wzorców API hosta używanych w Starter-Kit.
• Poproś sztuczną inteligencję o podsumowanie manifestu obciążenia i zaproponowanie minimalnych zestawów uprawnień
• W usłudze Codespaces copilot jest dostępny w przeglądarce lub na pulpicie programu VS Code; zachowaj uruchomiony serwer deweloperski, aby natychmiast zobaczyć zmiany

Szybka iteracja i debugowanie

Struktura rozszerzalności została zaprojektowana pod kątem szybkiego opracowywania w przypadku korzystania z pomocy w zakresie sztucznej inteligencji:

• Po uruchomieniu serwera deweloperskiego i DevGateway, zmiany w kodzie aplikacji są widoczne natychmiast po otwarciu elementu w środowisku Fabric.
• Można debugować przy użyciu narzędzi deweloperskich przeglądarki, gdy obciążenie jest hostowane w elemencie iFrame Fabric.
• Przeprowadzaj iteracje nad interfejsem użytkownika, trasami oraz konfiguracją manifestu szybko, a także weryfikuj zachowanie od początku do końca w swoim obszarze roboczym usługi Fabric.
• Narzędzia sztucznej inteligencji mogą pomóc w identyfikowaniu i rozwiązywaniu problemów w czasie rzeczywistym podczas opracowywania

Oczekiwana linia czasu

• Prosty element: 30–60 minut ze wskazówkami dotyczącymi sztucznej inteligencji
• Złożony element: 1–3 godziny z wieloma iteracjami
• Element zaawansowany: pół dnia z szerokim możliwościami dostosowywania

🛠✔ Ręczne podejście skryptowe

Używanie skryptu CreateNewItem.ps1

Metoda ręczna używa zautomatyzowanego skryptu programu PowerShell, który kopiuje szablon elementu HelloWorld i konfiguruje go dla nowego elementu.

Szybki start

1. Przejdź do katalogu skryptów:

   cd scripts\Setup
   

2. Uruchom skrypt tworzenia:

   .\CreateNewItem.ps1 -ItemName "MyCustomItem"
   

Co robi skrypt

Automatyczne tworzenie plików:

• ✅ Kopiuje wszystkie 4 podstawowe pliki składników z szablonu HelloWorld
• ✅ Zmienia nazwy plików tak, aby odpowiadały nazwie elementu
• ✅ Aktualizuje wszystkie odwołania wewnętrzne i importy
• ✅ Tworzy pliki manifestu (konfiguracje XML i JSON)
• ✅ Kopiuje i zmienia nazwy zasobów ikon

Wygenerowana struktura plików:

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

Wymagane kroki ręczne

Po uruchomieniu skryptu należy wykonać następujące kroki ręcznej konfiguracji:

1. Aktualizuj pliki środowiska 🚨 KRYTYCZNE

Dodaj nowy element do zmiennej ITEM_NAMES we wszystkich plikach środowiskowych:

Pliki do zaktualizowania:

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

Zmień z:

ITEM_NAMES=HelloWorld

Zmień na:

ITEM_NAMES=HelloWorld,MyCustomItem

⚠✔ Bez tego kroku twój element NIE będzie wyświetlany w harmonogramie!

2. Aktualizacja konfiguracji Product.json

Dodaj konfigurację elementu do 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. Dodawanie ciągów lokalizacyjnych

Aktualizowanie plików tłumaczenia w programie Workload\Manifest\assets\locales\:

W en-US.json (i innych plikach ustawień regionalnych):

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

4. Dodawanie konfiguracji routingu

Zaktualizuj Workload\app\App.tsx , aby uwzględnić routing dla nowego elementu:

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

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

Kroki weryfikacji

Po wykonaniu wszystkich czynności ręcznych:

1. Skompiluj projekt:

   npm run build
   

2. Uruchom ponownie serwer deweloperów:

   .\scripts\Run\StartDevServer.ps1
   

3. Testowanie w sieci szkieletowej:

   • Przejdź do obciążenia w Fabric
   • Sprawdź, czy nowy typ elementu jest wyświetlany w oknie dialogowym tworzenia
   • Utwórz wystąpienie i sprawdź, czy ładuje się poprawnie

Najlepsze rozwiązania i wytyczne

Dlaczego nie zmieniasz nazwy HelloWorld?

Element HelloWorld służy jako szablon referencyjny , który otrzymuje regularne aktualizacje od firmy Microsoft. Najważniejsze powody, aby zachować niezmienione:

• Aktualizacje i ulepszenia: firma Microsoft regularnie aktualizuje aplikację HelloWorld nowymi funkcjami, poprawkami błędów i najlepszymi rozwiązaniami
• Testowanie integracji: HelloWorld gwarantuje, że środowisko działa prawidłowo
• Dokumentacja referencyjna: służy jako dokumentacja na żywo dotycząca wzorców implementacji
• Zgodność z poprzednimi wersjami: aktualizacje zachowują zgodność z istniejącymi dostosowaniami

Zalecany przepływ pracy

1. Zachowaj nietknięty element HelloWorld: użyj go jako odwołania i elementu testowego
2. Tworzenie nowych elementów: użyj skryptu lub pomocy sztucznej inteligencji, aby utworzyć oddzielne elementy
3. Regularne aktualizacje: okresowo ściągaj aktualizacje z repozytorium podstawowego
4. Wzorce łączenia: Zastosuj nowe wzorce z zaktualizowanego HelloWorld do elementów niestandardowych

Najlepsze rozwiązania dotyczące tworzenia elementów

Architektura komponentów:

• ✅ Postępuj zgodnie ze wzorcem 4-składników (Definicja, Edytor, Pusty, Wstążka)
• ✅ Używanie kontenera ItemEditor w celu zapewnienia spójnego układu i zachowania
• ✅ Implementowanie prawidłowych stanów ładowania i obsługi błędów
• ✅ Postępuj zgodnie z wzorcami projektowymi interfejsu użytkownika Fluent

Zarządzanie danymi:

• ✅ Użyj saveWorkloadItem() dla elementów ze złożonymi danymi
• ✅ Użyj getWorkloadItem() do ładowania z domyślnymi wartościami zapasowymi
• ✅ Implementowanie odpowiednich interfejsów Języka TypeScript w pliku definicji
• ✅ Obsługa niezdefiniowanych/pustych stanów w sposób bezproblemowy

Środowisko użytkownika:

• ✅ Zapewnij przejrzyste stany początkowe dla użytkowników korzystających po raz pierwszy
• ✅ Używaj odpowiednich wskaźników ładowania
• ✅ Implementowanie przydatnych komunikatów o błędach
• ✅ Postępuj zgodnie z wzorcami projektowymi Fabric i wytycznymi dotyczącymi dostępności

Zagadnienia dotyczące wydajności

• Ładowanie z opóźnieniem: ładowanie tylko danych w razie potrzeby
• Wydajne aktualizacje: użyj wzorców React, aby zminimalizować ponowne renderowanie
• Integracja z usługą OneLake: użyj createItemWrapper() do właściwego określania zakresu
• Granice błędów: Implementowanie właściwej obsługi błędów w całym systemie

Dalsze kroki

Po utworzeniu elementu:

1. Dostosowywanie modelu danych: aktualizowanie pliku definicji przy użyciu określonych interfejsów
2. Implementowanie podstawowych funkcji: tworzenie głównych funkcji w składniku Edytor
3. Projektowanie pustego stanu: Tworzenie angażującego doświadczenia dla nowych użytkowników
4. Skonfiguruj akcje: Skonfiguruj odpowiednie akcje Wstążki dla przepływu pracy
5. Dokładnie przetestuj: sprawdź wszystkie funkcje w środowisku projektowym
6. Przygotowanie do produkcji: postępuj zgodnie z przewodnikiem publikowania , gdy wszystko będzie gotowe

Rozwiązywanie problemów

Element nie pojawia się w planie pracy:

• ✅ Sprawdź ITEM_NAMES we wszystkich plikach .env
• ✅ Weryfikowanie konfiguracji Product.json
• ✅ Ponowne uruchamianie serwera programistycznego

Błędy kompilacji:

• ✅ Sprawdzanie interfejsów TypeScript w pliku definicji
• ✅ Sprawdź, czy wszystkie importy są poprawne
• ✅ Upewnij się, że routing jest prawidłowo skonfigurowany

Błędy środowiska uruchomieniowego:

• ✅ Sprawdź konsolę przeglądarki, aby uzyskać szczegółowe komunikaty o błędach
• ✅ Weryfikowanie integracji i uwierzytelniania interfejsu API
• ✅ Najpierw przetestuj z uproszczonymi danymi

Dodatkowe zasoby

• Dokumentacja kontrolki ItemEditor
• OneLake Integration Guide
• Użycie Fabric API
• Wymagania dotyczące publikowania

Szczęśliwe kodowanie! 🚀