SxDialog UI 设计规范

自动生成时间: 2026-02-04 组件路径: src/NextUI.Blazor/Components/SxDialog.razor

1. 组件概述

  • 组件包含 5 个参数，0 个回调，1 个公开方法。
  • 内部组合组件：SxButton, SxIcon。

2. 组件模式

模式 条件 说明
条件渲染 Visible || !Hidden 影响局部渲染块
条件渲染 ShowDismiss 影响局部渲染块
条件渲染 Footer != null || !string.IsNullOrEmpty(PrimaryAction 影响局部渲染块
条件渲染 Footer != null 影响局部渲染块
条件渲染 !string.IsNullOrEmpty(SecondaryAction 影响局部渲染块
条件渲染 !string.IsNullOrEmpty(PrimaryAction 影响局部渲染块

3. 表单字段

字段组件 绑定
- -

4. 操作按钮

外观 动作/链接 禁用条件
ButtonAppearance.Stealth CloseAsync -
ButtonAppearance.Outline - -
ButtonAppearance.Accent - -

5. 验证规则

未检测到显式验证标记。

6. 状态与流程

内部状态字段： 未检测到明确状态字段。

7. 公共 API

7.1 Parameters

参数 类型 默认值 说明
Size ControlSize ControlSize.Medium
Modal bool true
ShowDismiss bool true
TrapFocus bool true
Width string? "500px"

7.2 Public Methods

  • CloseAsync: Task

7.3 Events/Callbacks

无回调事件。

8. 典型使用场景 (Use Cases)

8.1 UC-1: 基础渲染

  1. 组件渲染默认状态
  2. 关键区域可见
  3. 无异常

9. 状态不变性测试 (State Invariants)

  • 同一参数重复设置不应触发非必要 UI 改变
  • 与表单字段无关的操作不应影响字段值

10. 测试检查点

  • 条件 Visible || !Hidden 下渲染正确
  • 条件 ShowDismiss 下渲染正确
  • 条件 Footer != null || !string.IsNullOrEmpty(PrimaryAction 下渲染正确
  • 条件 Footer != null 下渲染正确
  • 条件 !string.IsNullOrEmpty(SecondaryAction 下渲染正确
  • 条件 !string.IsNullOrEmpty(PrimaryAction 下渲染正确

11. Fluent UI 对齐

对应 Fluent UI Blazor 组件：FluentDialog + FluentDialogProvider 源码：src/Core/Components/Dialog/* 对齐要点：

  • DialogParameters.Alignment 不支持 HorizontalAlignment.Stretch（设置会抛异常）。
  • 默认宽度 500px（Dialog），Panel 模式默认宽度 340px；高度仅在 Center 对齐时生效。
  • PreventDismissOnOverlayClick=false 时遮罩点击触发关闭。
  • Provider 监听路由变化自动 DismissAll。
  • 关闭时可执行 ValidateDialogAsync，失败则阻止关闭。 关键参数/事件：
  • 组件参数：Hidden/HiddenChanged、Modal、TrapFocus、PreventScroll、Aria*。
  • DialogParameters：Title、ShowTitle、ShowDismiss、PrimaryAction/SecondaryAction、Width/Height、DialogType。
  • 事件：OnDialogOpened、OnDialogClosing、OnDialogResult。 差异与扩展：
  • SxDialog 需对齐 Provider 生命周期与对齐/宽高限制逻辑。

12. 参考文档摘要

  • docs/ComponentInventory.md: NextUI 组件全量版图审计 (Fluent UI v4.13.2 对齐) 本文档作为 NextUI 设计系统的“全量施工蓝图”，实时对齐 Microsoft Fluent UI Blazor v4.13.2 官方组件库。所有组件分为已实现 [x]、开发中 [-] 和待开发 [ ] 状态。
  • docs/ComponentAPIGuide.md: Next UI Component API Guide (Standard Interface) 本指南定义了 Next UI 组件的标准接口。我们的目标是 API 兼容优先，确保与 Microsoft Fluent UI Blazor 库的命名习惯对齐。
  • docs/CODE_QUALITY_IMPROVEMENT_PROGRESS.md: 代码质量改进进度 > 创建日期: 2026-01-13

13. 规范合规检查

  • 未检测到明显硬编码颜色/px。

14. 变更历史

  • 2026-02-04: 深度分析填充规范。