nex_animation/frontend/src/components/ui/Panel.tsx

329 lines
15 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

/**
* 卡片体系:Ant Design 5 Card / Statistic / Row·Col / Alert / Empty / Progress 的唯一封装。
*
* 症状(2026-11 第二轮重写的对象):第一轮只把**原子控件**换成了 antd,
* 「有边框的内容块」仍然是自绘 <section> + Tailwind 类,标题行、指标卡、
* 栅格、提示条、空态各自一把尺子。于是页面看着像 antd 控件贴在旧版式上:
* 卡头没有分隔线、指标卡数字与 antd 的 Statistic 差 6px、栅格按私有断点降列。
* 做法:**布局也交给 antd**。Panel=Card(卡头用 Card 自己的 title/extra)、
* Stat=Card+Statistic、Grid/StatGrid=Row+Col(断点用 antd Grid 的 xs…xxl)、
* Notice=Alert、Empty=Empty、ProgressBar=Progress、Divider=Divider。
* 页面继续写 <Panel><PanelHead …/>正文</Panel>:Panel 会把作为第一个子节点的
* PanelHead **吞进 Card 的 title/extra**,所以 52 处调用一行不用改,
* 卡头却已经是真正的 antd 卡头(分隔线、15px 标题、右端 extra)。
* 为什么把吞并做在 Panel 里而不是让页面改写:<PanelHead> 这个形状已经写了 42 遍,
* 改名成 Card 的 title/extra 属性要动 12 个页面 42 处,而它表达的语义
* (这一块是什么 + 右端动作)完全一致;语义不变、实现换掉,就是这一轮的全部工作。
*/
import { Children, isValidElement, type CSSProperties, type ReactNode } from 'react'
import {
Alert, Card, Divider as AntDivider, Empty as AntEmpty, Flex,
Progress, Row, Spin, Statistic, Typography
} from 'antd'
import { cn } from '../../lib/cn'
import { IconExternal, IconLoading } from '../icons'
import { colSpans, toCols, type GridCollapse, type GridStep, type StatStep } from './grid'
/** Panel 认得出的 PanelHead 形状(Panel 用它拼 Card 的 title/extra) */
type HeadProps = { title?: ReactNode; sub?: ReactNode; right?: ReactNode }
/**
* 面板 = antd Card。
*
* pad={false} 给「正文本身就是一张表 / 一整个滚动区」的卡:antd 的 body 内边距
* 会让表格的描边离卡边 24px,看起来像表格外又套了一圈盒子。
*/
export function Panel({ children, className, style, pad = true, title, sub, extra }: {
children?: ReactNode; className?: string; style?: CSSProperties; pad?: boolean
/** 不写 children 里的 PanelHead 时,也可以直接用卡头属性(与 antd Card 同名) */
title?: ReactNode; sub?: ReactNode; extra?: ReactNode
}) {
const head: HeadProps = {}
const body: ReactNode[] = []
let taken = false
Children.forEach(children, (child) => {
if (!taken && isValidElement(child) && child.type === PanelHead) {
const p = (child.props || {}) as HeadProps
head.title = p.title; head.sub = p.sub; head.right = p.right
taken = true
return
}
body.push(child)
})
const cardTitle = title ?? head.title
const cardSub = sub ?? head.sub
const cardExtra = extra ?? head.right
const headNode = (cardTitle || cardSub)
? (
<Flex vertical gap={2} className="min-w-0">
{cardTitle && <span className="min-w-0">{cardTitle}</span>}
{cardSub && (
<Typography.Text type="secondary" className="!text-xs font-normal leading-snug">{cardSub}</Typography.Text>
)}
</Flex>
)
: undefined
return (
<Card className={cn('nex-panel', className)} style={style} title={headNode} extra={cardExtra}
styles={pad ? undefined : { body: { padding: 0 } }}>
{body}
</Card>
)
}
/**
* 面板头(标题 + 副标题 + 右端动作)。
*
* 在 <Panel> 里它不渲染任何东西——Panel 把这三个属性搬进 Card 的 title/extra。
* 单独出现(页面正文最上方那种「不属于任何卡片的小标题」)时才是下面这一行。
*
* 旧站 25 处卡头都是 <small class="eyebrow"> + <h2> 的「英文眉标 + 中文标题」双层,
* 眉标既不翻译也不承载信息,已整层删除(UI规范 §1)。
*/
export function PanelHead({ title, sub, right, className }: HeadProps & { className?: string }) {
return (
<Flex justify="space-between" align="center" gap={12} wrap className={cn('mb-4 min-w-0 [&>*]:min-w-0', className)}>
<Flex vertical gap={2} className="min-w-0">
{title && <Typography.Title level={5} className="!mb-0">{title}</Typography.Title>}
{sub && <Typography.Text type="secondary" className="!text-xs">{sub}</Typography.Text>}
</Flex>
{right && <Flex gap={8} wrap align="center" className="min-w-0">{right}</Flex>}
</Flex>
)
}
/**
* 小标题 + 右端动作(.small-label / .sect-act:增删按钮一律贴在标题行右端)。
*
* title 给整行挂悬浮解释:版面里不放整段说明文字(G2),窄屏也不会因为一句说明
* 把动作按钮挤到下一行。
*/
export function SectionTitle({ children, action, className, title }: {
children: ReactNode; action?: ReactNode; className?: string; title?: string
}) {
return (
<Flex align="center" gap={8} wrap title={title}
className={cn('mb-2 mt-4 min-w-0 text-xs font-bold tracking-wide text-text-quaternary', className)}>
<span>{children}</span>
{action && <span className="ml-auto inline-flex items-center gap-2">{action}</span>}
</Flex>
)
}
/**
* 指标:全站「数字 + 标题」只有这一个写法 = antd Statistic(卡档再套一层 Card)。
*
* 病灶:同一个统计数字长出过三套皮肤——概览/仪表盘用自绘卡、资产库自己写了
* 一张带渐变的 MetricCard、分镜顶栏又写了一套更小的 Metric。
* 做法:数字与标题的度量交还 antd(.ant-statistic 的 title 14 / content 24),
* 档位是**参数**不是第二套类名——card(默认)=页面顶部那排统计卡;
* inline=sticky 顶栏 / 工具条里的一列小数字。
* 给了 onClick 就整张卡可点(antd Card hoverable,键盘点得动 AS-7),
* active 点亮描边 = 「当前这一屏数字就是这个筛选命中的那批」。
* 数字 tabular-nums 由 antd 自己负责(.ant-statistic-content 已开)。
*/
export type StatTone = 'lead' | 'ok' | 'warn' | 'bad'
const STAT_TONE: Record<StatTone, string> = {
lead: 'var(--ant-color-primary)', ok: 'var(--ant-color-success)',
warn: 'var(--ant-color-warning)', bad: 'var(--ant-color-error)'
}
export function Stat({ label, value, hint, className, style, variant = 'card', tone, active, onClick, title, valueSize = 'num' }: {
label: ReactNode; value: ReactNode; hint?: ReactNode; className?: string; style?: CSSProperties
/** card=页面统计卡;inline=顶栏里的一列小数字 */
variant?: 'card' | 'inline'
tone?: StatTone
/** 命中当前筛选:点亮描边 + 标题 */
active?: boolean
/** 整张卡是筛选入口 */
onClick?: () => void
title?: string
/** `num`(默认)=纯数字;`title`=放的是一段名字(模型控制台的「当前默认大模型」) */
valueSize?: 'num' | 'title'
}) {
const color = tone ? STAT_TONE[tone] : undefined
const labelNode = <span title={title}>{label}</span>
/* value 里的 <i> 是「次要的一半」(9<i>/47</i> 里的分母、/ 未设置),样式只在这里定义一次 */
const valueStyle: CSSProperties = {
color,
fontSize: variant === 'inline' ? 18 : valueSize === 'num' ? 24 : 15,
fontWeight: 600,
...(valueSize === 'title' ? { whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' } : {})
}
const stat = (
<Statistic className="nex-stat-value min-w-0 [&_i]:not-italic [&_i]:font-medium [&_i]:ml-[3px] [&_i]:text-text-quaternary [&_i]:text-base"
title={labelNode} value={value as never} valueStyle={valueStyle} />
)
if (variant === 'inline') {
return (
<Flex vertical gap={0} className={cn('min-w-0', className)} style={style} title={title}>
{stat}
{hint && <Typography.Text type="secondary" className="!text-xs">{hint}</Typography.Text>}
</Flex>
)
}
return (
<Card hoverable={!!onClick} onClick={onClick} className={cn('nex-stat min-w-0', onClick && 'nex-stat-click', className)}
/* active 是「这张卡被选中」,选择态用主色描边;success 只留给数字本身表示 ok(STAT_TONE.ok)。 */
style={active ? { ...style, borderColor: 'var(--ant-color-primary-border)' } : style}
styles={{ body: { padding: 20 } }}>
{stat}
{hint && (
<Typography.Text type="secondary" className="!mt-2 block !text-xs leading-snug">{hint}</Typography.Text>
)}
</Card>
)
}
/** 顶栏 / 工具条里的一排小指标(分镜、调度那种 sticky 条);卡片栅格请用 StatGrid */
export function StatRow({ children, className }: { children: ReactNode; className?: string }) {
return <Flex wrap align="end" gap={24} className={cn('min-w-0', className)}>{children}</Flex>
}
/* 栅格换算(列数 + 降列档位 → antd Col 断点)与 Page/Controls 共用一份:见 grid.tsx */
/**
* 通用栅格(旧 .grid / .grid2 / .grid3 / .grid4)= antd Row + Col。
*
* 列间距走 antd 的 gutter(横向必须是 8 的倍数才和站内间距成一套),
* 纵向间距同样由 gutter 给,页面不再自己写 mb-*。
*/
export function Grid({ children, cols = 4, gap = 12, min, oneAt, steps, className }: {
children?: ReactNode; cols?: number; gap?: number; oneAt?: GridCollapse
steps?: GridStep[]; className?: string
/** 兼容旧参数:列最小宽。栅格改成 24 等分后由 span 决定列宽,这个值只作窄屏兜底 */
min?: number
}) {
void min
const spans = colSpans(cols, oneAt, steps)
return (
<Row gutter={[gap, gap]} className={cn('min-w-0', className)}>
{toCols(children, spans, 'min-w-0')}
</Row>
)
}
/**
* 指标卡栅格:列数与降列节奏都由容器声明,页面不写 @media。
* 默认 4 列 → ≤992 两列 → ≤576 一列(antd 断点,不再用私有的 900/560)。
*/
export function StatGrid({ children, cols = 4, steps, className, gap = 12 }: {
children: ReactNode; cols?: number; steps?: StatStep[]; className?: string; gap?: number
}) {
const merged: StatStep[] = steps || [{ at: 'lg', cols: 2 }, { at: 'sm', cols: 1 }]
return <Grid cols={cols} steps={merged} gap={gap} className={className}>{children}</Grid>
}
/** 进度条:antd Progress(站内只有这一条;bad=异常态用 antd 的 exception 色) */
export function ProgressBar({ value, bad, className }: { value: number; bad?: boolean; className?: string }) {
const pct = Math.max(0, Math.min(100, Number(value) || 0))
return (
<Progress percent={pct} showInfo={false} status={bad ? 'exception' : 'normal'}
size="small" className={cn('nex-progress min-w-[60px]', className)} />
)
}
/** 分隔线:antd Divider */
export function Divider({ className, dashed }: { className?: string; dashed?: boolean }) {
return <AntDivider className={className} dashed={dashed} />
}
/** 空态:antd Empty(简单图,站内不放插画——卡片里那块地方给不起) */
export function Empty({ children = '暂无数据', className }: { children?: ReactNode; className?: string }) {
return <AntEmpty className={cn('my-2', className)} image={AntEmpty.PRESENTED_IMAGE_SIMPLE} description={children} />
}
/** 读取中:antd Spin */
export function Loading({ children = '读取中…', className }: { children?: ReactNode; className?: string }) {
return (
<Flex vertical align="center" gap={8} className={cn('p-6', className)}>
<Spin size="small" />
<Typography.Text type="secondary" className="!text-xs">{children}</Typography.Text>
</Flex>
)
}
/** 行内小转圈(按钮、状态条里那颗) */
export function Spinner({ className }: { className?: string }) {
return <IconLoading spin aria-hidden className={cn('align-[-1px] text-xs', className)} />
}
/**
* 提示条:antd Alert。成功/普通信息用 info(站内 colorInfo=主色),错误用 error。
* 只放一句人话,长说明收进抽屉(G2)。
*/
export function Notice({ children, danger, className, onClose }: {
children: ReactNode; danger?: boolean; className?: string; onClose?: () => void
}) {
if (!children) return null
return (
<Alert className={cn('mb-4', className)} type={danger ? 'error' : 'info'} showIcon
message={children} closable={!!onClose} onClose={onClose} />
)
}
/** 数据回显(.val)与条件告警(.linehint):规范 §7 G2 —— 版面不放成段解释文字 */
export function Value({ children, muted, className }: { children: ReactNode; muted?: boolean; className?: string }) {
return (
<Typography.Text
className={cn('!text-xs leading-relaxed wrap-anywhere', muted ? '!text-text-quaternary' : '!text-text-tertiary', className)}
type={muted ? undefined : 'secondary'}>{children}</Typography.Text>
)
}
export function LineHint({ children, className }: { children: ReactNode; className?: string }) {
return (
<Flex align="baseline" gap={6} wrap className={cn('mt-2 text-xs leading-normal text-warning', className)}>
{children}
</Flex>
)
}
/** 等宽小字(路径 / id / 枚举码) */
export function Mono({ children, className, title }: { children: ReactNode; className?: string; title?: string }) {
return <Typography.Text className={cn('font-mono !text-xs', className)} title={title} copyable={false}>{children}</Typography.Text>
}
/** 文字链(.link):导航用 <Link>,这里只给「打开外部资源 / 下载」 */
export function ExtLink({ href, children, className, download }: {
href: string; children: ReactNode; className?: string; download?: boolean | string
}) {
return (
<Typography.Link href={href} download={download} target="_blank" rel="noreferrer"
className={cn('!inline-flex !items-center gap-1 !text-xs', className)}>
{children}<IconExternal className="text-xs" />
</Typography.Link>
)
}
/**
* 卡片行(.cardrow):标题 + 说明 + 右侧动作,列表里重复项的统一骨架。
*
* 骨架交给 antd Flex + Typography,分隔线用 colorSplit;
* 只留 CARD_ROW 一个类名常量给「要自己排正文」的资产管理卡(同一条分隔线、同一套字号)。
*/
export const CARD_ROW = 'flex min-w-0 items-start justify-between gap-3 border-b border-fill-secondary py-3 last:border-b-0 '
+ '[&_h4]:m-0 [&_h4]:mb-1 [&_h4]:text-sm [&_h4]:font-semibold [&_h4]:text-text '
+ '[&_p]:mx-0 [&_p]:my-1 [&_p]:text-xs [&_p]:leading-normal [&_p]:text-text-tertiary'
export function CardRow({ title, children, right, className, tone = 'border' }: {
title?: ReactNode; children?: ReactNode; right?: ReactNode; className?: string; tone?: 'border' | 'plain'
}) {
return (
<div className={cn(CARD_ROW, tone === 'plain' && 'border-b-0', className)}>
<div className="min-w-0 flex-1">
{title && <h4>{title}</h4>}
{children && <div>{children}</div>}
</div>
{right && <Flex gap={8} align="center" wrap className="min-w-0 shrink-0">{right}</Flex>}
</div>
)
}
/** 元信息一行(.meta) */
export function Meta({ children, className }: { children: ReactNode; className?: string }) {
return <Flex gap={8} align="center" wrap className={cn('min-w-0 text-xs text-text-tertiary', className)}>{children}</Flex>
}
/** 行内动作组(.actions):唯一实现在 Controls.CardActions,这里只转发旧名字 */
export { Actions } from './Controls'