入门与设置 / DAYU TOOLBOX 5.0
控件与布局
查询标准控件、分组、同行排版及界面布局规则。
子插件声明功能与语义布局,框架负责统一字体、字重、颜色、圆角、缩放及排版。不要另建旧窗口,也不要自行调整不同 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。控件的完整属性以声明格式为准。
编辑器边界、带注释配置、组合参考与安全要求见编辑配置与安全。颜色按钮、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。色带与数值输入绑定同一字段,色带外的精确输入范围仍由字段合同决定。
数值范围必须表达业务限制,不得为适配输入框宽度压小最大值。一般空间长度可允许大尺度手动输入;数量、像素、百分比和几何容差继续使用各自的有效范围。框架悬浮帮助显示范围,编辑区和箭头区域独立计宽,按实际字体与缩放后的可用宽度判断是否同行。超过可用空间应换行,不能隐藏数值或强制缩小字体。