# 参数面板与数值双向绑定 · 设计 > 父任务 `08-26-direct-manipulation-road-editor/design.md` 仍是约束模型、求解边界与 API 合约的权威定义。本文只补充**第二条输入通道**引入的规则,不改变其中任何一条。 ## 架构定位 本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层: ```text ┌─ 拖拽(连续)──→ 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`,不做近似映射"——数值范围越界应同等处理。 属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。