Dynamics 365 Ribbon按钮PrimaryControl参数内容及其他CRM参数咨询

关于PrimaryControl参数的内容范围 #

PrimaryControl没有固定的返回结构，其值完全由自定义按钮的部署位置决定，不存在除对应场景标准上下文外的额外隐藏内容：

• 当按钮部署在实体表单命令栏、表单内嵌入子网格位置时，传入参数为标准的表单上下文formContext对象，和表单脚本事件中获取的formContext用法完全一致，可直接调用getAttribute()、getControl()、data.entity等表单API操作记录数据，就是你示例代码中接收的对象。
• 当按钮部署在实体主页网格（列表视图）、关联视图网格、子网格批量选择场景时，传入参数为标准的网格上下文对象，可直接调用getSelectedRows()、getGrid()等网格API获取选中记录、视图信息。
• 当按钮部署在全局命令栏、仪表盘等未绑定具体实体记录的位置时，配置PrimaryControl会返回null，无法获取任何业务上下文。

除PrimaryControl外的常用内置CRM参数 #

所有内置参数均可以在Ribbon Workbench编辑JS Action时直接从参数下拉列表选择，按使用场景分类如下：

• 上下文识别类
  • SelectedControl：返回触发按钮的源控件上下文，和PrimaryControl的核心区别是，当表单内存在多个子网格时，该参数可以精准定位到点击按钮的具体子网格，不会混淆不同子网格的触发源。
  • PrimaryEntityTypeName：字符串类型，直接返回当前按钮绑定实体的逻辑名（如account、contact），不需要从上下文对象中二次解析。
  • FirstPrimaryItemId：字符串类型，单记录场景下（表单页、网格单选记录）直接返回当前操作记录的GUID，无需从上下文对象中取值。
  • PrimaryItemIds：字符串数组类型，网格多选场景下直接返回所有选中记录的GUID列表，不需要手动遍历网格选中行提取ID。
• 环境与用户信息类
  • OrgLcid：数字类型，返回当前组织的基础语言区域代码（如简体中文为2052、英文为1033），可直接用于按钮逻辑的多语言适配。
  • UserLcid：数字类型，返回当前登录用户个人设置中配置的语言区域代码。
  • OrgName：字符串类型，返回当前Dataverse/CRM组织的唯一标识名。
  • ServerUrl：字符串类型，返回当前环境的服务根地址，可直接用于拼接Web API请求路径。
• 命令控制类
  • CommandProperties：返回当前按钮命令的基础属性，包括触发源控件ID、触发事件类型，多用于按钮启用/禁用规则判断、弹窗触发逻辑适配。
  • CustomParameter：支持用户自定义配置静态参数值，同一个JS方法绑定多个不同位置的按钮时，可以传入不同的静态值区分触发源，无需重复编写多套逻辑。

配置参数时需要注意：JS函数的形参顺序必须和Ribbon Workbench中配置的参数传入顺序完全一致，否则会出现参数取值错位的问题。参考示例写法：

var APP = APP || {};
APP.GetValue = APP.GetValue || {
    GetCount: (recordId, formContext) => {
        // 直接使用传入的记录ID
        console.log("当前操作记录ID：", recordId);
        // 调用表单API取字段值
        const fieldValue = formContext.getAttribute("attribute_name").getValue();
        return fieldValue;
    }
}

内容的提问来源于stack exchange，提问作者Dev Dev