ASP.NET Core Blazor CSS izolacja

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Autor: Dave Brock

W tym artykule wyjaśniono, jak izolacja CSS określa zakresy CSS dla Razor składników, co może uprościć arkusz CSS i uniknąć kolizji z innymi składnikami lub bibliotekami.

Izolowanie stylu CSS do pojedynczych stron, widoków i składników umożliwia zmniejszenie lub uniknięcie:

  • Zależności stylów globalnych, które mogą być trudne do utrzymania.
  • Konfliktów stylów w zawartości zagnieżdżonej.

Włączanie izolacji CSS

Aby zdefiniować style specyficzne dla składników, utwórz .razor.css plik pasujący do nazwy .razor pliku dla składnika w tym samym folderze. Plik .razor.css jest plikiem CSS o określonym zakresie.

Example W przypadku składnika w Example.razor pliku utwórz plik obok składnika o nazwie Example.razor.css. Plik Example.razor.css musi znajdować się w tym samym folderze co Example składnik (Example.razor). Podstawowa nazwa pliku "Example" nie uwzględnia wielkości liter.

Example.razor:

@page "/example"

<h1>Scoped CSS Example</h1>

Example.razor.css:

h1 { 
    color: brown;
    font-family: Tahoma, Geneva, Verdana, sans-serif;
}

Style zdefiniowane w elemencie Example.razor.css są stosowane tylko do renderowanych danych wyjściowych Example składnika. Izolacja CSS jest stosowana do elementów HTML w pasującym Razor pliku. Wszystkie h1 deklaracje CSS zdefiniowane w innym miejscu w aplikacji nie powodują konfliktu ze stylami Example składnika.

Uwaga

Aby zagwarantować izolację stylu podczas tworzenia pakietów, importowanie arkuszy CSS w Razor blokach kodu nie jest obsługiwane.

Tworzenie pakietów izolacji CSS

Izolacja stylów CSS ma miejsce w czasie kompilacji. Blazor Ponownie zapisuje selektory CSS, aby dopasować znaczniki renderowane przez składnik. Przepisane style CSS są umieszczane w pakiecie i tworzone jako statyczny element zawartości. Do arkusza stylów odwołuje się <head> tag (lokalizacja <head> zawartości). <link> Następujący element jest domyślnie dodawany do aplikacji utworzonej Blazor na podstawie szablonów projektu, gdzie symbol zastępczy {ASSEMBLY NAME} to nazwa zestawu projektu:

<link href="{ASSEMBLY NAME}.styles.css" rel="stylesheet">

Poniższy przykład pochodzi z hostowanej Blazor WebAssemblyClient aplikacji. Nazwa zestawu aplikacji to BlazorSample.Client, a <link> element jest dodawany przez Blazor WebAssembly szablon projektu podczas tworzenia projektu z opcją Hostowana (-ho|--hosted opcja przy użyciu interfejsu wiersza polecenia platformy .NET lub ASP.NET Core Hosted przy użyciu programu Visual Studio):

<link href="BlazorSample.Client.styles.css" rel="stylesheet">

W pliku dołączonym każdy składnik jest skojarzony z identyfikatorem zakresu. Dla każdego ze stylisowanych składników atrybut HTML jest dołączany z formatem b-{STRING}, gdzie {STRING} symbol zastępczy jest ciągiem dziesięć znaków wygenerowanym przez strukturę. Identyfikator jest unikatowy dla każdej aplikacji. W renderowany Counter składnik Blazor dołącza identyfikator zakresu do h1 elementu :

<h1 b-3xxtam6d07>

Plik {ASSEMBLY NAME}.styles.css używa identyfikatora zakresu do grupowania deklaracji stylu ze składnikiem. W poniższym przykładzie przedstawiono styl poprzedniego <h1> elementu:

/* /Components/Pages/Counter.razor.rz.scp.css */
h1[b-3xxtam6d07] {
    color: brown;
}

W czasie kompilacji pakiet projektu jest tworzony przy użyciu konwencji obj/{CONFIGURATION}/{TARGET FRAMEWORK}/scopedcss/projectbundle/{ASSEMBLY NAME}.bundle.scp.css, gdzie symbole zastępcze to:

  • {CONFIGURATION}: konfiguracja kompilacji aplikacji (na przykład Debug, Release).
  • {TARGET FRAMEWORK}: Struktura docelowa (na przykład net6.0).
  • {ASSEMBLY NAME}: nazwa zestawu aplikacji (na przykład BlazorSample).

Obsługa składników podrzędnych

Domyślnie izolacja CSS ma zastosowanie tylko do składnika skojarzonego z formatem {COMPONENT NAME}.razor.css, gdzie symbol zastępczy {COMPONENT NAME} jest zwykle nazwą składnika. Aby zastosować zmiany do składnika podrzędnego, użyj ::deeppseudo-elementu do wszystkich elementów podrzędnych w pliku składnika nadrzędnego .razor.css . Pseudoelement ::deep wybiera elementy, które są elementami podrzędnymi wygenerowanego identyfikatora zakresu elementu.

W poniższym przykładzie pokazano składnik nadrzędny o nazwie Parent z składnikiem podrzędnym o nazwie Child.

Parent.razor:

@page "/parent"

<div>
    <h1>Parent component</h1>

    <Child />
</div>

Child.razor:

<h1>Child Component</h1>

Zaktualizuj deklarację h1 w Parent.razor.css elemencie ::deep pseudo-element, aby oznaczyć h1 deklarację stylu, musi mieć zastosowanie do składnika nadrzędnego i jego elementów podrzędnych.

Parent.razor.css:

::deep h1 { 
    color: red;
}

Styl h1 ma teraz zastosowanie do Parent składników i Child bez konieczności tworzenia oddzielnego pliku CSS o określonym zakresie dla składnika podrzędnego.

Pseudo-element ::deep działa tylko z elementami potomnymi. Poniższy znacznik stosuje h1 style do składników zgodnie z oczekiwaniami. Identyfikator zakresu składnika nadrzędnego div jest stosowany do elementu, więc przeglądarka wie, że dziedziczy style ze składnika nadrzędnego.

Parent.razor:

<div>
    <h1>Parent</h1>

    <Child />
</div>

Jednak wykluczenie div elementu spowoduje usunięcie relacji potomnych. W poniższym przykładzie styl nie jest stosowany do składnika podrzędnego.

Parent.razor:

<h1>Parent</h1>

<Child />

Pseudo-element ::deep wpływa na to, gdzie atrybut zakresu jest stosowany do reguły. Podczas definiowania reguły CSS w pliku CSS o określonym zakresie zakres zakres jest stosowany do odpowiedniego najbardziej elementu domyślnie. Na przykład: div > a jest przekształcana na div > a[b-{STRING}], gdzie {STRING} symbol zastępczy jest ciągiem dziesięć znaków wygenerowanym przez strukturę (na przykład b-3xxtam6d07). Jeśli zamiast tego chcesz, aby reguła miała być stosowana do innego selektora, ::deep pseudo-element umożliwia to. Na przykład div ::deep > a element jest przekształcany na div[b-{STRING}] > a (na przykład div[b-3xxtam6d07] > a).

Możliwość dołączania ::deep pseudo-elementu do dowolnego elementu HTML umożliwia tworzenie stylów CSS o określonym zakresie, które wpływają na elementy renderowane przez inne składniki, gdy można określić strukturę renderowanych tagów HTML. W przypadku składnika, który renderuje tag hiperłącza (<a>) wewnątrz innego składnika, upewnij się, że składnik jest opakowany w div element (lub dowolny inny) i użyj reguły ::deep > a , aby utworzyć styl, który jest stosowany tylko do tego składnika, gdy składnik nadrzędny renderuje.

Ważne

Arkusz CSS o określonym zakresie dotyczy tylko elementów HTML, a nie Razor składników lub pomocników tagów, w tym elementów z zastosowanym pomocnikem tagów, na przykład <input asp-for="..." />.

Obsługa preprocesora CSS

Preprocesory CSS poprawiają tworzenie plików CSS poprzez wykorzystanie funkcji takich jak zmienne, zagnieżdżanie, moduły, domieszki i dziedziczenie. Chociaż izolacja CSS nie obsługuje natywnie preprocesorów CSS, takich jak Sass lub Mniej, integrowanie preprocesorów CSS jest bezproblemowe, o ile kompilacja preprocesora ma miejsce przed Blazor ponownym zapisywaniem selektorów CSS podczas procesu kompilacji. Na przykład przy użyciu programu Visual Studio można skonfigurować istniejącą kompilację preprocesora jako zadanie Przed kompilowaniem w eksploratorze modułu uruchamiającego zadanie programu Visual Studio.

Wiele pakietów NuGet innych firm, takich jak AspNetCore.SassCompiler, może kompilować pliki SASS/SCSS na początku procesu kompilacji przed wystąpieniem izolacji CSS.

Konfiguracja izolacji CSS

Izolacja CSS jest przeznaczona do pracy gotowej do użycia, ale zapewnia konfigurację niektórych zaawansowanych scenariuszy, takich jak gdy istnieją zależności od istniejących narzędzi lub przepływów pracy.

Dostosowywanie formatu identyfikatora zakresu

Domyślnie identyfikatory zakresu korzystają z formatu b-{STRING}, w którym symbol zastępczy {STRING} to ciąg zawierający dziesięć znaków wygenerowany przez strukturę. Aby dostosować format identyfikatora zakresu, zaktualizuj plik projektu do odpowiedniego wzorca:

<ItemGroup>
  <None Update="Components/Pages/Example.razor.css" CssScope="custom-scope-identifier" />
</ItemGroup>

W poprzednim przykładzie plik CSS wygenerowany dla pliku Example.razor.css zmienia identyfikator zakresu z b-{STRING} na custom-scope-identifier.

Użyj identyfikatorów zakresu, aby umożliwić dziedziczenie w przypadku plików CSS z określonym zakresem. W poniższym przykładzie BaseComponent.razor.css pliku projektu plik zawiera typowe style między składnikami. Plik DerivedComponent.razor.css dziedziczy te style.

<ItemGroup>
  <None Update="Components/Pages/BaseComponent.razor.css" CssScope="custom-scope-identifier" />
  <None Update="Components/Pages/DerivedComponent.razor.css" CssScope="custom-scope-identifier" />
</ItemGroup>

Użyj operatora symbolu wieloznacznego (*), aby udostępnić identyfikatory zakresu w wielu plikach:

<ItemGroup>
  <None Update="Components/Pages/*.razor.css" CssScope="custom-scope-identifier" />
</ItemGroup>

Domyślnie identyfikatory zakresu korzystają z formatu b-{STRING}, w którym symbol zastępczy {STRING} to ciąg zawierający dziesięć znaków wygenerowany przez strukturę. Aby dostosować format identyfikatora zakresu, zaktualizuj plik projektu do odpowiedniego wzorca:

<ItemGroup>
  <None Update="Pages/Example.razor.css" CssScope="custom-scope-identifier" />
</ItemGroup>

W poprzednim przykładzie plik CSS wygenerowany dla pliku Example.razor.css zmienia identyfikator zakresu z b-{STRING} na custom-scope-identifier.

Użyj identyfikatorów zakresu, aby umożliwić dziedziczenie w przypadku plików CSS z określonym zakresem. W poniższym przykładzie BaseComponent.razor.css pliku projektu plik zawiera typowe style między składnikami. Plik DerivedComponent.razor.css dziedziczy te style.

<ItemGroup>
  <None Update="Pages/BaseComponent.razor.css" CssScope="custom-scope-identifier" />
  <None Update="Pages/DerivedComponent.razor.css" CssScope="custom-scope-identifier" />
</ItemGroup>

Użyj operatora symbolu wieloznacznego (*), aby udostępnić identyfikatory zakresu w wielu plikach:

<ItemGroup>
  <None Update="Pages/*.razor.css" CssScope="custom-scope-identifier" />
</ItemGroup>

Zmienianie podstawowej ścieżki w przypadku statycznych zasobów internetowych

Plik scoped.styles.css jest generowany w katalogu głównym aplikacji. W pliku projektu użyj <StaticWebAssetBasePath> właściwości , aby zmienić ścieżkę domyślną. W poniższym przykładzie plik jest umieszczany scoped.styles.css w ścieżce _content do pozostałych zasobów aplikacji:

<PropertyGroup>
  <StaticWebAssetBasePath>_content/$(PackageId)</StaticWebAssetBasePath>
</PropertyGroup>

Wyłączanie automatycznego tworzenia pakietów

Aby zrezygnować z sposobu Blazor publikowania i ładowania plików o określonym zakresie w czasie wykonywania, użyj DisableScopedCssBundling właściwości . W przypadku korzystania z tej właściwości oznacza to, że inne narzędzia lub procesy są odpowiedzialne za pobieranie izolowanych plików CSS z obj katalogu i publikowanie i ładowanie ich w czasie wykonywania:

<PropertyGroup>
  <DisableScopedCssBundling>true</DisableScopedCssBundling>
</PropertyGroup>

Wyłączanie izolacji CSS

Wyłącz izolację CSS dla projektu, ustawiając <ScopedCssEnabled> właściwość na false wartość w pliku projektu aplikacji:

<ScopedCssEnabled>false</ScopedCssEnabled>

Obsługa biblioteki klas Razor (RCL)

Style izolowane dla składników w pakiecie NuGet lub Razor bibliotece klas (RCL) są automatycznie pakowane:

  • Aplikacja używa importów CSS do odwołowania się do powiązanych stylów listy RCL. W przypadku biblioteki klas o nazwie ClassLib i Blazor aplikacji z arkuszem BlazorSample.styles.css stylów arkusz stylów listy RCL jest importowany w górnej części arkusza stylów aplikacji:

    @import '_content/ClassLib/ClassLib.bundle.scp.css';

  • Style listy RCL w pakiecie nie są publikowane jako statyczny zasób internetowy aplikacji, która korzysta ze stylów.

Aby uzyskać więcej informacji na temat bibliotek klas Razor, zobacz następujące artykuły: