文档把选型决策、R7 与探针口径写死:UI规范新增 §0.6「标准控件组 = Radix primitives + 自有皮肤」,报告补第二十五章。
UI规范.md:§0.6 一次讲清四层分工(尺子 tokens.css / 行为 primitives / 皮肤 layers.ts / 语义 ui+forms)、 否掉 antd-MUI-Arco 的三条量化理由(两套尺子、preflight 抢深浅主题、深色皮肤要覆盖八成)、 以及规矩(页面与 ui/ 不许直接 import @radix-ui/*、新浮层必须先在 primitives 落原语再登记、 层级只用一套、Esc 先看 floatingLayerOpen()、Content 上写 fixed 会让 Radix 量到 0 高)。 另立「两个咬过人的陷阱」:① [&>*]:min-w-0 与 min-w-(--label-w) 特指度平票会无声清零标签下限; ② Playwright 的 locator.click() 先做 DOM.scrollIntoViewIfNeeded 把目标居中, 「开抽屉把页面顶回顶部」就是这么造出来的假 bug——量滚动位移前基线必须在 scroll_into_view_if_needed() 之后取。 硬规则从六条升到七条(R6 从「不用裸 select」扩成「控件不用浏览器原生外观」,新增 R7 字段形态唯一); §0.5 对照表补 Checkbox/Slider/Popup/Menu/Dialog 与 floatingLayerOpen 六行;§3 的 hint 栅格写法 从 grid-cols-[auto_minmax(0,1fr)] 更新成 minmax(var(--label-w),max-content)_minmax(0,1fr); §8 登记 align4(五判据各 0 组)与 ctl4(31 项)为新口径。 工程规范.md:§1.1 依赖链插入 components/primitives/ 这一层(附「一个用户就进,不等第二个用户」的例外), 扩展点加「加一类控件行为」一行,§4 补依赖卫生判据:grep 出的 import 集合必须等于 package.json。 README:分层表加 primitives/ 一行,并写清「不引成套组件库」的结论与 5 个 radix 包全部有 import。 报告第二十五章:现象归因表(对齐是 CSS bug、下拉与原生外观才是组件库该管的)、选型对照表、 三个根因的读数、逐项验收表(30 字段五判据 0 组、31/31、原生残留 0、13 装 6 用 → 5 装 5 用), 以及仍然没做的四条(MediaLightbox/RecordAudio 自绘 overlay、检查器刻意非模态、Tabs/tooltip 无用户先卸包、 日期与命令面板按需再补)。main
parent
b0086fb487
commit
83d262a199
10
README.md
10
README.md
|
|
@ -49,10 +49,11 @@ media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 r
|
|||
api/ 唯一的 fetch 出口:信封自动拆包、detail 统一成 Error、401 跳登录
|
||||
app/ 应用外壳:router.tsx 路由表(唯一一份)· layout/ 顶栏侧栏鉴权闸门
|
||||
pages/ 页面与项目页签,一屏一文件;页面私有的类名常量/子组件留在文件底部
|
||||
components/ 无业务语义的原语,三个目录按职责分:
|
||||
components/ 无业务语义的原语,四个目录按职责分:
|
||||
ui/ 版式与控件(Button/Field/Ctlbar/Table/Modal/Drawer/Tag…)
|
||||
forms/ 选择器族(Select/MultiSelect/SecretInput + toOptions)
|
||||
media/ 带全局状态的媒体件(MediaThumb/AudioPlay/MediaLightbox/WorkflowBar…)
|
||||
primitives/ 控件行为层(Radix primitives + CVA 皮肤:Popup/Dialog/Menu/Checkbox/Slider)
|
||||
stores/ zustand 切片:auth · theme · notice · project · models · system · audio · preview
|
||||
hooks/ use-async / use-polling / use-auto-refresh / use-outside-click / use-local-storage
|
||||
lib/ 纯函数与适配器:cn · format · media · pipeline · recorder · versions
|
||||
|
|
@ -62,6 +63,13 @@ styles/ tokens.css(设计令牌 = 唯一尺子来源)· base.css(元
|
|||
新增页面只做三件事:在 `pages/` 落文件 → 在 `app/router.tsx` 注册 → 复用 `components/*` 原语,
|
||||
缺原语就补进 `components/`(不要复制粘贴样式)。加一类新母版/新页签同理:改表不改逻辑(见 `docs/工程规范.md` §1.1)。
|
||||
|
||||
**控件不引成套组件库**(antd / MUI / Arco 都否掉了):行为层统一用 **Radix UI Primitives**,
|
||||
皮肤层是自己的一套令牌(`styles/tokens.css` + CVA),即 shadcn/ui 的架构、但不带第三方皮肤——
|
||||
组件源码在 `components/primitives/` 里可直接改,深浅两套 studio 视觉不用跟组件库的默认 token 抢方向盘。
|
||||
因此 `package.json` 只有 5 个 `@radix-ui/*`(popover / dialog / dropdown-menu / checkbox / slider),
|
||||
且每一个都有 import;页面里不许出现裸 `<select>`、原生 `checkbox`/`range`,也不许直接 `import '@radix-ui/*'`。
|
||||
选型理由、分层规矩与两个 Tailwind 陷阱见 `docs/UI规范.md` §0.6。
|
||||
|
||||
| 脚本 | 干什么 | 在哪儿跑 |
|
||||
| --- | --- | --- |
|
||||
| `scripts/dev.sh` | 开发态前后端两个进程(后端 8000 + Vite 5173),缺 `.env` / `.venv` / `node_modules` 自己补 | 开发机 |
|
||||
|
|
|
|||
116
docs/UI规范.md
116
docs/UI规范.md
|
|
@ -11,15 +11,18 @@
|
|||
> 所以下文写 `.ctlbar` / `.fld` / `.btn-add` 时,**照 §0.5 的对照表落成组件属性**,
|
||||
> 不要去新代码里 grep 这些类名,也不要为了让探针好看把它们塞回 `className`。
|
||||
>
|
||||
> 动手前先读三块基础设施,它们各自只有一份实现:
|
||||
> 动手前先读四块基础设施,它们各自只有一份实现:
|
||||
> ① 控件高度体系(`--ctl-h` / `--ctl-h-md` / `--ctl-h-main`,`styles/tokens.css`)
|
||||
> ② 控件栏与字段体系(`Ctlbar` / `Field` / `FormRow`,`components/ui/Controls.tsx`)
|
||||
> ③ 浮层体系(`Drawer` / `Modal`,`components/ui/Overlay.tsx`)。
|
||||
> 尺子只允许在这三处改,页面不要各自发明。
|
||||
> ② 控件栏与字段体系(`Ctlbar` / `Field` / `FieldBlock` / `FormGrid` / `FormRow`,`components/ui/Controls.tsx`)
|
||||
> ③ 浮层体系(`Drawer` / `Modal`,`components/ui/Overlay.tsx`)
|
||||
> ④ **控件行为层(`components/primitives/`:Radix + 自有皮肤,见 §0.6)**——
|
||||
> 浮层定位、翻边避让、焦点、键盘、Esc 分层、勾选框、滑杆、菜单的行为全部在这里,
|
||||
> 页面与 `ui/` 都不许再直接 `import '@radix-ui/*'`。
|
||||
> 尺子只允许在这四处改,页面不要各自发明。
|
||||
|
||||
---
|
||||
|
||||
## 0. 六条硬规则(违反任意一条 = 返工)
|
||||
## 0. 七条硬规则(违反任意一条 = 返工)
|
||||
|
||||
| # | 规则 | 反例(本轮截图) |
|
||||
|---|---|---|
|
||||
|
|
@ -28,7 +31,8 @@
|
|||
| R3 | **同一行控件必须等高、垂直居中**(`align-items:center` + 继承 `--ctl-h`);一行里出现两种高度 = 尺子坏了 | 图3 搜索框与右侧下拉中心线错开 |
|
||||
| R4 | **chip 行 / 标签行与下方内容至少 12px 间隔**(`ChipBar` 与 `TagGroup` 自带 `mb-3`),且行本身不参与贴边 | 图2 「标签」chip 行压住下方面板 |
|
||||
| R5 | **筛选项准入**:每个筛选项必须 ① 对应后端真实参数 ② 在当前设计里有可达的非默认值 ③ 与页面顶部已选的大分类一致。三者缺一就删 | 图3 「每页」属于分页条,不属于筛选栏 |
|
||||
| R6 | **不用原生 `<select>`**:单选 `Select`、多选 `MultiSelect`(`components/forms`);自动刷新类组件不放「立即刷新」按钮 | 全站历史问题 |
|
||||
| R6 | **控件不用浏览器原生外观**:`<select>` / `input[type=checkbox]` / `input[type=range]` 一律不裸写,也不在原生上做 CSS 补丁——单选 `Select`、多选 `MultiSelect`、勾选 `Check`、滑杆 `Slider`、菜单与抽屉模态全部走 `components/primitives`(§0.6)。自动刷新类组件不放「立即刷新」按钮 | 全站历史问题;原生 `range`/`checkbox` 在深浅两版主题里各长一个样 |
|
||||
| R7 | **同一个容器只用一种字段形态**:同一列栅格里「标签在上的 `FieldBlock`/`FormRow stack`」与「标签在左的 `Field`」不许混排——两种形态的控件左缘天生差一个标签列宽,混排 = 一定不齐。窄列(< 240px)一律竖排 | `/review` 人工审核那列:`审核人` 行内、`问题描述` 竖排,控件左缘出现 1353 / 1425 / 1472 三种 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -51,7 +55,13 @@
|
|||
| `.pager` | `<Pager sizes total pageSize onChange>`(`0` = 全部) | `ui/Controls.tsx` |
|
||||
| `.check` | `<Check checked onChange disabled title>` | `ui/Controls.tsx` |
|
||||
| `.upload` / 选文件 | `<FilePick label hint onChange>` | `ui/Controls.tsx` |
|
||||
| 原生 `<select>`(R6 禁用) | `<Select options>` / `<MultiSelect>`,选项一律过 `toOptions` | `forms/Select.tsx` · `forms/MultiSelect.tsx` |
|
||||
| 原生 `<select>`(R6 禁用) | `<Select options>` / `<MultiSelect>`,选项一律过 `toOptions`;浮层行为在 `primitives/Popup` | `forms/Select.tsx` · `forms/MultiSelect.tsx` |
|
||||
| 原生 `<input type=checkbox>`(R6 禁用) | `<Check checked onChange title>`(Radix Checkbox,`role=checkbox`,点文字也切换) | `ui/Controls.tsx` · `primitives/Checkbox.tsx` |
|
||||
| 原生 `<input type=range>`(R6 禁用) | `<Slider value min max step onChange>`(Radix Slider,键盘方向键可调) | `ui/Slider.tsx` · `primitives/Slider.tsx` |
|
||||
| 裸 `<button>` + 手写下拉面板(旧 `use-popup` / `parts.ts`,已废弃) | `<Popup>`(Radix Popover:portal / 翻边 / 视口避让 / 外点关闭 / 焦点归还) | `primitives/Popup.tsx` · `primitives/layers.ts` |
|
||||
| 手写遮罩 + `fixed inset-0` 的菜单 | `<Menu>` / `<MenuItem>`(Radix DropdownMenu,方向键 + 焦点归还) | `primitives/Menu.tsx` |
|
||||
| 抽屉 / 模态的遮罩、Esc、锁滚动、焦点圈定 | `<Drawer>` / `<Modal>` 内部用 `primitives/Dialog`(Radix Dialog) | `ui/Overlay.tsx` · `primitives/Dialog.tsx` |
|
||||
| 页面级快捷键「有浮层就别抢 Esc / 空格」 | 处理函数第一行 `if (floatingLayerOpen()) return` | `primitives/layers.ts` |
|
||||
| `.primary` `.secondary` `.outline` `.ghost` `.tiny` `.danger` | `<Button variant size="sm\|md\|lg" danger on>` | `ui/Button.tsx` |
|
||||
| `.btn-add` `.btn-del` `.btn-del.solid` `.sq` `.lg` | `<Button variant="add">` / `variant="del"` / `variant="del" danger` / `square` / `size="lg"` | `ui/Button.tsx` |
|
||||
| `<a>` 要按钮皮肤(路由跳转) | `buttonCls({ variant })` 或 `<Button variant="link">` | `ui/Button.tsx` |
|
||||
|
|
@ -70,6 +80,74 @@
|
|||
| 抽屉里的整宽 textarea(86px 起、可拉长) | 在容器上挂 `TEXTAREA_TALL` | `ui/Controls.tsx` |
|
||||
| 栅格降列 | `<Grid cols min oneAt steps>`——变量驱动,页面不写 `@media` | `ui/Panel.tsx` |
|
||||
|
||||
## 0.6 标准控件组 = Radix primitives(headless)+ 自有皮肤
|
||||
|
||||
**决策(2026-11-02 定):全站控件的「行为」统一交给 Radix UI Primitives,「长相」仍然是我们自己的令牌 +
|
||||
CVA。也就是 shadcn/ui 的架构,只是组件源码留在仓库里(`components/primitives/`),不引第三方皮肤包。**
|
||||
一句话:**尺子和皮肤不换,只把「自己造浮层」这一件事外包出去。**
|
||||
|
||||
### 0.6.1 四层分工(依赖只允许自上而下)
|
||||
|
||||
| 层 | 唯一来源 | 管什么 | 不管什么 |
|
||||
|---|---|---|---|
|
||||
| 尺子 | `styles/tokens.css` | `--ctl-h*` / `--label-w` / `--field-label-w` / `--check-size` / 颜色 / 断点 | 任何 DOM |
|
||||
| 行为 | `components/primitives/*.tsx`(Radix) | portal、锚点定位、翻边与视口避让、焦点圈定与归还、Esc 分层、键盘、ARIA、锁滚动 | 尺寸、配色 |
|
||||
| 皮肤 | `components/primitives/layers.ts`(CVA + `cn`) | 触发器 / 面板 / 选项行 / 遮罩的类名档位,数值全部 `var(--c-*)`、`h-(--ctl-h)` | 业务语义 |
|
||||
| 语义 | `components/ui/` `components/forms/` | `Field` `FormRow` `Select` `Check` `Slider` `Drawer` `Modal` 这些页面认识的名字 | 直接 import Radix |
|
||||
|
||||
现在 `primitives/` 里是**五个原语 + 一份档位(`layers.ts`)+ 一个键盘 hook(`use-listbox`)**,每一个都能在页面上指出用户:`Popup`(Radix Popover,Select / MultiSelect 的浮层)、
|
||||
`Dialog`(Radix Dialog,`Drawer` / `Modal` 的遮罩与焦点)、`Menu`(Radix DropdownMenu,账号菜单)、
|
||||
`Checkbox`(全站 30 处 `<Check>`)、`Slider`(模型参数 / 时间轴)、`use-listbox`(下拉的键盘与首字母定位,
|
||||
不是 Radix 包,是我们自己的 hook)。**装了没在用的依赖一律清掉**:本轮卸载了 8 个
|
||||
(tabs / tooltip / label / separator / progress / radio-group / switch / visually-hidden),
|
||||
`package.json` 里剩的 5 个 `@radix-ui/*` 全部有 import。将来要加原语,`npm i` + 一个文件 + 回到本表登记。
|
||||
|
||||
### 0.6.2 为什么不引 antd / MUI / Arco 这类成套组件库
|
||||
|
||||
三条理由都是量出来的,不是审美偏好:
|
||||
|
||||
1. **会变成两套尺子**。它们自带 token 与组件级主题:antd 说控件高 32px,我们的 `--ctl-h-main` 是 38px,
|
||||
同一个页面两种「控件高度」的说法,本轮刚清完的「字段标题不对齐」会换个地方原地复发。
|
||||
2. **全局重置打架**。Tailwind v4 的 base 层已经接管元素基线(`styles/base.css`:input / textarea /
|
||||
`[role=combobox]` 全部 `appearance-none` + `h-(--ctl-h)`),组件库再注入一份 preflight,
|
||||
深浅主题切换时谁覆盖谁取决于样式注入顺序,等于把对齐交给运气。
|
||||
3. **深色 studio 皮肤要覆盖八成以上**。组件库的默认外观就是我们要消灭的「原生感」;改到看不出它是 antd
|
||||
之后省下的工时全数还回去,还多背整包体积和一次大版本迁移风险(antd v4→v5 的 token 迁移就是前车之鉴)。
|
||||
|
||||
要「装完就有皮肤」的替代方案是 Base UI 或直接抄 shadcn 官方皮肤。代价同样是第 1、3 条——
|
||||
我们的视觉已经定了,皮肤本来就得自己写,那么值得外包的只剩行为层,这正好是 Radix 的边界。
|
||||
|
||||
### 0.6.3 规矩
|
||||
|
||||
- **页面与 `ui/` 不许 `import '@radix-ui/*'`**,也不许再手写 `fixed inset-0` 的浮层。要一层新浮层:
|
||||
在 `primitives/` 加一个文件(Radix Root + `layers.ts` 档位)→ 在 `ui/` 给它业务名字 → 登记进 §0.5 与本节。
|
||||
- **浮层叠浮层时,页面级快捷键先看一眼 `floatingLayerOpen()`**(`primitives/layers.ts`)。
|
||||
Radix 的 Esc 只关自己那一层,页面的 `window` keydown 是另挂的;漏了这道判据就是
|
||||
「按一下 Esc,下拉连同背后的抽屉一起没了」。分镜检查器、素材预览器、版本面板三条路径都踩过这个坑。
|
||||
- **层级只用一套**:遮罩 100 / 抽屉 101 / 模态 111 / 下拉与菜单 400;每层浮层自带
|
||||
`data-nex-layer`,判据靠它,不靠 z-index 猜。
|
||||
- **行为层的缺口用行为层的积木补,别为它请整个组件库**:Radix 没有 combobox,
|
||||
所以可搜索 / 多选下拉 = `primitives/Popup` + `primitives/use-listbox`;
|
||||
面板宽度「至少等于触发器、按最长选项展开到 440px」直接消费 Radix 给的
|
||||
`--radix-popover-trigger-width` 与 `--radix-popover-content-available-*`,不需要手算 left/top。
|
||||
- **`Content` 上不许写 `position:fixed`**:Radix 的定位 translate 在它外层 wrapper 上,
|
||||
面板自己 fixed 就脱离文档流,wrapper 量到的高度是 0,flip/size 全按 0 高算
|
||||
(表现:贴近视口底边的下拉要么该翻不翻被压成 35px,要么翻了不掉高度掉出屏幕 125px)。
|
||||
|
||||
### 0.6.4 两个咬过人的陷阱(改这块代码前先读)
|
||||
|
||||
1. **Tailwind 的 `[&>*]:min-w-0` 会无声清零 `min-w-(--label-w)`**。两条规则特指度都是 0-1-0,
|
||||
而 Tailwind 把 `min-w-0` 排在自定义值之后 → 后者赢。`Field` 需要前者让长控件能收缩,
|
||||
又需要后者撑住 66px 的标签列,于是在同一个元素上打架,症状就是**字段标题各就各位地歪开**:
|
||||
同一个容器里出现 47px 的控件右移。修法是把下限写进带属性的选择器
|
||||
(`[&>span:first-child]:min-w-(--label-w)`,0-2-0 才压得住),`Controls.tsx` 里那段 ⚠️ 注释别删。
|
||||
2. **Playwright 的 `locator.click()` 会先把目标居中**(CDP `DOM.scrollIntoViewIfNeeded`)。
|
||||
目标在文档顶部时理想 scrollY 是负数、被钳到 0,于是「打开抽屉把页面顶回顶部」这种假 bug
|
||||
能追一整轮——真实鼠标 `mouse.click(x, y)` 全程守恒。**量滚动位移之前,基线必须在
|
||||
`scroll_into_view_if_needed()` 之后再取**,或者干脆用真实鼠标点击(§8 的探针按这个口径写)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 控件栏(工具条 / 筛选条 / 搜索条 / 卡片动作行)
|
||||
|
||||
规范类名 `.ctlbar`,它是**所有**含控件横条的唯一实现。页面里出现下列任意旧类名时,
|
||||
|
|
@ -342,6 +420,14 @@ sm 档给密度高的地方:表格单元格、缩略图角标、一行挤五
|
|||
<div class="frow cols6 stack tight segfields">…时间线片段参数…</div>
|
||||
```
|
||||
|
||||
**同一种形态只用到底(R7)**:`stack` 是**容器级**开关,不是字段级开关。一个多行容器里
|
||||
出现一个 `FieldBlock` + 一个行内 `Field`,控件左缘必然差出整个标签列宽——`/review` 的
|
||||
「人工审核」两列就是这么烂的:`审核人` 行内(标签 66px)、`问题描述` 竖排,
|
||||
同一列里量出 **1353 / 1425 / 1472 三种控件左缘**(最大右移 47.3px)。
|
||||
这一列宽 > 240px 才允许行内;抽屉、审核台、检视器这类多行容器默认 `FormRow stack`。
|
||||
豁免只有两类:**滑杆行与勾选行**(`Temperature`、`立即重新入队生成`——标签即说明、
|
||||
轨道/方框即整行,本来就没有「控件左缘」这个概念),探针按 `role` 跳过它们。
|
||||
|
||||
历史类名 `.form-grid two|three|four`、`.segfields` 全部并入这一套;页面里
|
||||
不得再写 `.form-grid{…}`、`.segfields{grid-template-columns:…}` 这类尺子,
|
||||
只保留皮肤(边框/背景)。规则:
|
||||
|
|
@ -368,7 +454,11 @@ sm 档给密度高的地方:表格单元格、缩略图角标、一行挤五
|
|||
配色 `text-muted` / `text-faint`,**不超过一行**;超出的解释进手册(`/help` → `frontend/src/pages/Help.tsx`)或 `title` 提示。
|
||||
规则说明以前塞在 `placeholder` 里(改密码页「至少 8 位,包含…」),一开始输入说明就消失了。
|
||||
`hint` 现在真正落地:带 hint 的 `Field` 把自己翻成
|
||||
`grid grid-cols-[auto_minmax(0,1fr)]`,标签左上、控件右上、说明贴在控件下面。
|
||||
`grid grid-cols-[minmax(var(--label-w),max-content)_minmax(0,1fr)]`,
|
||||
标签左上、控件右上、说明贴在控件下面。**标签列必须是 `minmax(下限, max-content)` 而不是 `auto`**:
|
||||
`auto` 轨道会被内容压缩,中文标签 2~5 字,控件起点就跟着字数漂(`--field-label-w: 66px`
|
||||
是全站 193 个行内标签的 p90,见 `styles/tokens.css`)。下限挂在带属性的选择器上,
|
||||
原因见 §0.6.4 的 `[&>*]:min-w-0` 平票陷阱。
|
||||
**这里不能用 `flex-wrap`**:base.css 里控件是 `w-full`,一换行控件就整只跑到第二行、
|
||||
标签退回上面,同一栅格里就成了「一个横排、两个竖排」(违反 R3)。
|
||||
配套两条在 `FormRow` 上:`[&>*]:self-start`(带 hint 的字段把行撑高后,旁边的字段仍贴格子
|
||||
|
|
@ -645,6 +735,16 @@ sm 档给密度高的地方:表格单元格、缩略图角标、一行挤五
|
|||
`nex_d_shot.py`(整页截图 + console/pageerror 计数,改完必须目视一遍)。
|
||||
判据全部走计算样式与 Tailwind 工具类,不依赖旧类名;四者都要求
|
||||
**0 红项 + 0 console error**,红项按 §2.4 / §1.2.1 的例外清单逐条解释。
|
||||
**字段对齐(R7)与控件行为这两件事,2026-11 起以这两条为准**:
|
||||
- `nex_align4.py` — 全站 30 个表单字段,五项判据各要求 **0 组**:
|
||||
① 同列控件左缘不一致 ② 标签压住控件 ③ 控件溢出字段盒 ④ 行内标签与控件中心不齐
|
||||
⑤ 同列 stack/inline 混用(⑤ 按 `role` 豁免滑杆与勾选行)。
|
||||
判据只看 `--label-w != 0` 的容器(工具条不参与表单对齐),滑到字段级,红项打印标签文字与左右缘。
|
||||
- `nex_ctl4.py` — 31 项控件行为回归(抽屉 + 下拉叠加、Esc 只关一层、锁滚动不横跳、
|
||||
点文字切勾选、滑杆键盘可调、无原生控件残留、分页 Select、菜单方向键与焦点归还、
|
||||
真实鼠标开/关抽屉窗口滚动守恒),要求 **31/31 + 0 console error**。
|
||||
⚠️ 里面所有「滚动位置」断言的基线都在 `scroll_into_view_if_needed()` 之后取,
|
||||
新增断言请照抄这个写法,否则又会造出 §0.6.4 第 2 条那种假 bug。
|
||||
6. 改了 `styles/tokens.css` 的令牌或 `styles/base.css` 的元素基线(含 `--ctl-h*`、媒体查询)→ 必须双主题全量重跑
|
||||
(深浅各 83 + 浮层 16 + 用户位 5 + 生成台 2 = 195 作业),不能只跑改动页。
|
||||
**窄屏(430px)也在回归宽度里**:只在 ≤560px 生效的规则必须有证据,不能靠推理。
|
||||
|
|
|
|||
18
docs/工程规范.md
18
docs/工程规范.md
|
|
@ -27,15 +27,22 @@
|
|||
前端从 Vue 换成 React + Tailwind 后,目录职责按「**依赖只允许自上而下**」执行:
|
||||
|
||||
```text
|
||||
api/ → app/ → pages/ → components/{ui,forms,media}/ → hooks/ · lib/ → styles/
|
||||
api/ → app/ → pages/ → components/{ui,forms,media}/ → components/primitives/ → hooks/ · lib/ → styles/
|
||||
```
|
||||
|
||||
`components/primitives/` 是**行为层**,站在皮肤层下面一层:Radix 负责浮层定位、翻边避让、焦点圈定与归还、
|
||||
键盘、Esc 分层、锁滚动,`primitives/layers.ts` 用 CVA + `tokens.css` 令牌给它套皮肤。
|
||||
`ui/` `forms/` 只认 primitives 给出的业务名字(`Popup` `Dialog` `Menu` `Checkbox` `Slider`),
|
||||
**页面和 `ui/` 都不许直接 `import '@radix-ui/*'`**——换行为库时改动面就是这一个目录。
|
||||
选型理由与规矩见 [UI规范.md](UI规范.md) §0.6。
|
||||
|
||||
| 目录 | 放什么 | **不**放什么 |
|
||||
|---|---|---|
|
||||
| `api/` | 唯一的 `fetch` 出口(信封拆包、`detail`→`Error`、401 跳登录) | 业务分支、组件状态 |
|
||||
| `app/` | 外壳:`router.tsx` 路由表 · `App.tsx` 布局与守卫 · `ErrorBoundary.tsx` 分包失败兜底 · `layout/` 顶栏侧栏与 `nav.ts` 页签表 | 任何业务接口调用 |
|
||||
| `pages/` | 一屏一文件;页面私有小组件与类名常量在文件底部 | 页面之间的互相 import |
|
||||
| `components/ui/` | 版式与控件原语(`Button` `Field` `Ctlbar` `Table` `Modal` `Drawer` `Tag` `Pager`…) | 业务字段名、接口路径 |
|
||||
| `components/ui/` | 版式与控件原语(`Button` `Field` `Ctlbar` `Table` `Modal` `Drawer` `Tag` `Pager`…) | 业务字段名、接口路径、直接 import `@radix-ui/*` |
|
||||
| `components/primitives/` | 控件**行为层**:Radix Root + `layers.ts`(CVA 档位)+ `use-listbox`;`Popup` `Dialog` `Menu` `Checkbox` `Slider` | 业务语义、写死的 px(尺寸只能来自 `tokens.css` 变量) |
|
||||
| `components/forms/` | 选择器族(`Select` `MultiSelect` `SecretInput` + `toOptions`) | 页面专属选项 |
|
||||
| `components/media/` | 带全局状态的媒体件(`MediaThumb` `AudioPlay` `MediaLightbox` `VersionPanel` `WorkflowBar`) | 纯展示(那些进 `ui/`) |
|
||||
| `stores/` | zustand 切片(auth · theme · notice · project · models · system · audio · preview)+ 少量全站静态字典 | 组件本地 state |
|
||||
|
|
@ -51,6 +58,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → hooks/ ·
|
|||
| 改某页每页条数档位 | `Pager` 的 `sizes`(页面里传 `PAGE_SIZES`,`0` = 全部) | 默认档位和「全部」语义在 `Controls.tsx` 一处实现 |
|
||||
| 抽屉想要别的宽度 | `Drawer` 的 `width` 收一个 Tailwind 宽度类 | 默认值只在 `Overlay.tsx` 写一次,页面按屏宽传变体 |
|
||||
| 新增弹窗/表单 | `Modal` `Drawer` `Field` `FormRow` 组合 | 高度、间距、页脚按钮排布由原语和容器 `--ctl-h` 档位兜住 |
|
||||
| 加一类控件行为(tooltip / 命令面板 / 日期选择…) | `primitives/` 新加一个文件(Radix Root + `layers.ts` 档位)→ `ui/` 给业务名字 → 登记进 UI规范 §0.5 与 §0.6 | 行为与皮肤分层,页面那层永远只见到一个组件名;Radix 没提供的(combobox)用 `Popup` + `use-listbox` 拼 |
|
||||
| 控件档外的高度 | 容器上写 `[--ctl-h:var(--ctl-h-md)]` | 控件一律 `h-(--ctl-h)`,禁止单个控件写死像素 |
|
||||
|
||||
**根目录只允许**:`README.md`、`docker-compose.yml`、`.env`、`.env.example`、`.gitignore`
|
||||
|
|
@ -126,6 +134,12 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → hooks/ ·
|
|||
不建 `.css`、不写 `@media`——窄屏行为用断点变体(`max-mid:` `max-narrow:` `max-short:`)写在类上。
|
||||
- **一页一文件**,页面专属的类名常量与两行就够的小组件留在页面文件底部,
|
||||
被第二个页面用到才提进 `components/`;反向也要提,别让两个页面各养一份皮肤。
|
||||
唯一的例外是 `components/primitives/`:**行为层原语一个用户就进**,因为它换掉的是
|
||||
「谁来实现浮层」这件事的整个成本,不该等第二个用户。
|
||||
- **依赖清单必须等于实际 import**:`package.json` 里装了没人 import 的包要卸载。
|
||||
2026-11-02 清掉 8 个装了没用的 `@radix-ui/*`(tabs / tooltip / label / separator / progress /
|
||||
radio-group / switch / visually-hidden),顺带删掉唯一消费死包链的 `ui/Toggle.tsx`(0 个用户)。
|
||||
判据一条命令:`grep -rho "@radix-ui/[a-z-]*" frontend/src | sort -u` 对 `package.json` 的 dependencies。
|
||||
|
||||
## 5. 部署:数据边界与流程
|
||||
|
||||
|
|
|
|||
|
|
@ -2064,3 +2064,114 @@ import 那道确实炸出 `No module named 'app.models.base'` ✅。
|
|||
|
||||
反向验证(不做这一步,不变量只是装饰):往 `.gitignore` 临时塞一条 `backend/app/models/`,
|
||||
`deploy.sh --check` 立刻把 11 个 ORM 文件逐个点名并 die;撤掉恢复绿色 ✅。
|
||||
|
||||
---
|
||||
|
||||
# 第二十五章 · 控件行为层选型:Radix primitives + 自有皮肤,以及「字段标题不对齐」的真凶(2026-11-02)
|
||||
|
||||
## 25.1 这一轮是从一句抱怨开始的
|
||||
|
||||
> 还是有很多问题啊,比如字段标题、控件不对齐。下拉控件的样式等问题。现在需要你决定是否选用一套标准的前端控件组,
|
||||
> 而非全部在原生控件上改。如果选前端控件组,基于当前的技术栈,你的建议是什么?
|
||||
|
||||
抱怨的是三件事,分开看它们的性质完全不同:
|
||||
|
||||
| 现象 | 归因 | 是不是「缺组件库」 |
|
||||
|---|---|---|
|
||||
| 字段标题与控件不对齐 | **CSS 优先级 bug**(同一个元素上两条 `min-width` 平票)+ 同一列两种字段形态混排 | ❌ 引谁都要修 |
|
||||
| 下拉控件样式不统一 | 浮层是自己手写的(定位/翻边/焦点/Esc 全自研),原生 `<select>` 的外观又改不动 | ✅ 这一半正是组件库该管的 |
|
||||
| 抽屉/勾选框/滑杆在深浅主题里各长一个样 | 原生 `checkbox` / `range` 在 macOS 是系统绿圆角块、在 Windows 是方角,`appearance` 补丁按平台失效 | ✅ 同上 |
|
||||
|
||||
结论先给:**要一套标准控件组,但只买「行为」,不买「皮肤」——Radix UI Primitives(headless)+ 我们自己的
|
||||
令牌皮肤**,即 shadcn/ui 的架构、组件源码 vendored 在 `components/primitives/`。理由写进 `docs/UI规范.md` §0.6,
|
||||
摘要在 25.2。
|
||||
|
||||
## 25.2 决策:为什么是 Radix,而不是 antd / MUI / Arco
|
||||
|
||||
| 候选 | 换来什么 | 代价(量过的,不是推测) |
|
||||
|---|---|---|
|
||||
| **Radix primitives + 自有皮肤(选定)** | 浮层定位/翻边/视口避让/焦点圈定与归还/键盘/Esc 分层/锁滚动/ARIA 全部外包;DOM 与类名仍归我们 | 需要自研的只有「皮肤 + 业务语义」两层,而这两层本来就要自己写;Radix 没有 combobox,可搜索/多选下拉要用 `Popup` + `use-listbox` 自己拼 |
|
||||
| antd / MUI / Arco 成套组件库 | 装完就有皮肤和交互 | ① **两套尺子**:它说控件高 32px,我们的 `--ctl-h-main` 是 38px,同一个页面两种高度说法,本轮刚清完的对齐问题换个地方原地复发;② **preflight 打架**:Tailwind v4 的 base 层(`styles/base.css`)已经接管元素基线,再注一份 reset,深浅主题谁覆盖谁看注入顺序;③ **深色 studio 视觉要覆盖八成以上**,改到看不出它是 antd 之后省下的工时全数还回去,还多背整包体积 + 一次大版本迁移(antd v4→v5 token 迁移即前车之鉴) |
|
||||
| Base UI / 直接抄 shadcn 官方皮肤 | 同上,API 更新潮 | 代价同上两条:皮肤必须自己重写,否则字号圆角与 `tokens.css` 打架 |
|
||||
|
||||
一句话:**我们的视觉早就定了,皮肤本来就得自己写;那么值得外包的只剩行为层,而行为层正好是 Radix 的边界。**
|
||||
|
||||
落地后的分工(依赖只允许自上而下,`docs/工程规范.md` §1.1):
|
||||
|
||||
```text
|
||||
styles/tokens.css → components/primitives/ → components/{ui,forms}/ → pages/
|
||||
尺子 行为(Radix) 语义 + 皮肤(CVA) 业务
|
||||
```
|
||||
|
||||
`primitives/` 现在 634 行、5 个 Radix 包 + 1 个自研键盘 hook,撑起 16 个页面里的
|
||||
**76 处 `Select` + 4 处 `MultiSelect` + 30 处 `Check` + 2 处 `Slider` + 13 处 `Drawer` + 5 处 `Modal`
|
||||
+ 12 处 `Menu`**(`grep -rn --include='*.tsx'` 数页面与 `app/` 的调用点,不含组件定义自身)。
|
||||
页面与 `ui/` 一律不许直接 `import '@radix-ui/*'`,也不许再手写 `fixed inset-0` 的浮层。
|
||||
|
||||
## 25.3 三个根因(都有读数)
|
||||
|
||||
**① 「字段标题不对齐」不是排版问题,是 Tailwind 优先级平票把标签下限无声清零。**
|
||||
`Field` 同时需要 `[&>*]:min-w-0`(让长控件能收缩)和 `min-w-(--label-w)`(撑住 66px 标签列),
|
||||
前者编译成 `.min-w-0 > *`,与后者同为 **0-1-0 特指度**,而 Tailwind 把 `min-w-0` 排在自定义值之后 → 后者赢,
|
||||
`--field-label-w: 66px` 整列下限**被清零**,控件左缘跟着中文标签的字数漂。
|
||||
`/review`「人工审核」那一列量到三种控件左缘 **1353 / 1425 / 1472**,最大右移 **47.3px**
|
||||
(`审核人` 66px、`任务优先级` 66px、`覆盖负面提示词(可选)` 113.3px 三种标签宽各推各的)。
|
||||
修法是给下限换一条压得住的选择器:`[&>span:first-child]:min-w-(--label-w)`(0-2-0),代码里留了 ⚠️ 注释。
|
||||
|
||||
**② 同一列混了两种字段形态(新立硬规则 R7)。**
|
||||
`审核人` 走行内 `Field`、`问题描述`/`覆盖提示词` 走 `FieldBlock`——两种形态的控件左缘天生差整个标签列宽,
|
||||
谁都对不齐谁。`Review.tsx` 两列 4 处 `FormRow` 全部改 `stack`,容器级统一成「标签在上」。
|
||||
豁免两类:**滑杆行与勾选行**(标签即说明、轨道/方框即整行,没有「控件左缘」这个概念),探针按 `role` 跳过。
|
||||
|
||||
**③ 「开抽屉把页面顶回顶部」是探针伪影,追掉了一整轮。**
|
||||
逐帧排查:`react-remove-scroll` 注入的规则、`focus({preventScroll:true})`、有没有 JS 调 `scrollTo`,全绿;
|
||||
真凶是 Playwright 的 `locator.click()` 会先 CDP `DOM.scrollIntoViewIfNeeded` 把目标**居中**——
|
||||
入口按钮在文档顶部(文档 y≈94、视口 520),理想 scrollY 是负数、被钳到 0,于是「点了顶栏的添加 → scrollY=0」
|
||||
被读成「抽屉把页面顶回顶部」。真实鼠标路径全程守恒:`101 → 开(1) 101 → Esc 关(0) 101`(视口 520、文档高 671)。
|
||||
**产品代码一行没改**,改的是探针口径:基线必须在 `scroll_into_view_if_needed()` 之后取。
|
||||
教训已写进 UI规范 §0.6.4 与 §8。
|
||||
|
||||
## 25.4 改法
|
||||
|
||||
1. **建行为层**:`primitives/{Popup,Dialog,Menu,Checkbox,Slider}` + `layers.ts`(CVA 档位)+ `use-listbox.ts`(键盘/首字母定位)。
|
||||
面板宽度直接消费 Radix 给的 `--radix-popover-trigger-width` 与 `--radix-popover-content-available-{width,height}`,
|
||||
旧 `use-popup.ts` 里手算 left/top/maxH 与二次纠正整段删掉。
|
||||
2. **原生控件清零**:`checkbox` → Radix Checkbox(点文字也切换,尺寸 `--check-size` 14px/触摸档 18px)、
|
||||
`range` → Radix Slider(方向键可调)、分页与全站裸 `<select>` → `Select`/`MultiSelect`(浮层归 Radix Popover)、
|
||||
账号菜单与抽屉遮罩 → Radix Menu/Dialog。
|
||||
Radix Checkbox 在 `<form>` 内会渲染一个 `opacity:0` 的隐藏 `input` 作表单代理——**那不是原生控件残留**,
|
||||
探针按 `[role=checkbox]` 认可见控件,别按 `input` 认。
|
||||
3. **Esc 分层**:每层浮层带 `data-nex-layer`,页面级快捷键第一行 `if (floatingLayerOpen()) return`。
|
||||
层级只用一套:遮罩 100 / 抽屉 101 / 模态 111 / 下拉与菜单 400。
|
||||
4. **尺子补齐**:`--field-label-w: 66px`(全站 193 个行内标签的 p90)+ `--label-w` 作用域开关
|
||||
(`FormRow` 抬起、`Ctlbar`/`ChipBar`/`CardActions`/`Pager` 压回 0,工具条不参与表单对齐)+ `--check-size`。
|
||||
手机档(≤560px)一行一个字段,没有对齐对象,`--field-label-w` 直接归 0。
|
||||
5. **依赖卫生**:卸载 8 个装了没在用的 `@radix-ui/*`(tabs / tooltip / label / separator / progress /
|
||||
radio-group / switch / visually-hidden),顺带删掉这条死链上唯一消费它们的 `ui/Toggle.tsx`(0 个用户)。
|
||||
`package.json` 现在剩 5 个 `@radix-ui/*`,**每一个都能在源码里指出 import 它的那一行**。
|
||||
|
||||
## 25.5 逐项验收
|
||||
|
||||
| 判据 | 改前 | 改后(实测) |
|
||||
|---|---|---|
|
||||
| 同列控件左缘不一致的组 | 1 组(`/review` 差 47.3px,三种左缘) | **0 组** / 30 个字段 |
|
||||
| 同列 stack 与 inline 混用的组 | 1 组 | **0 组**(滑杆/勾选行按 `role` 豁免) |
|
||||
| 标签压住控件 / 控件溢出字段盒 / 行内标签与控件中心不齐 | — | **0 / 0 / 0** |
|
||||
| 控件高度档(每页只允许一档) | — | account `[38]`、users `[38]`、review `[38]`、models 抽屉 `[14, 38]`(14 = 滑杆轨道,另一族) |
|
||||
| 原生控件残留(`<select>` / `type=checkbox` / `type=range`) | 分页 select、系统勾选框、系统滑杆、自绘菜单 | **0**(`grep` 仅剩 3 条注释里的名字) |
|
||||
| 控件行为回归 `nex_ctl4.py` | — | **31/31 通过 + 0 console error**(含抽屉+下拉叠加、Esc 只关一层、锁滚动不横跳、点文字切勾选、滑杆键盘可调、菜单方向键与焦点归还、真实鼠标开关抽屉滚动守恒) |
|
||||
| 表单对齐 `nex_align4.py` | — | **5 项判据全 0,errs 0** |
|
||||
| 下半屏下拉是否完整落在视口内 | 35px 被压扁 / 掉出屏幕 125px / 右侧溢出 45px | **19 个全部完整落在视口内**,三档视口宽度无横向裁切(同日上一节提交) |
|
||||
| `tsc --noEmit` / `npm run build` | — | EXIT=0(`ui-*.js` 67.7 kB gzip) |
|
||||
| `@radix-ui/*`:安装数 = import 数 | 13 装 / 6 用 | **5 装 / 5 用** |
|
||||
|
||||
## 25.6 仍然没做(别以为一套组件库进来就全好了)
|
||||
|
||||
1. `MediaLightbox`(z-220)与 `RecordAudio`(z-260)仍是自绘 overlay:它们要的是「沉浸式预览 + 键盘左右切图」,
|
||||
换成 Radix Dialog 得先解决焦点圈定把播放器吃掉的问题,收益不明确,先记账。
|
||||
2. 分镜「检查器」刻意不做成模态(遮罩会吞掉左边看板的点击),所以它借 `DRAWER_*` 常量而不进 `primitives/Dialog`——
|
||||
这是设计,不是漏迁移。
|
||||
3. `Tabs`(分段页签)与 tooltip 还没迁到 Radix:本轮把这两个包卸了,因为**当前没有任何用户需要它们的浮层行为**;
|
||||
真要做(命令面板、悬浮预览),按 §0.6.3 的三步流程加原语,别在页面里手搓。
|
||||
4. 日期/时间选择器、命令面板、Toast 队列这三个常见件还没需求,来了需求再补 `primitives`,
|
||||
这是 headless 架构最省事的一面:**加一个原语 ≈ 一个文件,加一个组件库 = 换一次方向盘。**
|
||||
|
|
|
|||
Loading…
Reference in New Issue