SxTileButton (磁贴按钮)

  • Implemented

上方大图标 + 下方小标签的磁贴式按钮，适用于发现页、启动器、工具箱等网格布局场景。 支持多种形状、大小、语义颜色、填充模式，以及单行/双行标签。

设计原则

  • 图标居上、标签居下：视觉层级清晰，一眼识别功能
  • 语义色彩：使用设计 Token 的语义色，非硬编码颜色值
  • 四种填充模式：Subtle (边框+浅背景) / Filled (实心) / Outline (仅边框) / Ghost (透明)
  • 三种大小：Small (3rem) / Medium (4rem) / Large (5rem)，图标与容器等比缩放
  • 响应式标签：支持单行截断和双行截断，紧凑行距

API

Parameters (参数)

状态 参数名 类型 默认值 描述
[x] Icon string? null 图标名称，兼容 SxIcon。
[x] Label string? null 图标下方的文本标签。
[x] Size TileButtonSize Medium 大小：Small (3rem), Medium (4rem), Large (5rem)。
[x] Shape TileButtonShape Circle 图标容器形状：Circle, Rounded, Square。
[x] Variant TileButtonVariant Subtle 填充模式：Subtle (边框+浅背景), Filled (实心), Outline (仅边框), Ghost (透明)。
[x] Appearance TileButtonAppearance Neutral 语义颜色：Neutral, Brand, Success, Warning, Danger。
[x] LabelLines int 1 标签行数：1 = 单行截断, 2 = 双行截断 (行距 1.2)。
[x] Disabled (继承) bool false 是否禁用交互。
[x] Loading (继承) bool false 是否处于加载状态。
[x] Href string? null 导航链接，点击时通过 NavigationManager 跳转。
[x] AriaLabel string? null 无障碍标签，覆盖默认的 Label 文本。
[x] IconContainerClass string? null 图标容器的附加 CSS 类。
[x] IconContainerStyle string? null 图标容器的附加内联样式。
[x] IconStyle string? null 图标元素的附加内联样式。
[x] LabelClass string? null 标签的附加 CSS 类。
[x] LabelStyle string? null 标签的附加内联样式。
[x] Class (继承) string? null 自定义 CSS 类名。
[x] Style (继承) string? null 自定义内联样式。
[x] TabIndex (继承) int? null 元素的 Tab 顺序。

Events (事件)

状态 事件名 类型 描述
[x] OnClick EventCallback<MouseEventArgs> 点击磁贴按钮时触发。若未设置且有 Href，则自动导航。

使用示例

基础用法

<SxTileButton Icon="house" Label="Home" />
<SxTileButton Icon="gear" Label="Settings" />

大小变体

<SxTileButton Icon="star" Label="Small" Size="TileButtonSize.Small" />
<SxTileButton Icon="star" Label="Medium" Size="TileButtonSize.Medium" />
<SxTileButton Icon="star" Label="Large" Size="TileButtonSize.Large" />

语义颜色 + 填充模式

<SxTileButton Icon="heart" Label="Brand" Appearance="TileButtonAppearance.Brand" Variant="TileButtonVariant.Filled" />
<SxTileButton Icon="circle-check" Label="Success" Appearance="TileButtonAppearance.Success" />
<SxTileButton Icon="trash" Label="Danger" Appearance="TileButtonAppearance.Danger" Variant="TileButtonVariant.Outline" />

导航与点击

<SxTileButton Icon="house" Label="首页" Href="/" />
<SxTileButton Icon="bell" Label="@($"Clicks: {count}")" OnClick="@(_ => count++)" />

CSS 架构

使用 CSS 自定义属性实现主题化：

变量 用途
--_size 图标容器尺寸
--_width 整体宽度
--_icon-bg Subtle 模式背景色
--_icon-border 边框色
--_icon-color 图标色
--_icon-bg-solid Filled 模式背景色
--_icon-color-solid Filled 模式图标色
--_icon-hover-bg 悬停背景色

无障碍

  • 使用 role="button" 和 tabindex
  • 支持 Enter / Space 键触发点击
  • 禁用状态设置 aria-disabled="true" 和 tabindex="-1"
  • 建议为纯图标磁贴提供 AriaLabel
在 Playground 中打开 →