CUI 可配置用户界面
CUI（Configurable User Interface）把工具栏、菜单、快捷键和部分窗口区域建模为元数据， 让管理员通过配置叠加界面，而不是直接修改 Aras 客户端源文件。
适用版本
CUI 在 Aras Innovator 11.0 的早期 Service Pack 已用于工具栏、菜单和快捷键； Release 12 又把它扩展到 TOC、sidebars、toolbars、context menus 和 accordion sections 等更多标准客户端区域。 本文示例以 R12 与 R33/R34 官方 CUI 指南为基线。Location 和 OOTB Item 名称必须在目标 Release 中核对。
1. CUI 解决什么问题
适合使用 CUI 的需求包括：
- 为某个 ItemType 添加或移除命令。
- 为特定 Identity 显示按钮或菜单。
- 在搜索页与 Item 详情页配置不同命令条。
- 配置键盘快捷键。
- 调整 TOC、侧栏或其他受 CUI 管理的区域。
CUI 不是完整授权系统。隐藏 Delete 按钮不会撤销 Delete 权限；安全规则仍应由 Permission、生命周期和服务器 Method 实现。
2. 元数据层次
2.1 Presentation Configuration
Presentation Configuration 是界面配置入口，可用于全局范围或 ItemType 范围。 先决定配置属于整个客户端，还是只属于某个业务 ItemType。
2.2 Section
Window Section 与 Command Bar Section 描述“在哪个界面区域组合控件”。 Section 通过 Location 对应标准客户端中的插槽。
2.3 Item 与 Control
Command Bar Item 表示按钮、菜单项、快捷键等命令元素；Window Control 表示窗口区域中的控件。 具体子类型和可用属性以目标版本 CUI 指南为准。
3. 常用属性
官方 CUI 指南把以下字段列为常见 CUI 属性：
| 属性 | 作用 | 验证方式 |
|---|---|---|
Location | 指定 Section 或 Item 所属界面位置 | 在目标 Release 查现有配置，不凭记忆输入 |
For Identity | 限制配置对哪些身份生效 | 用匹配与不匹配账号分别登录 |
For Classification | 限制配置适用的分类上下文 | 用不同分类 Item 打开同一视图 |
Sort Order | 控制同一区域内的显示顺序 | 用相邻且不同的值观察位置 |
当两个项目 Sort Order 相同时，不要写“按创建时间”或“按名称排序”。官方指南没有给出可依赖的跨版本稳定次序；应设置唯一、留有间隔的排序值。
4. Section 关系的四种 Action
Add、Remove、Replace、Clear All 是 CUI 关系的组合动作，不是四个全局运行模式。
| Action | 含义 | 典型用途 |
|---|---|---|
Add | 把一个 Item 加入该 Section | 增加自定义按钮 |
Remove | 从解析结果移除目标 Item | 对特定 Identity 隐藏 OOTB 命令 |
Replace | 用新 Item 替换匹配的原 Item | 保留位置但改变命令行为 |
Clear All | 清空该 Section 之前解析出的内容 | 完全接管一个受控区域 |
谨慎使用 Clear All
它可能一起移除保存、刷新等标准命令。先在隔离 ItemType 和测试 Identity 上验证，再决定是否使用。
5. Location 必须从目标版本取得
官方工具栏示例使用过如下 Location：
ItemView.ItemCommandBar：Item 视图命令条。SearchView.CommandBar：搜索视图命令条。
这并不代表所有版本、所有页面只有这两个值。正确做法是：
- 在目标 Release 的 CUI 管理界面搜索现有 Section。
- 找到与目标页面对应的 OOTB Presentation Configuration。
- 记录 Location、Section 名称和 Item 名称。
- 再创建自己的叠加配置。
不要使用未经当前环境验证的 MainWindowToolbar、RelationshipsGrid、 SearchGridCardInitialization 等字符串作为“官方固定 Location”。
6. 配置一个 ItemType 命令
以下流程只描述元数据步骤，Click Method 的客户端 API 应在目标 Release Programmer's Guide 中另行核验。
6.1 创建测试对象
- 准备测试 ItemType
z_Cui_Test。 - 创建测试 Identity
z_Cui_User。 - 确认该用户可以读取测试 Item，但没有管理员身份。
6.2 创建 Command Bar Item
- 在 CUI 管理区域创建目标类型的 Command Bar Item。
- 使用稳定名称，例如
z_cui_test_button。 - Label 写成“CUI 验证”。
- 如需执行逻辑，绑定已经在目标 Release 验证过的客户端 Method。
- 将 For Identity 设置为
z_Cui_User。
6.3 添加到 Section
- 打开或建立
z_Cui_Test的 Presentation Configuration。 - 选择目标
ItemView.ItemCommandBarSection。 - 新增关系，Action 设为
Add。 - 选择刚创建的 Command Bar Item。
- 设置一个未与现有项目冲突的 Sort Order。
- 保存并重新登录测试账号。
7. 可复现实验：验证解析结果
7.1 Identity 验证
- 用
z_Cui_User登录并打开测试 Item。 - 记录按钮是否出现、所在位置与标签。
- 用另一个不属于该 Identity 的账号登录。
- 确认按钮不出现。
7.2 Remove 验证
- 在目标环境记录一个无业务风险的 OOTB Command Bar Item 名称。
- 为测试 Identity 建立
Remove关系。 - 重新登录并确认只对该 Identity 移除。
- 删除测试关系后再次登录，确认 OOTB Item 恢复。
7.3 Classification 验证
- 为测试 ItemType 准备两个分类 Item。
- 把 Command Bar Item 的 For Classification 限制到其中一个分类。
- 分别打开两个 Item，记录解析差异。
7.4 权限反证
- 通过 CUI 隐藏某个敏感命令。
- 仍使用 AML/REST 尝试对应服务器动作。
- 若服务器允许，说明安全规则尚未配置；补充 Permission 或服务器校验。
证据应包括账号 Identity、Item 分类、Presentation Configuration ID、Section、Item 与截图。
8. 调试顺序
按钮未出现时，按以下顺序排查：
- 是否修改了正确的 Presentation Configuration。
- Location 是否来自当前 Release 的现有配置。
- Section 关系 Action 是否正确。
- For Identity 是否与用户成员关系匹配。
- For Classification 是否与当前 Item 匹配。
- Item 是否被另一个 Remove、Replace 或 Clear All 覆盖。
- 是否需要注销并重新登录以刷新客户端配置。
- Click Method 是否为客户端 Method，且其上下文符合调用位置。
先验证“是否显示”，再验证“点击行为”，可以快速区分 CUI 解析问题与 Method 问题。
9. 常见错误
把 CUI 写成 R12 才引入
CUI 在 11.0 的早期 SP 已出现，R12 是显著扩展覆盖范围。
猜 Location 字符串
Location 是版本和界面相关元数据。应从官方指南和目标数据库现有配置取值。
依赖相同 Sort Order 的隐式顺序
没有可靠的官方排序保证。给自定义项目使用唯一排序值。
使用私有全局函数作为通用 API
类似 top.aras.uiNewItem(...) 的历史写法不应作为跨版本稳定 CUI 示例。 客户端 Method 应按目标 Release API 文档实现。
把按钮隐藏当作权限控制
CUI 负责呈现；服务器 Permission 与 Method 才负责安全边界。
10. 官方依据
- Aras Innovator 12 — CUI Administrator Guide
- Common CUI Properties — Release 33
- Toolbars — Release 33
- R34 CUI Administrator Guide
文档最后核验：2026-08-13。