Grid 物件和方法 (用戶端參考)

 

發行︰ 2016年11月

適用於： Dynamics CRM 2015

使用新的事件和物件，在 Microsoft Dynamics CRM Online 2015 更新 1 可以透過表單的子格控制項執行更多功能。其他資訊：撰寫子格的指令碼

重要

如果是 Microsoft Dynamics CRM Online 組織，只有在組織已更新至 Dynamics CRM Online 2015 更新 1 時，才能使用此功能。 這項功能不適用於 Dynamics CRM (內部部署)。

本主題內容

• GridControl
  GridControl 的事件和方法：OnLoad 事件、addOnLoad、getEntityName、getGrid、getViewSelector 和 removeOnLoad。

• 格線
  GridControl.getGrid 方法所傳回的 Grid 的方法：getRows、getSelectedRows 和 getTotalRecordCount。

• GridRow
  **Grid.**getRows 和 **Grid.**getSelectedRows 方法所傳回的 GridRow 的 getData 方法。

• GridRowData
  **GridRow.**getData 方法所傳回的 GridRowData 的 getEntity 方法。

• GridEntity
  **GridRowData.**getEntity 方法所傳回的 GridEntity 的方法：getEntityName、getEntityReference、getId 和 getPrimaryAttributeValue。

• ViewSelector
  GridControl.getViewSelector 方法所傳回的 ViewSelector 的方法：getCurrentView、isVisible 和 setCurrentView。

GridControl

在 CRM Online 2015 更新 1 之前，子格控制項的唯一方法是 refresh。 當您知道子格控制項名稱時，您可以使用下列程式碼存取它，例如，存取預設客戶表單的 [連絡人] 子格。

var contactsSubgrid = Xrm.Page.getControl("Contacts");

提示

若要識別表單的子格控制項名稱，而不開啟表單編輯器，請參閱 使用瀏覽器開發人員工具 的資訊。

做為 Xrm.Page.ui 控制項，GridControl 也有所有標準控制項方法：getControlType、標籤 方法、getParent、可見 方法、setFocus 和 通知 方法，以及 refresh。 如需這些方法的詳細資訊，請參閱 Xrm.Page.ui 控制項 (用戶端參考)。

OnLoad 事件

新增事件處理常式至此事件，在子格重新整理時執行。 這包括使用者按一下欄標題排序值時。 使用 GridControl.addOnLoad 和 GridControl.removeOnLoad 方法來管理事件處理常式 (通常是在表單 Onload 事件中)。

addOnLoad

使用此方法新增事件處理常式至 GridControlOnLoad 事件。

**參數類型：**函數

範例： 將函數 myContactsGridOnloadFunction 新增至連絡人子格 OnLoad 事件。

var myContactsGridOnloadFunction = function () { console.log("Contacts Subgrid OnLoad occurred") };
Xrm.Page.getControl("Contacts").addOnLoad(myContactsGridOnloadFunction);

getEntityName

使用此方法取得在格線顯示的實體資料的邏輯名稱。

**傳回值類型：**字串

範例： 設定 opportunitySubgrids 變數為顯示商機記錄的子格控制項陣列。

var opportunitySubgrids = Xrm.Page.getControl(function (ctrl, i) {
 if (ctrl.getControlType() == "subgrid") {
  return (ctrl.getEntityName() == "opportunity");
 }
 else {
  return false;
 }
})

getGrid

使用此方法存取 GridControl 中的可用 格線。

**傳回值類型：**格線

範例： 設定 contactsSubgridGrid 變數為連絡人子格的格線。

var contactsSubgridGrid = Xrm.Page.getControl("Contacts").getGrid();

getViewSelector

使用此方法存取 GridControl 的可用 ViewSelector。

**傳回值類型：**ViewSelector

範例： 設定 contactsSubgridViewSelector 變數為連絡人子格的檢視表選取器。

var contactsSubgridViewSelector = Xrm.Page.getControl("Contacts").getViewSelector();

removeOnLoad

使用此方法從 GridControlOnLoad 事件 移除事件處理常式。

**參數類型：**函數

範例： 將函數 myContactsGridOnloadFunction 新增至連絡人子格 OnLoad 事件，然後移除它。

var myContactsGridOnloadFunction = function () { console.log("Contacts Subgrid OnLoad occurred") };
Xrm.Page.getControl("Contacts").addOnLoad(myContactsGridOnloadFunction);
Xrm.Page.getControl("Contacts").removeOnLoad(myContactsGridOnloadFunction);

格線

使用 Grid 方法存取方格中資料的相關資訊。Grid 是由 GridControl.getGrid 方法傳回。

getRows

傳回 Grid 中每個 GridRow 的集合。

**傳回值類型：**集合

範例： 設定 allRows 變數為連絡人子格中 GridRow 的集合。

var allRows = Xrm.Page.getControl("Contacts").getGrid().getRows();

備註：

如需用來存取集合中資料的方法的資訊，請參閱 集合 (用戶端參考)。

getSelectedRows

傳回 Grid 中每個選定 GridRow 的集合。

**傳回值類型：**集合

範例：以連絡人子格中選定列的實體參照填入 selectedEntityReferencesArray 變數。

//Get an array of entity references for all selected rows in the subgrid
var selectedEntityReferences = [];
var selectedRows = Xrm.Page.getControl("Contacts").getGrid().getSelectedRows();
selectedRows.forEach(function (selectedRow, i) {
 selectedEntityReferences.push(selectedRow.getData().getEntity().getEntityReference());
});

備註：

如需用來存取集合中資料的方法的資訊，請參閱 集合 (用戶端參考)。

getTotalRecordCount

在 Web 應用程式或 Dynamics CRM for Outlook 用戶端，在連線至伺服器時，此方法傳回符合檢視表的篩選準則的記錄總數，不限於顯示在單一頁面的數目。

當 Dynamics CRM for Outlook 用戶端未連線至伺服器時，此數字受限於使用者選取要離線的記錄。

對於 平板電腦專用 Microsoft Dynamics CRM 和 手機專用 Microsoft Dynamics CRM，這個方法將會傳回子格的記錄數目。

**傳回值類型：**數字

範例： 設定 filteredRecordCount 變數為符合檢視表的篩選準則的記錄總數。

var filteredRecordCount = Xrm.Page.getControl("Contacts").getGrid().getTotalRecordCount();

GridRow

使用 **GridRow.**getData 方法存取 GridRowData。GridRow 集合是由 **Grid.**getRows 和 **Grid.**getSelectedRows 方法傳回。

getData

傳回 GridRow 的 GridRowData。

**傳回值類型：**GridRowData

範例：以連絡人子格中所有列的 GridRowData 填入 allGridRowDataArray 變數。

var allGridRowData = [];
var rows = Xrm.Page.getControl("Contacts").getGrid().getRows();
rows.forEach(function (row, i) {
 allGridRowData.push(row.getData());
});

GridRowData

使用 **GridRowData.**getEntity 方法存取 GridEntity。GridRowData 是由 **GridRow.**getData 方法傳回。

getEntity

傳回 GridRowData 的 GridEntity。

**傳回值類型：**GridEntity

範例：以連絡人子格中所有列的 GridEntity 填入 allGridEntitiesArray 變數。

var allGridEntities = [];
var rows = Xrm.Page.getControl("Contacts").getGrid().getRows();
rows.forEach(function (row, i) {
 allGridEntities.push(row.getData().getEntity());
});

GridEntity

使用 GridEntity 方式存取列中特定記錄的資料。GridEntity 是由 **GridRowData.**getEntity 方法傳回。

getEntityName

傳回列中記錄的邏輯名稱。

**傳回值類型：**字串

**範例：**設定 firstEntityType 變數為連絡人子格的第一列的實體邏輯名稱的值。

var firstEntityType = Xrm.Page.getControl("Contacts").getGrid().getRows().get(0).getData().getEntity().getEntityName();
// firstEntityType == "contact"

getEntityReference

**傳回值類型：**查詢

**範例：**設定 firstEntityType 變數為連絡人子格的第一列的實體參照。

var firstEntityReference = Xrm.Page.getControl("Contacts").getGrid().getRows().get(0).getData().getEntity().getEntityReference();
// firstEntityReference.entityType == "contact"
// firstEntityReference.id == "{13CD16BD-3EC4-E411-80CF-00155DB58496}"
// firstEntityReference.name == "Rene Valdes (sample)"

備註：

此查詢有下列屬性：

名稱	類型	描述
entityType	字串	列中記錄的邏輯名稱。 相同資料由 GridEntity.getEntityName 方法傳回。
id	字串	列中記錄的 id。 相同資料由 GridEntity.getId 方法傳回。
名稱	字串	列中記錄的主要屬性值。 相同資料由 GridEntity.getPrimaryAttributeValue 方法傳回。

getId

傳回列中記錄的 id。

**傳回值類型：**字串

**範例：**設定 firstEntityId 變數為連絡人子格的第一列的記錄 id 值。

var firstEntityId = Xrm.Page.getControl("Contacts").getGrid().getRows().get(0).getData().getEntity().getId();
// firstEntityId == "{13CD16BD-3EC4-E411-80CF-00155DB58496}"

getPrimaryAttributeValue

傳回列中記錄的主要屬性值。

**傳回值類型：**字串

範例： 設定 currentView 變數為連絡人子格的檢視表選取器的目前檢視表。

var firstEntityPrimaryAttributeValue = Xrm.Page.getControl("Contacts").getGrid().getRows().get(0).getData().getEntity().getPrimaryAttributeValue();
// firstEntityPrimaryAttributeValue == "Rene Valdes (sample)"

ViewSelector

使用 ViewSelector 方法取得或設定關於子格控制項檢視表選取器的資訊。

注意

如果尚未設定子格控制項顯示檢視表選取器，呼叫 ViewSelector 方法會擲回錯誤。

getCurrentView

使用此方法取得目前檢視表的參照。

**傳回值類型：**查詢物件

範例： 設定 currentView 變數為連絡人子格的檢視表選取器的目前檢視表。

var currentView = Xrm.Page.getControl("Contacts").getViewSelector().getCurrentView();

備註：

如果尚未設定子格控制項顯示檢視表選取器，在 GridControl.getViewSelector 方法所傳回的 ViewSelector 上呼叫此方法會擲回錯誤。

isVisible

使用此方法決定檢視表選取器是否可見。

**傳回值類型：**布林值

範例： 設定 viewSelectorIsVisible 變數代表連絡人子格的檢視表選取器的顯示性狀態。

var viewSelectorIsVisible = Xrm.Page.getControl("Contacts").getViewSelector().isVisible();

備註：

如果尚未設定子格控制項顯示檢視表選取器，在 GridControl.getViewSelector 所傳回的 ViewSelector 上呼叫此方法會擲回錯誤。

setCurrentView

使用此方法設定目前檢視表。

**參數類型：**查詢物件

範例： 設定 ContactsIFollow 變數為連絡人子格的目前檢視表。

var ContactsIFollow = {
 entityType: 1039, // SavedQuery
 id:"{3A282DA1-5D90-E011-95AE-00155D9CFA02}", 
 name: "Contacts I Follow"
}
//Set the view using ContactsIFollow
Xrm.Page.getControl("Contacts").getViewSelector().setCurrentView(ContactsIFollow);

備註：

如果尚未設定子格控制項顯示檢視表選取器，在 GridControl.getViewSelector 所傳回的 ViewSelector 上呼叫此方法會擲回錯誤。

此查詢有下列屬性：

名稱	類型	描述
entityType	編號	SavedQuery (1039) 或 UserQuery (4230) 的物件類型代碼，代表使用者可以選取的檢視表。
id	字串	使用者可以選取的檢視表的 id。
名稱	字串	使用者可以選取的檢視表名稱。

另請參閱

Microsoft Dynamics CRM Online 2015 Update 1 的新功能
撰寫子格的指令碼
Xrm.Page.ui 控制項 (用戶端參考)
集合 (用戶端參考)
用戶端程式設計參考
撰寫 Microsoft Dynamics CRM 2015 表單的程式碼
撰寫用戶端應用程式擴充功能

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權