Dynamics 365定制:在實體的列表界面添加按鈕

我是微軟Dynamics 365 & Power Platform方面的工程師羅勇，也是2015年7月到2018年6月連續三年Dynamics CRM/Business Solutions方面的微軟最有價值專家(Microsoft MVP)，歡迎關注我的微信公眾號 MSFTDynamics365erLuoYong ，回復417或者20200707可方便獲取本文，同時可以在第一間得到我發布的最新博文信息，follow me!

之前我的文章 Dynamics CRM 客戶端程序開發：在實體的列表界面添加按鈕 講述了實體列表界面添加按鈕，那是六年前(2014年)的事情了。

是時候刷新了，官方文檔請參考：Customize commands and the ribbon .

一般使用 RIBBON WORKBENCH 來定制命令欄(command bar)，它是一個托管解決方案，導入Dynamics 365/Power Apps Model-Driven App中即可使用。

一般用一個專門的解決方案，比如我這里是使用RibbonEditor來定制命令欄，僅僅添加需要的組件，保持組件盡可能少來加快定制后的發布。組建多容易報錯，而且發布很慢。

我這里的例子是為 Order 實體在列表界面添加一個按鈕。

將實體 Order 添加到我專門用來定制的解決方案 RibbonEditor，只需要添加實體的元數據即可，不需要添加所有資產，也就是保持【Include entity metadata】選中，而取消選中 【Add All Assets】. 點擊【Finish】按鈕。

 

在新界面中選擇【No, do not include required components】選項后點擊【OK】按鈕，然后發布該解決方案。

  

登錄Dynamics 365后導航到 Advanced Settings > Settings > Solutions，點擊 RIBBON WORKBENCH 2016.

 

 選擇解決方案后點擊【OK】按鈕。

 

從Toolbox 拉動一個BOTTON到Home中的某個位置，我這里放在DELETE按鈕后，然后我修改下按鈕的Id屬性，在設置Label為 Approve 。

 

 然后點擊 + 號增加一個COMMAND。

 

 

一般我會更改下COMMAND的Id，然后增加一個Action，一般我們是添加 JavaScript Action。

 

 

我這里使用的Library是 $webresource:ly_/scripts/order/order_ribbon.js ，Function Name是 LuoYong.OrderRibbon.ApproveHomeAction ，然后我增加傳遞參數，點擊 【Add Parameter】，我這里選擇 【CRM Parameter】。

 

有哪些CRM Parameter可以傳遞呢？請參考官方文檔 Pass data from a page as a parameter to Ribbon Actions 。我這里傳遞 SelectedControlSelectedItemReferences 。

 

 至於Enable Rule和Display Rule可以后面設置（補充，若要選擇記錄后也顯示按鈕不能忽略后面添加的 SelectionCountRule 這個Enable Rule設置，見后文說明），記得一定要點擊新增按鈕，設置其Command屬性，否則按鈕不會顯示。

 

 

 

然后點擊 【Publish】按鈕，耐心等待發布完成。

 

然后去看下真的有按鈕了。但是選中任何一行記錄后這個按鈕就消失了。這是為什么呢？原來啊，這是UCI的一個變化，請參考官方文檔 Button in command bar does not appear after grid item selection 。

 

消失了咋回事呢，我們可以根據 Ribbon Troubleshooting Guide 去看下原因。在展示頁面的url的最后加上 &ribbondebug=true ，然后就會看到有個按鈕叫【Command checker】，點它。 不過這個檢測結果是應該顯示，但是沒有顯示。好尷尬。

 

如何解決呢？我找到的自定義解決方法如下，為這個按鈕添加有個Enable Rule. 官方的說法是增加一個名稱為 <EnableRule Id="Mscrm.AnySelection" /> 的Enable rule.

 

一般我會更改下這個Enable Rule的Id。我這里點擊 【Add Step】添加一個SelectionCountRule 。

 

 我這里設置如下(AppliesTo選擇SelectedEntity，Minimum輸入0)，也就是要求選擇了記錄或或者沒有選擇記錄都可以顯示。

 

 如果要求用戶對當前實體有Write權限才顯示按鈕的話，還要為按鈕添加一個類似如下的 Display Rule.

 

我用Command Check展示下我設置的兩個有關按鈕是否顯示的rule如下：

 

我這個按鈕使用了非常簡單的代碼如下：

"use strict";
var LuoYong = window.LuoYong || {};
LuoYong.OrderRibbon = LuoYong.OrderRibbon || {};
(function () {
    this.ApproveHomeAction = function (selectedControlSelectedItemReferences) {
        console.log(selectedControlSelectedItemReferences);
    };
}).call(LuoYong.OrderRibbon);

 

選擇記錄后傳遞過來的信息如下，可以知道是選擇記錄后傳遞過來的數組，每個元素包括了Id, Name, TypeName 等很有用的信息。

 

如果你想操作完成后刷新當前的列表怎么辦？向你執行的方法傳遞 SelectedControl這個CRM Parameter，在代碼中調用這個傳遞過來的SelectedControl的refresh() 方法即可。

如果你想獲得選中記錄的某個字段值怎么辦？可以類似這樣：

    this.recaluculateAction = function (selectedControl) {
        var selectedRows = selectedControl.getGrid().getSelectedRows();
        console.log("共選擇了" + selectedRows.getLength() + "條記錄!");
        if (selectedRows.getLength() === 0) {
            Xrm.Navigation.openErrorDialog({ message: "Please select at least one queue item!" });
        }
        else {
            selectedRows.forEach(function (row, i) {
                console.log(row.getData().entity.attributes.get("ly_name").getValue());
            });
            //獲得選中的第一條記錄某個字段的值
            var itemCode = selectedRows.get(0).getData().entity.attributes.get("ly_name").getValue();
        }
    }