PatternsSemantic
GraphNode
@mox-hub/patterns 模式 · Semantic · canonical
graph-node@mox-hub/patternsSemanticcanonicalsrc/components/graph-node.tsx变体轴
statedefaultfinal
densitydefaultcompact
变体演示graph-node
需求澄清进行中
把原始需求拆成可执行任务
claude-sonnet-5-5
方案评审待评审
已选中:ring 表达画布焦点
2 个阻塞项
交付物定稿定稿
成功色描边 + 浅底;文字信号由徽标补齐
final · compact
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title* | ReactNode | — | — |
| icon* | ReactNode | — | — |
| badge* | ReactNode | — | — |
| description* | ReactNode | — | — |
| actions* | ReactNode | — | — |
| footer* | ReactNode | — | — |
| selected* | boolean | false | — |
| state* | GraphNodeState | 'default' | — |
| density* | GraphNodeDensity | 'default' | — |
| disabled* | boolean | false | — |
| className* | string | — | — |
| children* | ReactNode | — | — |
源码
import type { ComponentProps, ReactNode } from 'react';
import { cn } from '@mox-hub/ui';
import { Card } from '@mox-hub/ui/components/card';
export type GraphNodeState = 'default' | 'final';
export type GraphNodeDensity = 'default' | 'compact';
export interface GraphNodeProps
extends Omit<ComponentProps<'div'>, 'title' | 'children'> {
/** 节点标题(必填,单行截断) */
title: ReactNode;
/** 标题行前导图标(已组装好的节点,如 lucide 图标或类型图标底框) */
icon?: ReactNode;
/** 标题右侧徽标槽(状态/版本等,可放 Badge / Chip) */
badge?: ReactNode;
/** 描述行,最多两行截断 */
description?: ReactNode;
/** 右上动作区(复制/禁用/删除等高频操作) */
actions?: ReactNode;
/** 底部元信息槽(配置摘要、模型名等) */
footer?: ReactNode;
/** 选中态;React Flow 自定义节点可直接透传 selected */
selected?: boolean;
/** 语义态:default 普通 / final 定稿(成功色描边与浅底) */
state?: GraphNodeState;
/** 密度:default 256px / compact 224px,只影响节点排版,不影响画布缩放 */
density?: GraphNodeDensity;
/** 禁用态:降透明度并禁用指针交互 */
disabled?: boolean;
/** 节点主体附加内容;根节点为 relative,可承载 React Flow Handle / 端口列 */
children?: ReactNode;
}
/**
* GraphNode —— 画布节点卡片骨架(DF-15,patterns 层,不绑定 React Flow)。
*
* 把任务图/拓扑里反复手写的节点卡收敛为同一形态:标题行(图标 + 标题 + 徽标 +
* 动作)+ 描述 + 底部元信息,统一 hover / selected / final 三态与 density / disabled
* 样式。组件只负责「节点长什么样」,画布机制(拖拽、连线、键盘移动、Handle 位置)
* 仍由消费方或 React Flow 适配层承担;因此本件**不 import 任何画布依赖**。
*
* ## 状态约定
* - hover:纯 CSS,禁用态自动失效。
* - selected:`selected` prop(React Flow 的 `selected` 直接透传),用 ring 表达,
* 不替代画布层的选中语义。
* - final:`state="final"` 用成功色描边 + 浅底表达定稿;**颜色不是唯一信号**,
* 调用方应在 `badge` 或 `footer` 中同时给出文字/图标。
* - disabled:降透明 + `pointer-events-none`,不改变布局。
*
* ## React Flow 接入
* - 在自定义节点组件里渲染 `<GraphNode selected={selected} …>`;
* - 内部可交互元素(按钮/输入)加 `nodrag` 类,避免触发画布拖拽;
* - Handle 作为 `children` 传入,自行用绝对定位贴到节点左右两侧。
*/
export function GraphNode({
title,
icon,
badge,
description,
actions,
footer,
selected = false,
state = 'default',
density = 'default',
disabled = false,
className,
children,
...props
}: GraphNodeProps) {
return (
<Card
data-slot="graph-node"
data-selected={selected || undefined}
data-state={state}
data-density={density}
data-disabled={disabled || undefined}
variant="outline"
size="sm"
className={cn(
'group/graph-node relative w-64 gap-2 overflow-visible rounded-lg border-border bg-card text-sm transition-[background-color,border-color,box-shadow] duration-normal',
// hover:仅提示可交互,不改变选中/定稿语义
'hover:border-ring/50 hover:bg-muted/30',
// selected:ring 是主信号,描边同步提亮
'data-[selected=true]:border-ring data-[selected=true]:ring-2 data-[selected=true]:ring-ring/40',
// final:成功色描边 + 浅底;文字/图标由 badge/footer 补齐
'data-[state=final]:border-accent-green/40 data-[state=final]:bg-accent-green-light/30',
// disabled:不响应指针,视觉降级
'data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50',
// 紧凑档:更窄的节点宽度与行距
'data-[density=compact]:w-56 data-[density=compact]:gap-1.5',
className
)}
{...props}
>
<div className="flex items-start gap-2 px-(--card-spacing)">
{icon ? (
<span className="flex size-control-2xs shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground group-data-[density=compact]/graph-node:size-control-xs">
{icon}
</span>
) : null}
<div className="min-w-0 flex-1">
<div className="flex min-w-0 items-center gap-1.5">
<span className="truncate font-medium text-foreground">{title}</span>
{badge ? <span className="shrink-0">{badge}</span> : null}
</div>
{description !== undefined && description !== null ? (
<p className="line-clamp-2 text-xs text-muted-foreground">{description}</p>
) : null}
</div>
{actions ? (
<div className="flex shrink-0 items-center gap-0.5">{actions}</div>
) : null}
</div>
{footer !== undefined && footer !== null ? (
<div className="border-t border-border/60 px-(--card-spacing) pt-2 text-xs text-muted-foreground">
{footer}
</div>
) : null}
{children}
</Card>
);
}
可访问性与 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。
用法说明
画布节点卡片骨架(不绑定 React Flow):标题/图标/徽标/描述/动作/页脚槽,统一 hover/selected/final 三态与 density/disabled 样式。React Flow 自定义节点直接透传 selected;交互元素加 nodrag,Handle 作为 children 绝对定位。
React Flow 接入
GraphNode 不依赖 React Flow,也不注册节点类型;在自定义节点组件里把它当普通卡片渲染即可。
画布机制仍由 React Flow 负责:
selected直接透传 React Flow 的节点选中态;- 节点内按钮/输入加
nodrag,避免点击时触发画布拖拽; Handle作为children传入,自行用绝对定位贴到左右两侧;- 拖拽、连线、键盘移动与
aria语义保持在 React Flow 适配层。
import {
Handle,
Position,
type Node,
type NodeProps,
} from '@xyflow/react'
import { Badge } from '@mox-hub/ui'
import { GraphNode } from '@mox-hub/patterns/components/graph-node'
type TaskNodeData = {
title: string
description?: string
status: string
final?: boolean
}
type TaskNode = Node<TaskNodeData, 'task'>
function TaskNode({ data, selected }: NodeProps<TaskNode>) {
return (
<GraphNode
selected={selected}
state={data.final ? 'final' : 'default'}
title={data.title}
description={data.description}
badge={<Badge variant="secondary">{data.status}</Badge>}
actions={
<button type="button" className="nodrag" aria-label="更多操作">
⋯
</button>
}
footer="claude-sonnet-5-5"
>
<Handle type="target" position={Position.Left} />
<Handle type="source" position={Position.Right} />
</GraphNode>
)
}如需禁用某个节点,传 disabled;紧凑画布用 density="compact"(224px),常规节点为 256px。
state="final" 只负责描边与浅底,定稿文字或图标请同时放进 badge / footer,不要只靠颜色传达。