﻿# 控件与布局

子插件声明功能与语义布局，框架负责统一字体、字重、颜色、圆角、缩放及排版。不要另建旧窗口，也不要自行调整不同 DPI 的控件坐标。

## 公共控件

| 用途 | 控件类型 |
| --- | --- |
| 操作与状态 | button、toggle-button、hyperlink、progress |
| 数字与文字 | number、slider、angle、text、label、combobox |
| 选项 | checkbox、choice、radio、segmented-choice |
| 颜色 | color、color4 |
| 数据与预览 | list、table、tree、gallery、image、image-action |
| 高级编辑 | curve、menu |

共 24 种公共控件。字段支持 number、boolean、check_state、enum、text、color、color4、string_list、curve、resource。控件的完整属性以[声明格式](reference/plugin-schema.json)为准。

编辑器边界、带注释配置、组合参考与安全要求见[编辑配置与安全](editing.md)。颜色按钮、split_action、动态 group 标题、列表状态详情属于现有类型的组合/展示能力，不新增重复控件类型。

## 只读结果如何显示

`read_only` 不是所有控件的通用属性，当前仅支持 `text`、`list`、`table`。不要给 `number`、`slider` 或 `angle` 添加 `read_only`，即使只需要显示数字，也会被语义校验拒绝。

仅展示计算结果时，可用 `text` 字段绑定 `text` 控件并设置 `read_only: true`，命令用 `SetText` 更新显示。需要继续计算时保留独立的 number 业务字段，另外返回格式化展示文本；不要为了显示结果把可编辑数值框冒充只读，也不要把 text 控件绑定到 number 字段。完整声明先通过 Schema，再由实际工具箱检查各控件的语义限制。

## 已确定的排版规则

- 默认逻辑尺寸：分类区宽 50、功能展开区宽约 210、普通按钮/输入框/下拉框高 22、卷展标题高 25。用户可统一自定义，子插件不强制覆盖。
- 分类、卷展、内部功能形成层级。功能文字及数字同属三级；帮助问号、箭头、辅助提示和分组小标题属于四级。框线内部正文不能降成辅助亮度。
- 相关且空间够的短标签和输入应同行；两个短参数可一排。复选项按文字长度成组对齐，避免为了等宽制造大面积留白。
- 使用 row/group/disclosure/tabs/vector/file/object_picker/editable/separator 等公共语义布局，不使用绝对坐标。
- 分组标题在框线上，避免独占大行。分组内容内缩留白，组间距一致，外框与相邻无框控件对齐。
- 列表仍用列表，预览仍用预览，不能为接入方便统一改成下拉框。
- 动态 `list` 可声明 `"continuous": true`，在同一列表内连续浏览完整过滤结果，无需上一页、下一页按钮。框架协商 `list.continuous` 能力；数据源最多 4096 项，单次选择仍最多 128 项。超限必须明确拒绝，不静默截断。滚轮或中键拖动只滚动起点所属列表；跨出列表、到达边界也不接管外层卷展栏。未声明时保留原分页行为，图库分页不受影响。
- 预览名称和详情进入悬浮提示；需要兼容/降级标记时使用可识别角标。显示、选择、激活与右击分别声明。
- 扩展区使用统一折叠区域和箭头。具体业务哪些功能默认隐藏，由原需求决定，AI 不自行移动常用操作。
- 命令消息交给框架统一输出，不在每个卷展添加独占的状态提示行。
- 标题帮助使用 tutorial 或帮助字段；不把问号当作普通功能按钮单独配色。

## 转换旧 UI 时

MAXScript、.NET 或 ActiveX 的旧控件名称不等于可直接嵌入。先提取值、事件、资源、单位和对象生命周期，再映射为公共语义。任意旧窗口、所有旧属性逐一原样嵌入不属于公共接口承诺；无法对应的行为必须写入差异清单。

## 预览状态与多分类

`button` 和 `image-action` 可用 `selected_when` 绑定布尔字段，表示已选中的项目；不要把选中态写成按钮名称。`image-action` 可声明 `badge` 短标记及 `preview_shape`，用于兼容复制槽等需要始终可辨认的预览。

同一个业务模块的多个卷展可分别放入不同分类：在 `placement.json` 的可选 `panels` 对象中，以面板 ID 为键分别指定 `category` 和 `order`。普通单分类插件仍只填写顶层两个字段。



### 列表右键菜单与多选

公开 list 可声明 `context_menu`，项目沿用 menu 的 id/label/command/enabled/checked/items 格式，必须为同步命令；框架协商 `list.context-menu`。此属性与只读列表、secondary_command 互斥。左键、Ctrl/Shift 多选和双击激活保持独立；右击已选行不丢多选，未选行改选该行。菜单取消不执行业务；中键和滚轮不分配业务命令。框架在惰性初始化后重新验证可用状态和点击项，拒绝过期/禁用项后下一步仍可正常操作。作者通过 Request.Invocation.ItemId 取得点击项，通过 string_list 参数取得当前多选，不把菜单项编号混入资源选中值。

资源列表推荐菜单为复制名称、超级搜索、指定文件夹搜索、定位物体。所选搜索不得清掉未选条目的候选，不自动应用路径。定位跳过过期引用/已删除对象，找不到时保留场景当前选择并接入胶囊说明；不改变相机视角、不自动解冻或显示隐藏对象。

框架组合视图统一映射菜单和嵌套右键菜单的命令身份。作者无需自行添加前缀；菜单数据中的资源项目 ID 保持业务语义，不应手工替换为控件 ID。新菜单或输入事件必须验收实际组合窗口的事件路径，直接调用命令只能证明业务逻辑。

快照含只读展示信息，不能直接作为重建补丁。框架按控件类型恢复已提交、允许写入的状态；错误恢复不会重放业务命令。拒绝过期输入、空选择或已删除对象后，应可立即执行下一次有效操作。


### 色带滑块

水平 `slider` 可声明可选 `color_scale`：`hue`、`saturation`、`brightness`、`contrast` 或 `temperature`。它只绘制框架提供的方向色带，不改变字段范围、数值或业务算法；不是最终渲染颜色预览。其他控件和竖向滑块不接受此属性，未知值会被拒绝，不允许任意 CSS。色带与数值输入绑定同一字段，色带外的精确输入范围仍由字段合同决定。

数值范围必须表达业务限制，不得为适配输入框宽度压小最大值。一般空间长度可允许大尺度手动输入；数量、像素、百分比和几何容差继续使用各自的有效范围。框架悬浮帮助显示范围，编辑区和箭头区域独立计宽，按实际字体与缩放后的可用宽度判断是否同行。超过可用空间应换行，不能隐藏数值或强制缩小字体。
