cn hx components Label

HxLabel

带样式的文本标签，支持悬停/激活状态和可选的模型绑定。渲染 <span>。

<HxLabel text="用户名" />
<HxLabel text="~Common.Price" valueUseI18N />

// 模型绑定，带值格式化
<HxLabel $model={form} $field="price" format="nf2" />

// 交互状态
<HxLabel text="点击我" clickable hoverable onClick={handleClick} />
<HxLabel text="已选中" active />

Props

Prop	类型	默认值	说明
text	ReactNode	—	标签内容。以 ~ 开头为 i18n 键名；需要原样显示开头的 ~ 时写作 \~。同时指定 $model 和 $field 时被忽略
color	HxColor	—	文字颜色
opaque	boolean	—	显示不透明背景
clickable	boolean	—	cursor: pointer 样式
hoverable	boolean	—	启用悬停视觉效果
hovered	boolean	—	强制悬停状态（受控）
active	boolean	—	强制激活/按下状态（受控）
borderRadius	HxBorderRadius	—	圆角
valueUseI18N	boolean	false	对 $model / $field 读到的值应用 i18n；静态 text 由 ~ 前缀决定
format	HxFormats	—	模型值的格式转换器（数字、日期、日期时间）
paddingX	HxLabelPaddingX	—	水平内边距（HxPadding 或 'text-indent'）
paddingY	HxPadding	—	垂直内边距
indent	boolean	—	内容两侧按文本缩进留白，等价于 paddingX="text-indent"
singleLineEllipsis （data attr）	—	—	非 prop；输入类组件在纯文本 label 上设置 data-hx-label-single-line-ellipsis，使其单行显示并在溢出时截断为省略号（子元素内容保持默认 flex 布局）
$model	HxObject<T>	—	响应式模型
$field	ModelPath<T> | HxDataPath	—	绑定时显示模型字段值而非 text

原生 DOM 事件

所有 <span> 事件透传。启用 clickable 或 hoverable 时有用：onClick、onMouseEnter、onMouseLeave。其他情况下 Label 通常是纯展示元素，不需要事件监听。

全局配置

设置所有 HxLabel 的默认值。默认值在渲染时读取，因此配置全局立即生效；label 上显式传入的 prop 优先级更高。

import { configHxLabel } from '@hx/components';

configHxLabel({
  valueUseI18N: true,       // 默认：false
  paddingX: 'md',           // 默认：none，仅可取 HxPadding（'text-indent' 是组件 prop 专属值）
  paddingY: 'xs',           // 默认：none，可取 HxPadding
});