组件Semantic
DefinitionRow
@mox-hub/ui 组件 · Semantic · canonical
definition-row@mox-hub/uiSemanticcanonicalsrc/components/definition-row.tsx变体演示definition-row
3
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| id* | string | — | — |
| leading* | ReactNode | — | — |
| title* | ReactNode | — | — |
| description* | ReactNode | — | — |
| trailing* | ReactNode | — | — |
| onClick* | () => void | — | — |
| sortable* | boolean | false | — |
| reorderLabel* | string | — | — |
| singleLine* | boolean | false | — |
| titleClassName* | string | — | — |
| className* | string | — | — |
源码
/**
* DefinitionRow - 设置·定义类管理页通用行骨架(标签 / 工单类型 / 角色 / 状态…)
*
* 统一行形态(2026-10-01 设置管理面统一批):拖拽手柄(hover 显隐)+ 前导底框图标 +
* 双行文本(标题行含徽标 / 描述行)+ 尾部槽(计数/开关/操作)。
* sortable 形态内置 SortableItem/Handle(须置于 <Sortable> 内);非 sortable 形态
* (无 order 能力的实体,如角色)渲染为同款静态行。**默认静态行**:只有需要排序的
* 实体显式传 `sortable`,只读信息不再被迫逐行传 `sortable={false}`(DF-10)。
* 展示型语义组件:内容全部由消费方注入。
*/
import { SortableItem, SortableItemHandle } from './sortable';
import { RawButton } from './raw/raw-button';
import { cn } from '../lib/utils';
import { useMessages } from '../i18n';
export interface DefinitionRowProps {
/** SortableItem value(= 实体 id) */
id: string;
/** 前导底框图标(StatusIconFrame / IssueTypeIcon 等已组装好的节点) */
leading: React.ReactNode;
/** 标题行:名称 + 徽标(消费方拼接) */
title: React.ReactNode;
/** 第二行:描述 / key 等;不传则单行 */
description?: React.ReactNode;
/** 尾部槽:计数 / 开关 / 菜单 / 操作按钮组 */
trailing?: React.ReactNode;
/** 行主体点击(leading + 文本区承载) */
onClick?: () => void;
/** 拖拽形态(须置于 <Sortable> 内且实体有 order 能力);默认 false = 静态行、无手柄,需要排序时显式传 true */
sortable?: boolean;
/** 拖拽手柄 aria-label(缺省「拖拽排序」);i18n 去耦后由消费方注入(2026-11-08) */
reorderLabel?: string;
/** 单行模式(表格型列表):leading + 标题 + 描述并排一行,描述占满余宽;默认双行堆叠 */
singleLine?: boolean;
/** 单行模式标题列宽类(须与列头同款类保证列对齐;默认 w-40) */
titleClassName?: string;
className?: string;
}
const ROW_CLASS =
'group flex items-center gap-2.5 bg-card px-1.5 py-2 motion-shift';
export function DefinitionRow({
id,
leading,
title,
description,
trailing,
onClick,
sortable = false,
reorderLabel,
singleLine = false,
titleClassName,
className,
}: DefinitionRowProps) {
const M = useMessages();
const reorder = reorderLabel ?? M.definitionRow.reorder;
const main = singleLine ? (
<RawButton
onClick={onClick}
className="flex min-w-0 flex-1 items-center gap-3 py-0.5 text-start"
>
{leading}
<span
className={cn(
'shrink-0 truncate text-sm font-medium text-foreground',
titleClassName ?? 'w-40',
)}
>
{title}
</span>
{description !== undefined && description !== null ? (
<span className="min-w-0 flex-1 truncate text-sm text-content-text-secondary">
{description}
</span>
) : null}
</RawButton>
) : (
<RawButton
onClick={onClick}
className="flex min-w-0 flex-1 items-center gap-3 py-0.5 text-start"
>
{leading}
<span className="min-w-0">
<span className="flex items-center gap-2">{title}</span>
{description !== undefined && description !== null ? (
<span className="block truncate text-xs text-content-text-muted">{description}</span>
) : null}
</span>
</RawButton>
);
const body = (
<>
{main}
{trailing ?? null}
</>
);
if (!sortable) {
return (
<div data-slot="definition-row" className={cn(ROW_CLASS, className)}>
{body}
</div>
);
}
return (
<SortableItem value={id} className={cn(ROW_CLASS, className)}>
<SortableItemHandle
render={<RawButton aria-label={reorder} />}
className="touch-none text-content-text-muted opacity-0 transition-opacity duration-fast hover:text-content-text-secondary group-hover:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100 pointer-coarse:size-11"
>
<svg viewBox="0 0 10 16" className="size-3.5 fill-current" aria-hidden>
<circle cx="3" cy="3" r="1.4" />
<circle cx="7" cy="3" r="1.4" />
<circle cx="3" cy="8" r="1.4" />
<circle cx="7" cy="8" r="1.4" />
<circle cx="3" cy="13" r="1.4" />
<circle cx="7" cy="13" r="1.4" />
</svg>
</SortableItemHandle>
{body}
</SortableItem>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
定义行(键值对),适合详情页字段列表;默认静态行不渲染拖拽手柄(sortable 默认 false),需要排序的实体显式传 sortable。长文本换行由内容区控制。
排序默认值(DF-10)
sortable 默认 false:只读信息行直接渲染静态行,不再要求 Sortable 上下文,也不会出现拖拽手柄。
只有真正需要用户调整顺序的实体(如自定义状态列表)才显式传 sortable,并置于 <Sortable> 内:
<Sortable>
<DefinitionRow id="status-1" sortable title="进行中" leading={<StatusIcon />} />
</Sortable>