InspectorPanel

何时用

设计工具 / 低代码搭建器里与选中元素双向绑定的右侧属性面板：把一组属性描述成 schema，面板按 kind 派生控件、按 key 读值、按 key 回吐。

不是「表单」：提交语义、校验、字段依赖请用 Form / ProForm；单个属性的编辑控件直接用 Slider / ColorPicker / Segmented，不必套面板。内置的 5 类预设只是默认值，业务属性（权重、跳转方式、置顶）同样可以用它，见「自定义 schema」示例。

导入

Props

字段类型（InspectorField 判别联合，按 kind 收窄）：

公共字段：key （属性路径，同时是回吐的 path）· `label` （可见标签 + 控件 aria-label）· hint? · disabled?。

Events

回吐值形态由字段自己决定，不看输入形态：unit 有值回吐 "12px" 字符串，无 unit 回吐数字 12；数字框清空回吐 null（= 删除该属性，不是 0）；token 色块回吐该 token 的 value，没写 value 就回吐 var(--token)。

无障碍

• 每个控件都带 aria-label（取字段 label）；spacing 四个框各自是「内边距 上 / 右 / 下 / 左」，不会四个同名。
• length 的滑杆与数字框是同一属性的两种输入方式，共用同一可访问名（滑杆经 aria-labelledby 指向可见标签），角色不同所以读屏可区分。
• 链接锁定钮用 aria-pressed 表达开关态，不是靠颜色。
• token 色块的无障碍名取 tokenSource[].label（缺省回退到 token），不是 var(--color-x) 变量串——读屏念的是「主色」而不是一串变量名。色板下方那行 token 名是给视觉用户的当前值读数，不是无障碍兜底。
• 分类折叠走 Collapsible，aria-expanded 由它维护；键盘可达。
• 混合值不靠灰色暗示：文本/数字类走 placeholder，开关/枚举旁边有可读文字，读屏能听见。

禁忌 / 坑

• `onChange` 会在同一 tick 连发多次（链接锁定的 spacing 是 4 次）。消费方必须用函数式更新 setState((prev) => …)，写成 setState({ ...style, [path]: value }) 会让后三次覆盖前三次，表现为「只有最后一边生效」。嫌麻烦就传 onBatchChange 一次拿全。
• commitMode 覆盖滑杆、输入框与色块弹出的 ColorPicker 三者。commit 模式下取色器松手 / 失焦 / 回车才回吐，拖动中的每帧值只留在面板内部（取色器此时是非受控的，外部 props 变了才会重新同步）。
• tokenSource[].token 必须带 `color-` 前缀（color-primary 而不是 primary）。Tailwind v4 @theme 的真名带前缀，写成裸名色板会画不出颜色也不报错。
• 混合值哨兵是 Symbol.for("hulian.inspector.mixed")，不能 JSON 序列化。属性表要过一遍网络/存储时，在边界上把它转成自己的标记再转回来。
• 数字框清空回吐 null 不是 0。消费方要区分「没设置」和「设成 0」，null 应当删除该属性而不是写 0。
• 面板不持有业务值：props 不回写，控件就不会动（commit 模式的输入草稿与拖动中的滑块除外）。它是受控组件，不是自带状态的编辑器。
• 面板自身的文案（title / 空态 / mixed / linkSides / 四边名 / 两个色值控件名）走 ConfigProvider 的 locale，外层包 <ConfigProvider locale={enUS}> 即变英文。优先级是 labels / title / emptyText prop > locale > 内置中文兜底。
• 内置预设的字段 `label` 仍是中文，不在 locale 覆盖范围内——它们属于 sections 数据而不是面板本身。要整屏英文请自带 sections。

相关

Form · ProForm · ColorPicker · ColorSwatchPicker · Slider · Segmented · Collapsible · Flow