Hướng dẫn Blazor — Lily Design System

Bạn sẽ xây dựng gì

Một biểu mẫu liên hệ nhỏ — ô nhập có nhãn, nút gửi, @bind-Value liên kết, hành vi bàn phím và trình đọc màn hình thật — lúc đầu để trơn, sau đó thêm kiểu dáng, trong khoảng 10 phút.

Trước khi bắt đầu

Bạn cần git và .NET SDK 8 trở lên. Dự án Blazor nào cũng được — Blazor Web App, Server hoặc WebAssembly.

Bước 1 — Lấy mã

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-blazor-headless
dotnet build
dotnet test      # bUnit — 1,400+ cases across the catalog

Các thành phần nằm trong src/LilyBlazorHeadless/Components/ — Button.razor, TextInput.razor — mỗi cái một tệp Razor. Tham chiếu dự án đó (hoặc sao chép các tệp) từ ứng dụng Blazor của bạn và thêm @using LilyBlazorHeadless.Components vào _Imports.razor.

Bước 2 — Thành phần đầu tiên của bạn

<Button OnClick="Save">Save</Button>

Hiển thị <button class="button">. Các quy ước tham số dùng chung: Label ( aria-label để ghi đè), CssClass (nối thêm vào hook cơ sở), ChildContentvà [Parameter(CaptureUnmatchedValues = true)] attribute splatting để mọi thuộc tính HTML bổ sung đều được chuyển qua.

Bước 3 — Ghép một biểu mẫu nhỏ

<Form OnSubmit="HandleSubmit">
  <Field Label="Full name" Required="true">
    <TextInput Id="name" Label="Full name" @bind-Value="name" Required="true" />
  </Field>
  <Button Type="submit">Save</Button>
</Form>

@code {
  private string name = "";
}

Field nhận Label hiển thị làm tham số riêng thay vì thành phần nhãn lồng bên trong — chỉ truyền một lần, trên Fieldvà TextInputtương ứng Label cung cấp tên có thể tiếp cận.

Đã xác minh 2026-08-29: bản nháp trước lồng một thành phần Label riêng bên trong Field, khiến hiển thị hai nhãn (một cái rỗng) vì Field đã tự hiển thị nhãn của nó từ Label tham số — phát hiện nhờ kiểm tra mã nguồn thành phần; Form tự nó không có Label tham số, nên cách dùng <Form> trong bản nháp trước đã được sửa để bỏ nó đi thay vì bịa ra một thuộc tính không tồn tại. Tuyến biểu mẫu liên hệ ghép sẵn cũng theo mẫu này, được kiểm chứng bằng các bài kiểm thử e2e và axe thật.

Kiểm tra kết quả: chạy ứng dụng và biểu mẫu trông trơ — đúng như dự định: kiểu dáng còn ở phía trước. Nhấn Tab: tiêu điểm di chuyển qua mọi điều khiển, nhãn được đọc lên và việc gửi hoạt động. Hành vi đã xong; diện mạo là của bạn và là bước tiếp theo.

Bước 4 — Tạo kiểu dáng

Tạo kiểu cho các class hook — .button, .text-input, .label, .field — trong app.csshoặc liên kết một chủ đề dựng sẵn trong App.razor / index.html:

<link rel="stylesheet" href="themes/wireframe.css" />

Bước 5 — Xem mọi thứ hoạt động

Ứng dụng ví dụ Blazor Web hiển thị toàn bộ danh mục có kiểu dáng và bản demo, cùng các bài kiểm thử Playwright e2e:

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-blazor-web-examples
dotnet run --project src/LilyBlazorWebExamples

Các bước tiếp theo

Chủ đề — chuyển đổi khi chạy bằng trợ giúp theme-picker của Blazor (thư viện lớp Razor trên NuGet).
Trợ giúp tùy chọn — ngôn ngữ và cỡ chữ.
Danh mục thành phần — thuộc tính, ARIA và bàn phím của từng thành phần.

Có thắc mắc trên đường đi? Trang trợ giúp có đầy câu trả lời — và nếu một bước có thể rõ ràng hơn, hãy cho chúng tôi biết và chúng tôi sẽ vui lòng cải thiện hướng dẫn.