SxMessageBar UI 设计规范
自动生成时间: 2026-02-05 组件路径: src/NextUI.Blazor/Components/SxMessageBar.razor
1. 组件概述
用于展示系统通知、警告与操作结果的消息栏组件。支持不同严重级别、可关闭、可渲染自定义内容或 HTML。
2. 组件模式
| 模式 | 条件 | 说明 |
|---|---|---|
| 可见 | !_dismissed |
默认渲染消息栏 |
| 已关闭 | _dismissed == true |
点击关闭后隐藏组件 |
| 标题显示 | !string.IsNullOrEmpty(Title) |
显示标题区域 .sx-message-bar-title |
| 自定义内容 | ChildContent != null |
使用 ChildContent 渲染主体 |
| HTML 内容 | AllowHtml && !string.IsNullOrEmpty(Message) |
Message 以 HTML 渲染 |
| 文本内容 | 以上条件不满足 | Message 作为文本渲染 |
| 可关闭 | IsDismissable == true |
显示关闭按钮 |
| 不可关闭 | IsDismissable == false |
不显示关闭按钮 |
| 禁用 | Disabled || Loading |
根元素加 sx-is-disabled，关闭按钮禁用 |
| 意图: Info | Intent == Info |
添加类 sx-message-bar--info，图标 circle-info |
| 意图: Success | Intent == Success |
添加类 sx-message-bar--success，图标 circle-check |
| 意图: Warning | Intent == Warning |
添加类 sx-message-bar--warning，图标 triangle-exclamation |
| 意图: Error | Intent == Error |
添加类 sx-message-bar--error，图标 circle-xmark |
3. 表单字段
无。
4. 操作按钮
| 外观 | 动作/链接 | 禁用条件 |
|---|---|---|
关闭按钮 .sx-message-bar-close |
调用 HandleDismiss，触发 OnDismiss 并隐藏组件 |
Disabled || Loading |
5. 验证规则
未检测到显式验证逻辑。
6. 状态转换图
[Visible]
| (IsDismissable && !IsDisabled) click close
v
[Dismissed]
- IsDismissable=false: 无关闭入口
- IsDisabled=true: 点击无效，保持 Visible
7. 公共 API
7.1 Parameters
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Message |
string? |
null |
消息文本内容。 |
ChildContent |
RenderFragment? |
null |
自定义内容，优先级高于 Message。 |
Intent |
MessageIntent |
Info |
严重级别，决定样式与图标。 |
IsDismissable |
bool |
true |
是否显示关闭按钮。 |
AllowHtml |
bool |
false |
允许将 Message 作为 HTML 渲染。 |
OnDismiss |
EventCallback |
null |
点击关闭按钮回调。 |
Disabled (继承) |
bool |
false |
禁用状态。 |
Loading (继承) |
bool |
false |
加载状态。 |
Id (继承) |
string? |
null |
根元素 Id。 |
Class (继承) |
string? |
null |
追加 CSS 类。 |
Style (继承) |
string? |
null |
追加内联样式。 |
Title (继承) |
string? |
null |
HTML title 属性，同时显示为消息栏标题。 |
TabIndex (继承) |
int? |
null |
组件 TabIndex。 |
AccessKey (继承) |
string? |
null |
访问键。 |
AdditionalAttributes (继承) |
IEnumerable<KeyValuePair<string, object>>? |
null |
其他 HTML 属性。 |
7.2 Public Methods
无。
7.3 Events/Callbacks
| 事件 | 类型 | 说明 |
|---|---|---|
OnDismiss |
EventCallback |
用户点击关闭按钮时触发。 |
8. 典型使用场景 (Use Cases)
8.1 UC-1: 默认消息
- 设置
Message - 组件以 Info 样式渲染
- 显示默认图标与内容
8.2 UC-2: HTML 消息
- 设置
AllowHtml=true与MessageHTML 字符串 - 组件渲染 HTML 内容
- 确认文本内容以 HTML 方式展示
8.3 UC-3: 自定义内容
- 提供
ChildContent - 组件渲染自定义内容
Message被忽略
8.4 UC-4: 关闭消息
IsDismissable=true且未禁用- 点击关闭按钮
- 触发
OnDismiss并隐藏组件
9. 状态不变性测试 (State Invariants)
- 变更
Intent不应改变Message/ChildContent内容 - 切换
IsDismissable不应改变当前消息内容 Disabled=true不应触发关闭或回调
10. 测试检查点
10.1 必须测试 (单元测试)
- 默认渲染包含
.sx-message-bar与 body -
Intent对应 class 与图标正确 -
IsDismissable控制关闭按钮显隐 -
AllowHtml时 HTML 内容可渲染 -
ChildContent优先于Message - 点击关闭触发
OnDismiss并隐藏 - 禁用时关闭按钮不可用、不会关闭
10.2 边界情况
-
Message为空时仅渲染结构 -
Title为空时不渲染标题区
10.3 状态不变性测试
- 切换
Intent不影响消息文本 - 禁用切换不影响消息文本
10.4 Use Case 集成测试
- 基础消息、HTML 消息、自定义内容覆盖
10.5 E2E 测试 (Playwright)
- Workbench 页面
/components/SxMessageBar基础渲染
11. 规范合规检查
11.1 组件使用
- 内部组件允许使用基础 HTML 标签
- 未在外部页面直接使用原生输入元素
11.2 样式
- 使用 Design Tokens，无硬编码颜色/间距
12. 已知问题 / TODO
- 若需要消息队列或自动关闭，需扩展 Provider 能力。
13. 变更历史
- 2026-02-05: 同步实现与测试要求。