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

343 lines
16 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 Form·Row·Col·Flex·Tag 的唯一封装)。
*
* 症状(2026-11 第二轮重写的对象):第一轮只换了原子控件,**字段与排布仍是自绘**——
* `.nex-field` 用 CSS Grid 把标签摆到控件左边,标签列宽靠私有变量 `--label-w`,
* `FormGrid`/`FormRow` 又各自一套 12 等分轨道。结果是资产库抽屉里
* 「标签在左」的三列字段和「标签在上」的长字段混排:列边界参差、
* 只有一个字段的行把输入框缩成一小截、`TEXTAREA_TALL` 把 rows=2 撑到 150px。
* 用户说的「布局还是不对」,病根全在这三个文件级的自绘栅格里。
* 做法:**字段就是 antd Form.Item,标签一律在上(layout="vertical")**。
* 已验证 antd 5.29 会为一个孤立的 `Form.Item layout="vertical"` 生成
* `.ant-form-item-vertical` 的完整样式(不需要外层 `<Form>`),
* 所以全站只有一种字段形态,抽屉、对话框、工具条共用同一条标签基线,
* 「对齐」这件事交还给 antd 的表单栅格,私有变量整层删除。
* <Ctlbar> 含字段的横条 = Dense + Flex(align=end, wrap)
* <FormGrid> 表单作用域(只管标记类名,间距由 Form.Item 自己给)
* <FormRow> 表单里的一行 = Row + Col(断点沿用 antd Grid,见 grid.tsx)
* <ChipBar> 可点筛选行 = Flex + Tag.CheckableTag
* <Pager> 分页条(page_size 唯一的家)
* 高度不写在控件上:紧凑容器只做一件事——`<ConfigProvider componentSize="small">`
* 下发 antd 第二档;自绘的那几处读同一个 `--ant-control-height[-sm]`,两条路同一个数。
*/
import type { CSSProperties, ReactNode } from 'react'
import { ConfigProvider, Checkbox as AntCheckbox, Flex, Form, Pagination, Radio as AntRadio, Row, Tag, Typography } from 'antd'
import { cn } from '../../lib/cn'
import { Button } from './Button'
import { Select } from '../forms/Select'
import { IconClose } from '../icons'
import { colSpans, toCols, type GridStep } from './grid'
/** 分组说明(ChipBar / TagGroup 行首那句「筛选:」):全站只此一种小标签字 */
export const GROUP_LABEL_CLS = 'text-xs text-text-tertiary'
/**
* 紧凑档作用域:工具条 / 分页条 / 卡片动作行里所有 antd 控件降一档
* (antd 自己的第二档 controlHeightSM = 24)。页面不需要、也不准再给单个控件写 size。
*
* 除了下发 ConfigProvider,还落下一个 .nex-dense 类名:自绘的东西(checkable tag 的
* 高度)不在 antd 的组件树里,读不到 componentSize,只能靠这个标记对齐到同一个 token。
*/
export function Dense({ children, className }: { children: ReactNode; className?: string }) {
return (
<ConfigProvider componentSize="small">
<div className={cn('nex-dense', className)}>{children}</div>
</ConfigProvider>
)
}
/**
* 含字段的横条:一行垂直居中(准确说垂直**贴底**——标签在上以后,
* 只有底边对齐才能让不同高度的字段共用一条控件基线),紧凑档,下边距 12。
* 字段在这里不带下边距(`.nex-ctlbar .ant-form-item` 归零,见 app.css)。
*/
export function Ctlbar({ children, className, as = 'div' }: {
children: ReactNode; className?: string; as?: 'div' | 'nav' | 'section'
}) {
return (
<Dense className="contents">
<Flex component={as} wrap align="end" gap={8} className={cn('nex-ctlbar min-w-0', className)}>
{children}
</Flex>
</Dense>
)
}
/**
* 卡片 / 列表行 / 抽屉段落末尾的动作行:横排、换行、间距 8,档位由容器下发(24)。
*
* 【为什么这里曾有两个实现】历史上 `Panel.Actions` 不包 Dense(按钮全 md 32)、
* `CardActions` 包了 Dense(全 sm 24),页面又在 Actions 里补 size="sm",
* 于是素材墙一张卡底下「AI 生成」24、「上传」32、「删除」32。
* 现在只有一个实现:页面既不用、也不准再给行里的单个控件写 size。
*/
export function CardActions({ children, className }: { children: ReactNode; className?: string }) {
return (
<Dense className="contents">
<Flex wrap align="center" gap={8} className={cn('nex-card-actions min-w-0', className)}>
{children}
</Flex>
</Dense>
)
}
/** `CardActions` 的旧名字:同上,只多一个 `mt-2` 的段落间距 */
export function Actions({ children, className }: { children: ReactNode; className?: string }) {
return <CardActions className={cn('mt-2', className)}>{children}</CardActions>
}
/** 需要右靠的一组控件(替代写在控件上的 margin-left:auto) */
export function BarRight({ children, className }: { children: ReactNode; className?: string }) {
return (
<Flex wrap align="center" gap={8} className={cn('ml-auto min-w-0', className)}>{children}</Flex>
)
}
type FieldWidth = 'default' | 'grow' | 'narrow' | 'wide' | 'full'
/**
* 字段宽度:宽度是**字段自己的属性**,列边界由 Row/Col 给(FormRow)。
* 旧的 `nf-w-*` 五条类名靠 `--label-w` 间接生效,改成 inline style 后
* 「这一格多宽」在 DOM 上直接看得见,工具条里的窄字段也不必再猜轨道宽度。
*/
const WIDTHS: Record<FieldWidth, CSSProperties> = {
default: {},
grow: { flex: '1 1 220px', minWidth: 150 },
narrow: { width: 128 },
wide: { width: 240 },
full: { width: '100%' }
}
/**
* 字段 = antd `Form.Item`(标签在上)。
*
* 已验证:孤立使用(外层没有 `<Form>`)时 antd 仍然渲染完整的
* `.ant-form-item-vertical` 结构与样式,所以字段不需要表单外壳也能独立成立;
* `FormGrid` 只提供一个作用域类名,用来给整片字段统一上间距与控件撑满规则。
* `title` 挂在标签文字上:版面里不放整段解释(规范 §2 G2),说明走悬浮。
*/
export function Field({ label, required, children, width = 'default', className, style, hint, title }: {
label?: ReactNode; required?: boolean; children: ReactNode; width?: FieldWidth
className?: string; style?: CSSProperties; hint?: ReactNode; title?: string
}) {
return (
<Form.Item
layout="vertical"
required={required}
label={label === undefined ? undefined : <span title={title}>{label}</span>}
extra={hint}
className={cn('nex-field min-w-0', width !== 'default' && 'nex-field-fill', className)}
style={{ ...WIDTHS[width], ...style }}
>
{children}
</Form.Item>
)
}
/** 必填星号:交还给 antd(Form.Item 的 required 自己画 `*`),这里只留旧名字的占位实现 */
export function Req() {
return <b className="nex-req">*</b>
}
/**
* 长字段(旧「标签在上」专用形态):现在和 Field 完全同一种形态,只是默认撑满整行。
* 保留这个名字是因为 54 处调用写着它,删名字要动 12 个页面而得不到任何东西。
*/
export function FieldBlock({ label, required, children, className, style, title, hint }: {
label?: ReactNode; required?: boolean; children: ReactNode; className?: string
style?: CSSProperties
/** 标签的含义/后果说明:分镜检查器里几乎每个长字段都要一句 */
title?: string; hint?: ReactNode
}) {
return (
<Field label={label} required={required} children={children} width="full"
className={className} style={style} title={title} hint={hint} />
)
}
/**
* 表单作用域:只落下 `.nex-form` 这个标记类。
*
* 旧版本在这里定义 12 等分轨道和 `--label-w`(「标题与控件对齐」的唯一机制)。
* 标签改到控件上方之后,对齐由 antd 表单栅格负责,这两套私有尺子整体退场——
* 列边界从此只有 Row/Col 一个来源(见 grid.tsx),不会再出现两行字段错开 110px。
*/
export function FormGrid({ children, className }: { children: ReactNode; className?: string }) {
return <div className={cn('nex-form min-w-0', className)}>{children}</div>
}
/** 每行 N 个字段时的降列节奏:档位名就是 antd Grid 的断点,站内不再有 900/1100 这种私有宽度 */
const ROW_STEPS: Record<number, GridStep[]> = {
2: [{ at: 'sm', cols: 1 }],
3: [{ at: 'md', cols: 2 }, { at: 'sm', cols: 1 }],
4: [{ at: 'lg', cols: 3 }, { at: 'md', cols: 2 }, { at: 'sm', cols: 1 }],
6: [{ at: 'xl', cols: 4 }, { at: 'lg', cols: 3 }, { at: 'md', cols: 2 }, { at: 'sm', cols: 1 }]
}
/**
* 表单里的一行 = antd Row + Col(cols = 这一行放几个字段)。
*
* 纵向间距不在 gutter 上:Form.Item 自带 24px 下边距,Row 再给纵向 gutter 就是 48。
* `tight` 是给「一行里全是窄字段」的场合(时间线/分镜的批量设置),
* 把下边距压到 8,见 app.css 的 `.nf-tight`。
*/
export function FormRow({ children, cols = 3, className, tight, gap = 16 }: {
children: ReactNode
/** 这一行放几个字段(窄屏按 ROW_STEPS 自动降列) */
cols?: 2 | 3 | 4 | 6
className?: string
tight?: boolean
/** 列间距:默认 16(antd 表单列间),窄屏由 Col 折行接管 */
gap?: number
}) {
return (
<Row gutter={[tight ? 12 : gap, 0]} className={cn('nex-form-row min-w-0', tight && 'nf-tight', className)}>
{toCols(children, colSpans(cols, undefined, ROW_STEPS[cols] || []), 'min-w-0')}
</Row>
)
}
/** 可点的筛选胶囊行(与下方内容强制呼吸 12px);只读回显一律走 TagGroup */
export function ChipBar({ children, label, className, top }: {
children: ReactNode; label?: ReactNode; className?: string; top?: boolean
}) {
return (
<Dense className="contents">
<Flex wrap align="center" gap={6} className={cn('nex-chipbar min-w-0', top && 'mt-3', className)}>
{label && <span className={GROUP_LABEL_CLS}>{label}</span>}
{children}
</Flex>
</Dense>
)
}
/**
* 筛选 / 开关胶囊 = antd `Tag.CheckableTag`(Ant Design 的「标签选择」形态)。
*
* 只有**可点的**东西属于这一族;只读回显(计数、能力、状态)用 Tag / TagGroup。
* 5.29 的 CheckableTag 没有 disabled,所以禁用态自己贴语义:降透明度 + 屏蔽 onChange。
*/
export function Chip({ active, children, onClick, className, title, disabled, as = 'button', href, size = 'md' }: {
active?: boolean; children: ReactNode; onClick?: () => void; className?: string; title?: string
disabled?: boolean; as?: 'button' | 'a' | 'span'; href?: string; size?: 'md' | 'sm'
}) {
const cls = cn('nex-chip', size === 'sm' && 'nex-chip-sm', className)
if (as === 'a') {
return (
<Tag className={cn(cls, 'nex-chip-link')} bordered>
<Typography.Link href={href} title={title} className="!text-inherit">{children}</Typography.Link>
</Tag>
)
}
if (as === 'span' || disabled) {
return (
<Tag className={cn(cls, 'is-off')} bordered {...{ title }}
style={{ opacity: 0.45, cursor: 'not-allowed' }}>{children}</Tag>
)
}
return (
<Tag.CheckableTag checked={!!active} {...{ title }} className={cls}
onChange={() => onClick?.()}>
{children}
</Tag.CheckableTag>
)
}
/** 选中态胶囊 + 移除叉(多选回显);removeTitle 解释叉掉之后会发生什么 */
export function TagChip({ children, onRemove, className, removeTitle }: {
children: ReactNode; onRemove?: () => void; className?: string; removeTitle?: string
}) {
return (
<Tag className={cn('nex-tag-chip', className)} bordered closable={!!onRemove}
closeIcon={onRemove ? <IconClose /> : undefined}
onClose={(e) => { e.preventDefault(); onRemove?.() }}>
<span className="min-w-0 wrap-anywhere">{children}</span>
{removeTitle && <span className="sr-only">{removeTitle}</span>}
</Tag>
)
}
/**
* 分页条(规范 §5):page_size 唯一的家,筛选栏里不再出现「每页」。
* 档位由页面给(卡片墙要的是 24/60/120/全部;0 表示不分页)。
*/
const DEFAULT_SIZES = [12, 20, 24, 30, 48, 60, 120]
export function Pager({ page, pages, total, pageSize, onPageSize, onPage, extra, sizes = DEFAULT_SIZES }: {
page: number; pages: number; total?: number; pageSize?: number
onPageSize?: (size: number) => void; onPage: (page: number) => void; extra?: ReactNode
sizes?: number[]
}) {
const last = Math.max(1, pages)
const opts = sizes.map((n) => ({ value: n, label: String(n || '全部') }))
return (
<Dense>
<Flex wrap align="center" gap={12}
className={cn('nex-pager min-w-0', (total === undefined || total === 0) && !extra && 'hidden')}>
<Typography.Text type="secondary" className="!text-xs">{page} / {last}{total !== undefined ? ` · 共 ${total} 条` : ''}</Typography.Text>
<Pagination current={page} total={Math.max(last * (pageSize || 1), total || 0)} pageSize={pageSize || 12}
showSizeChanger={false} onChange={(p) => onPage(p)} size="small" simple />
{onPageSize && (
<Flex align="center" gap={6}>
<Typography.Text type="secondary" className="!text-xs">每页</Typography.Text>
<Select size="sm" ariaLabel="每页条数" searchThreshold={0} placeholder="全部"
value={pageSize} onChange={(v: any) => onPageSize(Number(v))}
className="w-[72px]" options={opts} />
</Flex>
)}
{extra}
</Flex>
</Dense>
)
}
/** 复选(勾选框 + 文案整块可点):本体是 antd Checkbox,尺寸走 token */
export function Check({ checked, onChange, children, disabled, className, title }: {
checked: boolean; onChange: (next: boolean) => void; children: ReactNode; disabled?: boolean
className?: string; title?: string
}) {
return (
<AntCheckbox checked={checked} disabled={disabled} title={title} className={cn('nex-check', className)}
onChange={(e) => onChange(e.target.checked)}>
{children}
</AntCheckbox>
)
}
/** 单选组(互斥选项):antd Radio.Group;分段切换请用 Segmented */
export function RadioGroup({ value, onChange, options, className, disabled }: {
value: any; onChange: (next: any) => void; options: { value: any; label: ReactNode; disabled?: boolean }[]
className?: string; disabled?: boolean
}) {
return (
<Form.Item layout="vertical" className={cn('nex-field min-w-0 !mb-0', className)}>
<AntRadio.Group value={value} disabled={disabled}
onChange={(e) => onChange(e.target.value)}
options={options.map((o) => ({ label: o.label, value: o.value, disabled: o.disabled }))} />
</Form.Item>
)
}
/**
* 文件选择:整块按钮就是热区,点哪里都开文件对话框。
* 选完把 input 清空:否则连着两次选同一个文件 value 没变,onChange 不再触发
* (分镜导入要反复试同一份脚本)。
*/
export function FilePick({ label, icon, accept, multiple, onFiles, className, title, disabled }: {
label: ReactNode; accept?: string; multiple?: boolean; onFiles: (files: File[]) => void; className?: string
/** 悬浮说明「选出来的文件会落到哪里」:一页里上传点越多越需要这句话 */
title?: string; disabled?: boolean
/** 图标走 antd Button 的 icon 槽,不写进 label —— 否则间距由 label 里的空格决定 */
icon?: ReactNode
}) {
return (
<Button className={className} title={title} disabled={disabled} icon={icon}>
<span className="contents">{label}</span>
<input type="file" className="nex-file-input" accept={accept} multiple={multiple} title={undefined}
onChange={(e) => {
const files = Array.from(e.currentTarget.files || [])
e.currentTarget.value = ''
onFiles(files)
}} />
</Button>
)
}