Ordo UI
组件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*booleanfalse—
reorderLabel*string——
singleLine*booleanfalse—
titleClassName*string——
className*string——

源码

packages/ui/src/components/definition-row.tsx
/**
 * 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 /translator props,其次用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>