8.9 KiB
8.9 KiB
参数面板与数值双向绑定
目标
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
地图直接操纵保留,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
已确认的事实
以下均为读代码核实,不是推断:
App.tsx:206的draftFor(handle, value)已经是纯函数(手柄, 数字) → 草稿。拖拽只是产生这个数字的一种方式;输入框可以复用同一个入口。EditHandle.value是{ current, min, max, unit: 'meter' }——取值范围服务端早已下发,客户端不需要新增来源。direct-edit-solver.js:136的numericValue(constraint, key, fallback)直接从约束读值,无约束时回落基线。服务端从不改写用户输入的数字;值非法时发阻塞诊断(direct-edit-invalid-value)拒绝,不做静默替换。因此不存在"请求值 vs 求解值"两个数字。App.tsx:197每次预览结算都setManifest(response.handles)整体替换 manifest,value.current随之刷新。受控输入若直接绑定它,输入中间态(1.、-、空串)会被冲掉。projection.ts:60的projectHandleValue把拖拽值夹到[min, max],ghost.show()与handlePositionFor()都按夹后的值绘制。拖拽越界时手柄停在极限、光标继续移动。- 服务端
applyConstraint(direct-edit-solver.js:302/312/322附近)只校验Number.isFinite与非负,未校验 manifest 的min/max。范围目前是纯客户端概念。 - 外缘偏移的范围随道路宽度浮动(
±Math.max(0.1, width * 0.45));步行带固定0..8;角部圆角固定0.5..30。 gestureIdentity()懒创建 operationId,commitGesture()释放它。一次 gesture =EditSession.commit()一次 = 一步 undo。该机制与指针无绑定关系。handle.constraintId仅在约束存在时出现,因此客户端能区分"未修改(基线回落)"与"显式设为该值"。- 区间由整条道路共享:
rangeDraftFor会把该路上所有约束一起重锚。IntervalRangeHandle同时携带station与roadLengthMeters。 - 同一条路可有多个
road-lane-divider手柄,靠boundaryIndex区分。 direct-edit-solver.js写profile.interval(290、472 行),但compileGeometry()不读它——native-road.js中interval的唯一命中是方向箭头间距,与此无关。每次直接编辑实际作用于整条道路。 因此flag.ts:46的intervalEditingSupported为false,range 手柄被隐藏。- 当前没有任何参数面板。与手柄相关的 UI 仅
App.tsx:404状态栏一句手柄 ${n} 个。 handleDragEvent每次 mousemove 触发;App.tsx是单个 974 行组件。
范围
1. 面板与读取
- 选中道路后,面板按手柄列出可编辑参数:中文名、当前值、单位、合法范围。
- 多个
road-lane-divider分别成行,用boundaryIndex标识,不按 kind 去重。 - 影响区间每条路一行(不是每个手柄一行),以米显示,
station仍是唯一存储真相。 受intervalEditingSupported门控:该开关当前为false,故本任务不渲染区间行。 换算与显示逻辑仍按第 5 节实现并单测,随开关翻转一并生效。 - 每行标记该参数是否已被显式修改(依据
handle.constraintId是否存在)。 - 不可编辑手柄(落在路口保留区)在面板中呈禁用态并显示
disabledReason。
2. 拖拽 → 数字
- 拖拽过程中面板数值实时跟随,与地图 ghost 同步。
- 高频更新经 rAF 节流,不得每次 mousemove 触发整个 App 重渲染。
3. 数字 → 图形
- 输入框修改值时走与拖拽相同的
draftFor→PreviewRequester链路,含 80ms 防抖与previewSeq仲裁。 - gesture 边界:
focus对应pointerdown(铸 operationId),blur/Enter对应pointerup(commitGesture)。输入1.53只产生一步 undo。 Escape回滚到上一个有效值并cancel()在途请求。- 聚焦期间输入框显示本地文本,失焦后跟随
value.current。中间态不被预览响应冲掉。 saveDirectEdits()入口先强制结算未闭合的 gesture,不依赖 blur 与 click 的触发顺序。
4. 范围处理
- 拖拽与滑杆维持夹值(
projectHandleValue不变)。 - 数值输入不夹值:越界时标记非法、不发预览、不进 undo 栈,保留最后一个有效预览。
- 范围提示中的极值可一键填入。
5. 重置
- 每行提供"重置",删除该约束回到基线。这是拖拽无法表达的操作——拖拽只能设值,不能移除约束。
明确不做
- 不移除、不削弱地图上的拖拽手柄。
- 不新增约束 kind,不改动求解器几何逻辑。
- 不补服务端
min/max校验(见「已知缺口」,另立任务)。 - 不做参数的批量编辑、复制粘贴、跨道路应用。
- 不动
JunctionTools的所有权边界;面板只呈现主地图拥有的 kind。 - 不同步遗留
workbench/client/app.js。
验收标准
- 选中道路后面板列出全部可编辑参数;多条车道分隔各自成行且可独立修改。
- 拖拽手柄时面板数值实时跟随;拖拽期间 React 重渲染次数经 rAF 收敛(非每 mousemove 一次)。
- 输入框改值后地图预览更新,与拖到同一数值的结果一致。
- 输入
1.53后按 Ctrl+Z 一次即回到修改前状态。 - 输入过程中(如已键入
1.)到达的预览响应不会改写输入框内容。 - 输入越界值:字段标红、不发预览请求(可由网络面板证明)、保留上一个有效预览、blur 后不产生 undo 步骤。
- 点击范围提示中的极值可一键填入并正常提交。
- 拖拽越界时手柄停在极限位置,行为与改动前一致。
- 未修改参数与显式设为基线值的参数在面板上可区分;"重置"能删除约束并使该行回到未修改态。
- 影响区间的米↔station 换算函数经单测覆盖,往返无累积漂移。(区间行本身受
intervalEditingSupported门控,当前不渲染。) - 输入未失焦时直接点"保存",该次修改被正确持久化。
- 路口保留区内的手柄在面板中禁用并显示原因。
npm run format:check、npm run test、npm run test:client、npm run test:client:unit、npm run build全绿。
风险与门槛
- 面板不得成为第二套几何或第二个值的真相来源。所有范围、位置、影响对象仍只来自服务端 manifest。
value.current是请求值的回显而非求解值。若后续 solver 改成回写求解结果,第 11 条的显示规则失效,必须同步重审。- 外缘偏移的
min/max随道路宽度浮动,因此"当前合法"不等于"永远合法"。客户端校验只能覆盖输入当下。 - 拖拽回流若实现为直接
setState,会逐帧重渲染 974 行的App。必须先确认节流有效再扩大面板规模。
已知缺口(不在本任务内)
服务端只校验 finite/非负,不校验 manifest 的 min/max;而外缘偏移范围随道路宽度浮动,意味着保存时合法的值可能在几何变化后越界。这类越界客户端结构上无法拦截——它发生在保存之后的求解期。
design.md 已为 boundaryIndex 定义了同类规则("重放时若车道数变化导致越界,该约束转 stale"),数值范围越界应当同等处理。属重放正确性,独立成任务。
右侧工作台扩展(2026-09-01)
当前右侧栏将道路基础覆盖、直接编辑参数、路口连接、车道转向箭头、标线样式、 原生信号灯、复杂路口候选和技术 JSON 直接按顺序堆叠,缺少所选对象摘要、明确的 编辑上下文和一致的表单层级。用户确认本轮应覆盖全部既有编辑器,而非只处理道路 参数或车道箭头。
拟纳入范围:
- 统一右侧栏的对象摘要、未保存/即时保存状态和表单布局。
- 重新组织道路、元素、连接、调试/技术详情中的全部既有表单与信息展示。
- 为车道转向箭头补足距路口位置的可读数与精确输入,继续复用
placementDistanceMeters覆盖和既有拖曳行为。 - 保持各写入语义:普通 override 继续暂存并经保存/重新生成生效;信号灯继续走 现有即时 API;直接编辑继续走 manifest/preview/session 链路。
已决 UX:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。 所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。