Grid (read-only) objects and methods (client-side reference)获取子表单对象的一些方法 Crm 2016

https://msdn.microsoft.com/en-us/library/dn932126.aspx#BKMK_GridControl

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can set event handlers to execute scripts when data is loaded in subgrids. This provides methods to change the selected view and get references to data displayed in the grid.

In this topic

 

GridControl

Events and methods for the GridControl: OnLoad event, addOnLoad, getEntityName, getGrid, getViewSelector and removeOnLoad.

Grid

Methods for the Grid returned by the GridControl.getGrid method: getRows, getSelectedRows, and getTotalRecordCount.

GridRow

The getData method for the GridRow returned by the Grid.getRows and Grid.getSelectedRows methods.

GridRowData

The getEntity method for the GridRowData returned by the GridRow.getData method.

GridEntity

Methods for the GridEntity returned by the GridRowData.getEntity method: getEntityName, getEntityReference, getId, andgetPrimaryAttributeValue.

ViewSelector

Methods for the ViewSelector returned by the GridControl.getViewSelector, getCurrentView, isVisible and setCurrentView

GridControl

 

Before CRM Online 2015 Update 1 the only unique method for the subgrid control was refresh. When you know the name of the subgrid control you can access it using the following code, for example, to access the CONTACTS subgrid in the default account form.

 

 

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

Tip

To identify the names of subgrid controls in the form without opening the form editor, see the information in Use browser developer tools.

As an Xrm.Page.ui control, GridControl also has all the standard control methods: getControlType, Label methods, getParent, Visible methods,setFocus, and Notification methods as well as refresh. See Xrm.Page.ui control (client-side reference) for more information on these methods.

OnLoad event

 

Add event handlers to this event to run every time the subgrid refreshes. This includes when users sort the values by clicking the column headings. Use the GridControl.addOnLoad and GridControl.removeOnLoad methods to manage event handlers, usually in the form Onloadevent.

addOnLoad

 

Use this method to add event handlers to the GridControlOnLoad event.

Parameter type: Function

Example: Add the myContactsGridOnloadFunction function to the Contacts subgrid OnLoad event.

JavaScript

 

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

getEntityName

 

Use this method to get the logical name of the entity data displayed in the grid.

Return value type: String

Example: Set the opportunitySubgrids variable to an array of subgrid controls that display opportunity records.

JavaScript

 

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

getGrid

 

Use this method to get access to the Grid available in the GridControl.

Return value type:Grid

Example: Set the contactsSubgridGrid variable to the grid of the Contacts subgrid.

JavaScript

 

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

getViewSelector

 

Use this method to get access to the ViewSelector available for the GridControl.

Return value type:ViewSelector

Example: Set the contactsSubgridViewSelector variable to the view selector of the Contacts subgrid.

JavaScript

 

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

removeOnLoad

 

Use this method to remove event handlers from the GridControlOnLoad event.

Parameter type: Function

Example: Add the myContactsGridOnloadFunction function to the Contacts subgrid OnLoad event and then remove it.

JavaScript

 

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

Grid

 

Use Grid methods to access information about data in the grid. Grid is returned by the GridControl.getGrid method.

getRows

 

Returns a collection of every GridRow in the Grid.

Return value type: Collection

Example: Set the allRows variable to a collection of GridRow from the Contacts subgrid.

JavaScript

 

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

Remarks:

See Collections (client-side reference) for information on the methods available to access data in a collection.

getSelectedRows

 

Returns a collection of every selected GridRow in the Grid.

Return value type: Collection

Example: Populate the selectedEntityReferencesArray variable with entity references for selected rows from the Contacts subgrid.

 

 

//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());
});

Remarks:

See Collections (client-side reference) for information on the methods available to access data in a collection.

getTotalRecordCount

 

In the web application or the Dynamics 365 for Outlook client while connected to the server, this method returns the total number of records that match the filter criteria of the view, not limited by the number visible in a single page.

When the Dynamics 365 for Outlook client isn’t connected to the server, this number is limited to those records that the user has selected to take offline.

For Microsoft Dynamics 365 for tablets and Microsoft Dynamics 365 for phones this method will return the number of records in the subgrid.

Return value type: Number

Example: Set the filteredRecordCount variable to the total number of records that match the filter criteria of the view.

JavaScript

 

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

GridRow

 

Use the GridRow.getData method to access the GridRowData. A collection of GridRow is returned by Grid.getRows and Grid.getSelectedRowsmethods.

getData

 

Returns the GridRowData for the GridRow.

Return value type:GridRowData

Example: Populate the allGridRowDataArray variable with GridRowData for all rows from the Contacts subgrid.

JavaScript

 

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

GridRowData

 

Use the GridRowData.getEntity method to access the GridEntity. GridRowData is returned by the GridRow.getData method.

getEntity

 

Returns the GridEntity for the GridRowData.

Return value type:GridEntity

Example: Populate the allGridEntitiesArray variable with GridEntity for all rows from the Contacts subgrid.

JavaScript

 

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

GridEntity

 

Use the GridEntity methods to access data about the specific records in the rows. GridEntity is returned by the GridRowData.getEntity method.

getEntityName

 

Returns the logical name for the record in the row.

Return value type: String

Example: Set the firstEntityType variable to the value of the entity logical name for the first row in the Contacts subgrid.

JavaScript

 

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

getEntityReference

 

Return value type: Lookup

Example: Set the firstEntityType variable to an entity reference for the first row in the Contacts subgrid.

JavaScript

 

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)"

Remarks:

This lookup has the following properties:

Name	Type	Description
entityType	String	The logical name for the record in the row. The same data returned by the GridEntity.getEntityNamemethod.
id	String	The id for the record in the row. The same data returned by the GridEntity.getId method.
name	String	The primary attribute value for the record in the row. The same data returned by theGridEntity.getPrimaryAttributeValue method.

getId

 

Returns the id for the record in the row.

Return value type: String

Example: Set the firstEntityId variable to the value of id of the record from the first row in the Contacts subgrid.

JavaScript

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

getPrimaryAttributeValue

 

Returns the primary attribute value for the record in the row.

Return value type: String

Example: Set the currentView variable to the current view of the view selector for the Contacts subgrid.

JavaScript

 

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

ViewSelector

 

Use the ViewSelector methods to get or set information about the view selector of the subgrid control.

Note

If the subgrid control is not configured to display the view selector, calling the ViewSelector methods will throw an error.

getCurrentView

 

Use this method to get a reference to the current view.

Return value type: Lookup object

Example: Set the currentView variable to the current view of the view selector for the Contacts subgrid.

JavaScript

 

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

Remarks:

If the subgrid control is not configured to display the view selector, calling this method on the ViewSelector returned by theGridControl.getViewSelector method will throw an error.

isVisible

 

Use this method to determine whether the view selector is visible.

Return value type: Boolean

Example: Set the viewSelectorIsVisible variable to represent the visibility status of the view selector for the Contacts subgrid.

JavaScript

 

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

Remarks:

If the subgrid control is not configured to display the view selector, calling this method on the ViewSelector returned by theGridControl.getViewSelector will throw an error.

setCurrentView

 

Use this method to set the current view.

Parameter type: Lookup object

Example: Set the ContactsIFollow variable to be the current view of the Contacts subgrid.

JavaScript

 

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);

Remarks:

If the subgrid control isn’t configured to display the view selector, calling this method on the ViewSelector returned by theGridControl.getViewSelector will throw an error.

This Lookup has the following properties:

Name	Type	Description
entityType	Number	The object type code for the SavedQuery (1039) or UserQuery (4230) that represents the view the user can select.
id	String	The ID for the view the user can select.
name	String	The name of the view the user can select.

See Also

 

Write scripts for subgrids
Xrm.Page.ui control (client-side reference)
Collections (client-side reference)
Client-side programming reference
Write code for Microsoft Dynamics 365 forms
Extend Microsoft Dynamics 365 on the client