37

前端组件与页面开发（Blazor 指南）

简介

本文档旨在全面介绍基于 Blazor 的前端组件体系与页面开发流程，重点讲解布局、表单、表格等核心组件的使用与扩展。同时，将说明 UIContext、页面模型等关键概念及其与后端服务的集成方式。

项目结构

项目采用模块化设计，主要分为以下几个部分：

  1. Known：核心组件库，包含基础布局、表单、表格等核心功能。
  2. Known.Core：后端服务核心逻辑，提供数据访问和业务逻辑支持。
  3. Plugins：插件模块，如 Known.Admin 和 Known.Cells，用于扩展功能。
  4. Shared：共享代码库，包含通用工具类和数据库访问逻辑。
  5. Sample：示例项目，展示如何集成和使用核心组件。

主要目录结构

  1. Known/Blazor：包含 Blazor 的核心组件和上下文管理。
    • Base.Layout.cs：基础布局组件。
    • UIContext.cs：UI 上下文管理。
    • TableModel.cs：表格模型定义。
  2. Known/Components：核心组件实现。
    • AppForm.razor：表单组件。
    • KTable.razor：表格组件。
  3. Known/Pages：页面组件。
    • IndexPage.cs：首页。
    • LoginPage.cs：登录页。
  4. Plugins/Known.Admin：管理后台插件。
    • AdminOption.cs：管理选项配置。
classDiagram
  class BaseLayout {
    +IsAdmin: bool
    +UserMenus: List<MenuInfo>
    +ShowSpinAsync(text: string, action: Func<Task>): Task
    +SignInAsync(user: UserInfo): Task
    +SignOutAsync(): Task
  }
  class UIContext {
    +IsEditMode: bool
    +UserSetting: UserSettingInfo
    +UI: UIService
    +App: BaseLayout
  }
  class TableModel {
    +Id: string
    +Columns: List<ColumnInfo>
    +Reload(): void
    +SearchAsync(): Task
  }
  BaseLayout --> UIContext: 包含
  UIContext --> TableModel: 使用

核心组件

1. BaseLayout

基础布局组件，提供页面框架和用户认证功能。

  • 功能：
    • 管理用户菜单和权限。
    • 提供登录和注销功能。
    • 支持多标签页布局。

2. UIContext

UI 上下文管理类，用于管理页面状态和用户设置。

  • 关键属性：
    • IsEditMode：是否处于编辑模式。
    • UserSetting：用户个性化设置。
    • UI：UI 服务实例，提供弹窗和消息功能。

3. TableModel

表格模型，用于定义表格的行为和数据结构。

  • 功能：
    • 支持分页和高级搜索。
    • 提供默认查询条件和列配置。
// 示例代码：表格模型初始化
var model = new TableModel(page) {
    Id = "userTable",
    Columns = new List<ColumnInfo> {
        new ColumnInfo { Id = "Name", Title = "姓名" },
        new ColumnInfo { Id = "Age", Title = "年龄" }
    }
};

架构概述

项目采用分层架构，前端通过 Blazor 组件实现交互逻辑，后端通过 Known.Core 提供服务支持。UIContext 作为桥梁，连接前后端逻辑。

数据流

  1. 用户操作触发 Blazor 组件事件。
  2. 组件通过 UIContext 调用后端服务。
  3. 后端返回数据，组件更新 UI。
sequenceDiagram
  participant User
  participant BlazorComponent
  participant UIContext
  participant BackendService
  User->>BlazorComponent: 点击按钮
  BlazorComponent->>UIContext: 调用方法
  UIContext->>BackendService: 请求数据
  BackendService-->>UIContext: 返回结果
  UIContext-->>BlazorComponent: 更新状态
  BlazorComponent->>User: 刷新界面

详细组件分析

1. KTable.razor

表格组件，支持动态列配置和数据绑定。

  • 功能：
    • 支持分页、排序和筛选。
    • 提供自定义列模板。
    • 支持行内编辑。
<KTable Model="model" TItem="UserInfo">
    <Column Title="姓名" DataIndex="Name" />
    <Column Title="年龄" DataIndex="Age" />
</KTable>

2. LoginPage.cs

登录页面，处理用户认证逻辑。

  • 关键方法：
    • OnUserLogin：处理登录逻辑。
    • SetCurrentUserAsync：设置当前用户信息。
protected async Task OnUserLogin() {
    var result = await Admin.SignInAsync(Model);
    if (result.IsValid) {
        await SetCurrentUserAsync(result.DataAs<UserInfo>());
        Context.GoHomePage();
    }
}

依赖分析

1. 组件依赖

  • BaseLayout 依赖 UIContext 管理状态。
  • KTable 依赖 TableModel 定义行为。

2. 后端集成

  • 通过 AdminService 提供用户管理功能。
  • Database 类封装数据库访问逻辑。

性能考虑

  1. 表格性能：
    • 使用虚拟滚动优化大数据量渲染。
    • 分页加载减少初始数据量。
  2. 状态管理：
    • UIContext 采用轻量级设计，避免不必要的状态更新。

故障排除指南

常见问题

  1. 登录失败：
    • 检查后端服务是否正常运行。
    • 确保 AuthProvider 已正确注入。
  2. 表格加载慢：
    • 检查数据量是否过大，启用分页功能。

结论

本文档详细介绍了基于 Blazor 的前端组件体系，涵盖了核心组件、架构设计和实际应用场景。通过 UIContext 和页面模型的结合，实现了灵活且高效的开发流程。