Back to Details

use-igniteui-blazor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Application Setup & Component Registration

应用设置与组件注册

1. NuGet package

1. NuGet 包

Before adding packages, inspect the target projects' target framework and existing package references. The lowest supported target framework version is .NET 8.0. If 
IgniteUI.Blazor
or 
IgniteUI.Blazor.Trial
is already referenced, keep that package strategy and do not add Lite or GridLite. Only switch package families when the user explicitly asks, replacing conflicting references rather than keeping both.
bash
dotnet add package IgniteUI.Blazor.Lite       # OSS core UI components (MIT)
dotnet add package IgniteUI.Blazor.GridLite   # OSS lightweight grid (MIT)
Use 
IgniteUI.Blazor.Lite
for core controls such as 
IgbInput
, 
IgbCombo
and 
IgbDialog
, and 
IgniteUI.Blazor.GridLite
for the lightweight grid. Reference both packages only when the app needs both. Do not invent per-component packages such as 
IgniteUI.Blazor.Combo
.
Charts, maps, gauges and other premium components are not included in Lite. Check the requested component's package before recommending a reference.
添加包之前，请检查目标项目的目标框架和现有包引用。最低支持的目标框架版本为 .NET 8.0。如果已引用 
IgniteUI.Blazor
或 
IgniteUI.Blazor.Trial
，请保持该包策略，不要添加 Lite 或 GridLite。仅当用户明确要求时才切换包系列，需替换冲突的引用而非同时保留两者。
bash
dotnet add package IgniteUI.Blazor.Lite       # OSS core UI components (MIT)
dotnet add package IgniteUI.Blazor.GridLite   # OSS lightweight grid (MIT)
IgniteUI.Blazor.Lite
用于 
IgbInput
、
IgbCombo
、
IgbDialog
等核心控件，
IgniteUI.Blazor.GridLite
用于轻量级网格。仅当应用同时需要两者时才引用这两个包。请勿虚构按组件拆分的包，例如 
IgniteUI.Blazor.Combo
。
图表、地图、仪表及其他高级组件不包含在 Lite 版本中。推荐引用前请先确认所需组件所属的包。

2. 
IgniteUI.Blazor.Lite
Service Registration

2. 
IgniteUI.Blazor.Lite
服务注册

Usually in 
Program.cs
:
csharp
builder.Services.AddIgniteUIBlazor();   // no modules pre-loaded; each loads on first render
Pass 
typeof(Igb<Name>Module)
values to eagerly pre-load a specific set instead:
csharp
builder.Services.AddIgniteUIBlazor(
    typeof(IgbInputModule), typeof(IgbComboModule), typeof(IgbDialogModule));
Module names always follow 
Igb{ComponentName}Module
. Passing modules eagerly loads them during startup, increasing the initial transfer to reduce first-render latency. Components not listed still register their own modules on first render.
For a GridLite-only setup, do not call 
AddIgniteUIBlazor()
or add manual Ignite UI script tags. Reference 
IgniteUI.Blazor.GridLite
, add the control namespace, and link the GridLite stylesheet shown below.
Split Blazor Web App: add each required package to both the Server and Client 
.csproj
files. For core controls, use the actual project paths in place of these examples.
bash
dotnet add Server/Server.csproj package IgniteUI.Blazor.Lite
dotnet add Client/Client.csproj package IgniteUI.Blazor.Lite
If GridLite is needed, add 
IgniteUI.Blazor.GridLite
to both projects as well. For a GridLite-only app, add only that package and skip the service registrations below.
For Lite, call 
AddIgniteUIBlazor()
in both the server and client 
Program.cs
.
csharp
// Server
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();
builder.Services.AddIgniteUIBlazor();

// Client (WebAssemblyHostBuilder)
builder.Services.AddIgniteUIBlazor();
For a single-project Interactive Server Blazor Web App, call 
AddIgniteUIBlazor()
once in the server 
Program.cs
. Do not add a client project or WebAssembly services.
通常在 
Program.cs
中配置：
csharp
builder.Services.AddIgniteUIBlazor();   // no modules pre-loaded; each loads on first render
也可以传入 
typeof(Igb<Name>Module)
参数，主动预加载指定的模块集合：
csharp
builder.Services.AddIgniteUIBlazor(
    typeof(IgbInputModule), typeof(IgbComboModule), typeof(IgbDialogModule));
模块名称始终遵循 
Igb{组件名}Module
的格式。主动传入模块会在启动时加载它们，会增加初始传输量，但能减少首次渲染延迟。未列出的组件仍会在首次渲染时自行注册对应的模块。
对于仅使用 GridLite 的配置，请勿调用 
AddIgniteUIBlazor()
或手动添加 Ignite UI 脚本标签。只需引用 
IgniteUI.Blazor.GridLite
、添加控件命名空间，并链接下文所示的 GridLite 样式表即可。
拆分式 Blazor Web App： 将所需的每个包都添加到 Server 和 Client 两个项目的 
.csproj
文件中。对于核心控件，请使用实际项目路径替换示例中的路径。
bash
dotnet add Server/Server.csproj package IgniteUI.Blazor.Lite
dotnet add Client/Client.csproj package IgniteUI.Blazor.Lite
如果需要 GridLite，也请将 
IgniteUI.Blazor.GridLite
添加到两个项目中。对于仅使用 GridLite 的应用，只需添加该包，跳过下方的服务注册步骤。
对于 Lite 版本，请在服务端和客户端的 
Program.cs
中都调用 
AddIgniteUIBlazor()
。
csharp
// Server
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();
builder.Services.AddIgniteUIBlazor();

// Client (WebAssemblyHostBuilder)
builder.Services.AddIgniteUIBlazor();
对于单项目的交互服务端 Blazor Web App，只需在服务端的 
Program.cs
中调用一次 
AddIgniteUIBlazor()
即可。无需添加客户端项目或 WebAssembly 相关服务。

3. 
_Imports.razor

3. 
_Imports.razor

razor
@using IgniteUI.Blazor.Controls
Add it to both 
_Imports.razor
files in split Blazor Web App solutions.
razor
@using IgniteUI.Blazor.Controls
在拆分式 Blazor Web App 解决方案中，请将该语句添加到两个 
_Imports.razor
文件中。

4. Host page — theme stylesheet

4. 宿主页面 — 主题样式表

Host page is 
wwwroot/index.html
(WASM/MAUI), 
Pages/_Host.cshtml
(Server), or 
Components/App.razor
(Web App).
IgniteUI.Blazor.Lite
0.1.1 loads its JavaScript automatically through a Blazor initializer. Keep the existing Blazor framework script and add the theme stylesheet below. Do not add a manual Ignite UI script tag.
html
<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
The stylesheet is required: without it components render unstyled.
Theme files under 
_content/IgniteUI.Blazor/themes/
are 
{light|dark}/{bootstrap|material|fluent|indigo}.css
— link exactly one.
.NET 9+ Web App projects can use the fingerprinted asset collection:
razor
<link rel="stylesheet" href="@Assets["_content/IgniteUI.Blazor/themes/light/bootstrap.css"]" />
IgniteUI.Blazor.GridLite
ships its own stylesheet from its own asset root, but should be used only if you are using the GridLite component exclusively. If you are using other Ignite UI components, do not link (or suggest) the GridLite stylesheet — use the main theme stylesheet above instead.
html
<link href="_content/IgniteUI.Blazor.GridLite/css/themes/light/bootstrap.css" rel="stylesheet" />
宿主页面为 
wwwroot/index.html
（WASM/MAUI）、
Pages/_Host.cshtml
（Server）或 
Components/App.razor
（Web App）。
IgniteUI.Blazor.Lite
0.1.1 版本通过 Blazor 初始化器自动加载其 JavaScript。请保留现有的 Blazor 框架脚本，添加下方的主题样式表即可，无需手动添加 Ignite UI 脚本标签。
html
<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
样式表是必需的：缺少它的话组件会无样式渲染。
主题文件路径 
_content/IgniteUI.Blazor/themes/
下的文件格式为 
{light|dark}/{bootstrap|material|fluent|indigo}.css
—— 请仅链接其中一个。
.NET 9 及以上版本的 Web App 项目可以使用带指纹的资产集合：
razor
<link rel="stylesheet" href="@Assets["_content/IgniteUI.Blazor/themes/light/bootstrap.css"]" />
IgniteUI.Blazor.GridLite
从自身的资产根目录提供独立的样式表，但仅当你只使用 GridLite 组件时才应使用该样式表。如果你还使用其他 Ignite UI 组件，请勿链接（或推荐）GridLite 样式表——改用上方的主主题样式表。
html
<link href="_content/IgniteUI.Blazor.GridLite/css/themes/light/bootstrap.css" rel="stylesheet" />

5. Render mode (Blazor Web App only)

5. 渲染模式（仅 Blazor Web App 适用）

Ignite UI components need an interactive render mode; static SSR renders nothing usable.
razor
@rendermode InteractiveServer
Or globally in 
App.razor
: 
<Routes @rendermode="InteractiveServer" />
.
Use 
InteractiveWebAssembly
or 
InteractiveAuto
in place of 
InteractiveServer
as needed.
Ignite UI 组件需要交互渲染模式；静态 SSR 无法渲染出可用的内容。
razor
@rendermode InteractiveServer
或者在 
App.razor
中全局配置：
<Routes @rendermode="InteractiveServer" />
。
可根据需要使用 
InteractiveWebAssembly
或 
InteractiveAuto
替换 
InteractiveServer
。