8.7 KiB
参数面板与数值双向绑定 · 设计
父任务
08-26-direct-manipulation-road-editor/design.md仍是约束模型、求解边界与 API 合约的权威定义。本文只补充第二条输入通道引入的规则,不改变其中任何一条。
架构定位
本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层:
┌─ 拖拽(连续)──→ projectHandleValue() ─┐
选中道路 → manifest ─┤ ├→ draftFor(handle, value)
└─ 输入框(离散)→ 解析 + 范围校验 ──────┘ ↓
PreviewRequester
(80ms 防抖 + previewSeq 仲裁)
↓
EditSession.commit()
draftFor(handle, value)(App.tsx:206)本就是纯函数 (手柄, 数字) → 草稿。两条通道的唯一区别是如何产生那个数字以及何时闭合 gesture,汇合点之后完全一致。
不变量:取值范围
约束值永不超出 manifest 声明的
[min, max]。
- 连续输入(拖拽、滑杆)在极限处停止移动。ghost 与手柄按夹后的值绘制,绝不跟随越界的光标。
- 离散输入(数值框)拒绝接受越界值:标记非法、不发预览、不进 undo 栈、保留最后一个有效预览。范围提示可一键填入极值。
这是一条规则的两种设备表达,不是两套策略。
连续设备没有表达"拒绝"的手段——停止移动就是它的拒绝,而且是当场可见的:手柄停住、光标继续走。用户不会形成"我设成了 -24.1"这个信念。夹值理由见 projection.ts:75 的注释(ol-ext 探针把手柄拖到 -24.1m 而约束夹在 -5.4m,手柄指向一个不可能存在的路形)。
离散设备则相反:数字已经键入、Tab 已经按下,此时夹值是事后篡改。且失败模式不对称——
| 用户意图 | 夹值 | 拒绝 |
|---|---|---|
| 打错(想输 2.4,输成 24) | 变成 5.4,看起来合理,可能永不被发现 | 立即可见 |
| 想拉满 | 如愿 | 多一步(或点范围提示一键填入) |
拒绝错了只损失一次击键;夹值错了会把一个看起来正常的错误值送进下游编译与仿真。故取拒绝。
值的所有权
任一时刻,一个参数的显示值来源是唯一且由聚焦状态决定的:
| 状态 | 显示值 | 理由 |
|---|---|---|
| 未聚焦 | handle.value.current |
服务端权威回显 |
| 聚焦中 | 本地文本 draft | 保留 1.、-、空串等中间态 |
必须如此的原因:App.tsx:197 在每次预览结算时 setManifest(response.handles) 整体替换 manifest。受控输入若直接绑定 value.current,键入 1. 触发的防抖预览返回后会把输入框冲成 1,小数点消失。
失焦即清 draft。此时 value.current 必然等于刚提交的值——因为 direct-edit-solver.js:136 的 numericValue() 直接回显约束里的数字,服务端不改写。故不存在"请求值 vs 求解值"的双显示需求。
该结论依赖 solver 当前行为。若日后改为回写求解结果,本节规则失效,需同步重审。
gesture 边界
gestureIdentity() 是懒创建的 operationId 单例,commitGesture() 释放它。它抽象的是"一段有始有终的操作",与指针无绑定关系,因此可原样承载键盘输入:
| 阶段 | 拖拽 | 输入框 | 动作 |
|---|---|---|---|
| 开始 | pointerdown |
focus |
铸 operationId |
| 进行 | pointermove |
onChange |
requester.schedule(),不 commit |
| 结束 | pointerup |
blur / Enter |
requester.flush() + commitGesture() |
| 放弃 | — | Escape |
回滚显示值 + requester.cancel() |
EditSession 与 gestureIdentity() 无需改动。输入 1.53 产生一步 undo,而非四步。
滑杆(若实现)的 pointerdown/up 天然落在此表内,不引入新分支。
保存路径:saveDirectEdits() 必须在入口强制结算未闭合的 gesture。DOM 中 blur 先于 click 触发,直接点"保存"能赶上,但该顺序过于脆弱,不作为正确性依赖。
区间的单位分层
父 design.md 的坐标分层表规定持久化层只有米与归一化 station。显示层不受该表约束。
| 层 | 单位 |
|---|---|
| 持久化 / 传输 | station (0..1) |
| 面板显示与输入 | 米(station × roadLengthMeters) |
只在用户实际编辑时换算,不在每次渲染时做 米→station→米 的往返,否则四舍五入会让数字自行漂移。roadLengthMeters 取自 IntervalRangeHandle,与 range 手柄同源。
区间由整条道路共享(rangeDraftFor 重锚该路全部约束),故在面板中每条路一行,不随手柄重复。
面板可表达而拖拽不能表达的操作
value.current 在无约束时回落基线(外缘偏移基线为 0),因此"未修改"与"显式设为 0"数值完全相同。handle.constraintId 仅在约束存在时出现,客户端据此区分。
由此得到一个拖拽结构上无法提供的能力:删除约束。拖拽只能设值,不能移除。面板每行提供"重置",删除该约束并使该行回到未修改态。
这是参数面板的实质增量,而非拖拽的镜像显示。
渲染性能
handleDragEvent 每次 mousemove 触发,而 App.tsx 是单个 974 行组件。拖拽值回流面板必须经 rAF 节流,不得直接 setState。
节流有效性需在扩大面板规模前验证——手柄当前仅 5~6 个,问题不会自行显现。
边界
- 面板不得成为第二套几何算法或第二个值的真相来源。范围、位置、
affects、可编辑性一律只来自服务端 manifest。 - 面板只呈现主地图拥有的 kind。路口 shape 三 kind 仍属
JunctionTools;保留区内手柄呈禁用态并显示disabledReason。 - 不新增约束 kind,不改动求解器。
已知缺口
服务端 applyConstraint 只校验 Number.isFinite 与非负,不校验 manifest 的 min/max。今日范围仅由客户端 projectHandleValue 的夹值实际约束。
外缘偏移的范围随道路宽度浮动(±Math.max(0.1, width * 0.45)),因此保存时合法的值可能在后续几何变化后越界。此类越界发生在保存之后的求解期,客户端结构上无法拦截。
父 design.md 已为 boundaryIndex 定义同类规则——"重放时若车道数变化导致越界,该约束转 stale,不做近似映射"——数值范围越界应同等处理。
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
右侧工作台信息架构(2026-09-01)
右栏是操作面板而非信息流。顶部固定呈现当前选择对象、其道路方向和修改状态;下方 采用单主展开区的手风琴,避免所有表单在初始状态占满地图旁的空间。
| 分段 | 内容 | 展开规则 | 写入语义 |
|---|---|---|---|
| 道路 | 基础道路覆盖、直接编辑参数 | 选中道路时默认展开 | override 暂存;直接编辑 preview/session |
| 元素 | 车道箭头、标线、信号灯 | 选择相应地图元素时自动展开 | 箭头/标线暂存;信号灯即时 API |
| 连接 | 路口连接、行驶动作、手工候选 | 默认收起 | override 暂存 |
| 高级 | 复杂路口候选、技术 JSON | 始终默认收起 | 候选沿用现有调用 |
每个分段使用受控 React 状态,而非依赖原生 <details> 的不可观察状态;这让地图选中
事件可以可靠地展开相应段,且移动端与桌面端保持同一状态模型。分段标题显示摘要
(如参数修改数、所选第几车道、连接数量),但不复制任何几何或约束值。
车道箭头在元素段显示 maneuver 选择、距路口端的米数读数和有限数值输入。数值输入与
拖曳都写同一 lane-maneuver.placementDistanceMeters;客户端只限制为有限非负值,控制
设施与端点安全位置仍由正式编译的 nearestSafeTurnArrowPlacement() 权威裁决。
为避免继续膨胀 App.tsx,右栏容器、对象摘要、手风琴、道路/连接/元素分段应迁入
workbench/client/src/components/。现有 ParameterPanel 保持其 manifest 值所有权和
DOM 直写性能策略,只作为“道路”分段的内容,不被重写为另一条输入链路。