Compartir a través de

Referencia de scripting de formularios

  • Artículo

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Este tema muestra una referencia rápida de los métodos de scripting de formularios utilizados con frecuencia en función de las tareas que realiza con ellos. Para obtener la referencia completa, consulte Referencia de programación del lado del cliente. Todos los ejemplos de esta página usan el formulario principal predeterminado de la entidad de cuenta a menos que se especifique lo contrario.

En este tema

Atributos

  • Obtener acceso a los atributos

  • Obtener o establecer datos de atributo de entidad

  • Obtener metadatos del atributo

Guardar argumentos de evento

Mostrar notificaciones

Controles

  • Acceder a controles del formulario

  • Acceder a los controles de encabezado

  • Acceder a controles del flujo de proceso de negocio

  • Métodos de control de formulario

  • Métodos de control de OptionSet

  • Métodos de control de IFRAME y recursos web

  • Consultar métodos de control

  • Métodos de control de subcuadrícula

  • Métodos de control de fecha

Navegación del formulario

Pestañas y secciones

Agregar o quitar controladores de eventos en tiempo de ejecución

Métodos de información contextual

Obtener, actualizar, o guardar datos de entidad

Atributos

Los atributos almacenan los datos disponibles en el registro.

Obtener acceso a los atributos

Los atributos están disponibles en la colección Xrm.Page.data.entity.attributes. Para tener acceso a un atributo, puede usar el método **Xrm.Page.data.entity.attributes.**9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get o la versión de acceso directo Xrm.Page.getAttribute. El método get acepta cuatro tipos de argumentos:

  • Cadena: devuelve un objeto de atributo en el que el nombre del atributo coincide con la cadena.

  • Número: devuelve el objeto del atributo en el que el índice de la colección Xrm.Page.data.entity.attributes coincide con el número.

  • Ninguno: devuelve una matriz de todos los atributos.

  • Delegate function(attribute,index): devuelve una matriz de cualquier atributo de la colección Xrm.Page.data.entity.attributes que hace que la función delegar devuelva true.

Tarea

Ejemplo

Obtener acceso a un atributo por nombre

var nameAttribute = Xrm.Page.getAttribute("name");

Asigna el atributo del campo Nombre de cuenta a la variable nameAttribute.

Obtener acceso a un atributo por índice

var firstAttribute = Xrm.Page.getAttribute(0);

Asigna el primer atributo de la colección Xrm.Page.data.entity.attributes a la variable firstAttribute.

Obtener acceso a todos los atributos

var allAttributes = Xrm.Page.getAttribute();

Asigna una matriz de todos los atributos de la colección Xrm.Page.data.entity.attributes a la variable allAttributes.

Obtener acceso a todos los atributos que cumplen criterios específicos

var optionsetAttributes = Xrm.Page.getAttribute(function (attribute, index) {
return attribute.getAttributeType() == "optionset";
});

Asigna una matriz de todos los atributos de la colección Xrm.Page.data.entity.attributes que cumplen los criterios establecidos en la función anónima, que devuelve true cuando el tipo de atributo es "optionset" a la variable optionsetAttributes.

La colección Xrm.Page.data.entity.attributes también incluye un método 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach que puede usar para obtener acceso a atributos dentro de una función. La siguiente función writeRequiredAttributesToConsole escribirá los nombres de los atributos que requieren datos en la consola de depuración:

function writeRequiredAttributesToConsole() {
 var requiredAttributeNames = [];

 Xrm.Page.data.entity.attributes.forEach(
 function (attribute, index) {
  if (attribute.getRequiredLevel() == "required")
  { requiredAttributeNames.push(attribute.getName()); }
 });

 if (requiredAttributeNames.length > 0) {
  if (typeof console != "undefined") {
   console.log(requiredAttributeNames.join());
  }
 }
 else {
  if (typeof console != "undefined") {
   console.log("No required attributes detected");
  }
 }
}

En este tema

Obtener o establecer datos de atributo de entidad

Los ejemplos de la siguiente tabla muestran cómo puede recuperar o cambiar los datos almacenados en los atributos.

Tarea

Método

Ejemplo

Obtener el valor de un atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getValue

var nameValue = Xrm.Page.getAttribute("name").getValue();

Asigna el valor del campo Nombre de cuenta a la variable nameValue.

Establecer el valor de un atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setValue

Xrm.Page.getAttribute("name").setValue("new name");

Establece el valor del campo Nombre de cuenta en "nuevo nombre".

Obtener el valor de texto de la opción actualmente seleccionada de un atributo optionset

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getText

var addressType = Xrm.Page.getAttribute("address1_addresstypecode").getText();

Asigna el texto de la opción seleccionada en el campo Tipo de dirección a la variable addressType.

Obtener el objeto de la opción actualmente seleccionada en un atributo optionset.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSelectedOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getSelectedOption();

Asigna la opción seleccionada en el campo Tipo de dirección a la variable addressTypeOption.

En este tema

Obtener metadatos del atributo

En los ejemplos de la siguiente tabla se muestra cómo puede consultar las propiedades del atributo para entender de qué tipo de atributo se trata o cambiar el comportamiento del atributo.

Tarea

Método

Ejemplo

Obtener el tipo de atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getAttributeType

var attributeType = Xrm.Page.getAttribute(0).getAttributeType();

Asigna el valor de cadena que representa el tipo de atributo para el primer atributo a la variable attributeType.

Obtener el formato del atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getFormat

var attributeFormat = Xrm.Page.getAttribute(0).getFormat();

Asigna el valor de cadena que representa el formato del primer atributo a la variable attributeFormat.

Obtener el valor inicial de un atributo Boolean o optionset.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getInitialValue

var attributeInitialValue = Xrm.Page.getAttribute("address1_addresstypecode").getInitialValue();

Asigna el valor del número inicial del campo Tipo de dirección a la variable attributeInitialValue.

Determinar si el valor de un atributo ha cambiado

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsDirty

var isNameChanged = Xrm.Page.getAttribute("name").getIsDirty();

Asigna un valor Boolean que indica si el valor del campo Nombre de cuenta ha cambiado a la variable isNameChanged.

Determina si un atributo de búsqueda representa una búsqueda de tipo partylist.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsPartyList

var isPartyList = Xrm.Page.getAttribute("to").getIsPartyList();

Asigna un valor Boolean que indica si el campo para de la entidad Correo electrónico representa una búsqueda de lista de partes.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Obtener el valor máximo permitido de un atributo que contiene un número

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMax

var newValue = 100000000000001;
var newValueBelowMax = (newValue < Xrm.Page.getAttribute("creditlimit").getMax())

Asigna un valor Boolean que indica si el valor de la variable newValue supera el valor máximo permitido para el campo Límite del crédito a la variable newValueBelowMax.

Obtener la longitud máxima permitida de un atributo que contiene una cadena

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMaxLength

var newAccountName = "A Store";
var nameTooLong = (newAccountName.length > Xrm.Page.getAttribute("name").getMaxLength())

Asigna un valor Boolean que indica si el valor de la variable newAccountName supera la longitud máxima permitida para el campo Nombre de cuenta a la variable nameTooLong.

Obtener el valor mínimo permitido de un atributo que contiene un número

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMin

var newValue = -1;
var newValueBelowMin = (newValue < Xrm.Page.getAttribute("creditlimit").getMin())

Asigna un valor Boolean que indica si el valor de la variable newValue es inferior al valor mínimo permitido para el campo Límite del crédito a la variable newValueBelowMin.

Obtener el nombre lógico de un atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getName

var attributeName = Xrm.Page.getAttribute(0).getName();

Asigna el valor del nombre lógico del primer atributo de la página a la variable attributeName.

Obtener el objeto de opción que representa un valor

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getOption(1);
alert(addressTypeOption.text); //displays 'Bill To'

Abre una alerta que muestra el texto de la opción del campo Tipo de dirección con un valor de 1.

Obtener un valor numérico que representa el nivel de precisión del atributo de número

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getPrecision

var creditLimitPrecision = Xrm.Page.getAttribute("creditlimit").getPrecision();

Asigna el valor de precisión del campo Límite del crédito a la variable creditLimitPrecision.

Obtener un valor de cadena que representa si un atributo debe tener un valor

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getRequiredLevel

var creditLimitRequired = Xrm.Page.getAttribute("creditlimit").getRequiredLevel();

El valor de la variable creditLimitRequired puede ser none, required o recommended.

Cambiar si los datos son obligatorios en un campo para poder guardar un registro

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setRequiredLevel

Xrm.Page.getAttribute("creditlimit").setRequiredLevel("required");

Convierte el campo Límite del crédito en un campo obligatorio.

Determinar si los datos de un atributo se enviarán cuando se guarda el registro

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSubmitMode

var nameSubmitMode = Xrm.Page.getAttribute("name").getSubmitMode();

El valor de la variable nameSubmitMode será always, never o dirty para representar el submitMode para el campo Nombre de cuenta.

Controlar si los datos de un atributo se guardarán cuando se guarda el registro

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setSubmitMode

Xrm.Page.getAttribute("name").setSubmitMode("always");

El ejemplo obligará a guardar siempre el valor del campo Nombre de cuenta aunque no se haya modificado.

Cuando se aplicó la seguridad de nivel de campo a un atributo,
determine si un usuario tiene privilegios para realizar operaciones de creación,
lectura o actualización en el atributo. Para obtener más información, vea
Cómo se puede usar la seguridad de campos para controlar el acceso a los valores de campo en Microsoft Dynamics 365

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getUserPrivilege

var canUpdateNameAttribute = Xrm.Page.getAttribute("name").getUserPrivilege().canUpdate;

Asigna un valor Boolean que representa el privilegio del usuario para actualizar el campo Nombre de cuenta a la variable de canUpdateNameAttribute.

En este tema

Guardar argumentos de evento

Cuando se aplica la lógica de negocios, con frecuencia es necesario impedir que un registro se guarde para que el usuario pueda incluir la información necesaria. Para ello, debe configurar el controlador de eventos para que pase en el contexto de ejecución. El contexto de ejecución contiene el método getEventArgs para recuperar los argumentos del evento. Estos argumentos incluyen métodos que puede usar para controlar si se guardará un registro o consultar las propiedades que le brindan información sobre el evento save.

Tarea

Ejemplo

Impedir que un registro se guarde.

function My_PreventSaveFunction(eContext) {
 eContext.getEventArgs().preventDefault();
}

Use el parámetro eContext para capturar el contexto de ejecución y use el método preventDefault incluido con los argumentos del evento.

Determinar qué acción inició la operación de guardar.

function My_GetSaveModeTextFunction(eContext) {
 var saveModeCode = eContext.getEventArgs().getSaveMode();
 var saveModeText = "Unknown";
 switch (saveModeCode) {
  case 1:
   saveModeText = "Save";
   break;
  case 2:
   saveModeText = "SaveAndClose";
   break;
  case 5:
   saveModeText = "Deactivate";
   break;
  case 6:
   saveModeText = "Reactivate";
   break;
  case 7:
   saveModeText = "Send";
   break;
  case 15:
   saveModeText = "Disqualify";
   break;
  case 16:
   saveModeText = "Qualify";
   break;
  case 47:
   saveModeText = "Assign";
   break;
  case 58:
   saveModeText = "SaveAsCompleted";
   break;
  case 59:
   saveModeText = "SaveAndNew";
   break;
  case 70:
   saveModeText = "AutoSave";
   break;
 }
 return saveModeText;
}

Use el parámetro eContext para capturar el contexto de ejecución y use el método getSaveMode incluido con los argumentos del evento para convertir el valor de código entero en texto.

En este tema

Mostrar notificaciones

Las notificaciones ofrecen un modo de mostrar un mensaje al usuario.

Tarea

Método

Ejemplo

Mostrar un mensaje cerca del control para indicar que los datos no son válidos.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.setNotification("'Test' is not a valid name.");
})

Establece un mensaje de error de validación en cada control del formulario para el atributo Nombre de cuenta.

Mientras se muestra este mensaje, el registro no se puede guardar.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Eliminar un mensaje que ya se muestra para un control.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.clearNotification();
})

Borra todos los mensajes de error de validación en cada control del formulario para el atributo Nombre de cuenta.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Mostrar notificaciones en el nivel del formulario.

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_setFormNotification

Xrm.Page.ui.setFormNotification(
"Hello",
"INFO",
"helloMsg"
);

Muestra el mensaje "Hola" en la parte superior del formulario con un icono de información del sistema.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Quitar notificaciones en el nivel del formulario.

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_clearFormNotification

Xrm.Page.ui.clearFormNotification("helloMsg");

Borra el mensaje establecido anteriormente con "helloMsg" como el parámetro uniqueid.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Mostrar un diálogo de alerta sin bloqueo con una función de devolución de llamada.

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_alertDialog

var alertDisplayed = false;
Xrm.Utility.alertDialog(
"Showing Alert",
function () { alertDisplayed = true; }
)

Mostrar una alerta y establecer el valor de la variable alertDisplayed cuando se cierra.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Mostrar un diálogo de confirmación sin bloqueo con distintas devoluciones de llamada en función del botón que ha pulsado el usuario.

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_confirmDialog

var agree = false;
Xrm.Utility.confirmDialog(
"Do you agree?",
function () { agree = true;},
function () { agree = false; }
);

Mostrar un mensaje de confirmación y establecer el valor de la variable agree según la respuesta.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

En este tema

Controles

Los controles representan los elementos de la interfaz de usuario del formulario. Cada atributo del formulario tendrá al menos un control asociado con él. No todos los controles están asociado con un atributo.IFRAME, los recursos web y las subcuadrículas son controles que no tienen atributos.

Acceder a controles del formulario

Los controles están disponibles desde la colección Xrm.Page.ui.controls. Para tener acceso a un control, puede usar el método **Xrm.Page.ui.controls.**9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get o la versión de acceso directo Xrm.Page.getControl.

El método get acepta cuatro tipos de argumentos:

  • Cadena: devuelve un control en el que el nombre lógico coincide con la cadena.

  • Número: devuelve el control en el que el índice de la colección Xrm.Page.ui.controls coincide con el número.

  • Ninguno: devuelve una matriz de todos los controles.

  • Delegate function(control,index): devuelve una matriz de cualquier control de la colección Xrm.Page.ui.controls que hace que la función delegar devuelva el valor True.

Tarea

Ejemplo

Obtener acceso a todos los controles de un atributo específico

var nameControls = Xrm.Page.getAttribute("name").controls.get();

Asigna una matriz de todos los controles del atributo name a la variable nameControls.

Obtener acceso a un control por nombre

var nameControl = Xrm.Page.getControl("name");

Asigna el primer control que representa al campo Nombre de cuenta a la variable nameControl.

El primer control que se agrega a un formulario de un atributo tendrá el mismo nombre que el atributo. Cada nombre de control adicional tendrá un número de índice anexado al nombre. Por ejemplo, tres controles del atributo nombre se llamarán: name, name1 y name2 respectivamente.

Obtener acceso a un control por índice

var firstControl = Xrm.Page.getControl(0);

Asigna el primer control de la colección Xrm.Page.ui.controls a la variable firstControl.

Obtener acceso a todos los controles

var allControls = Xrm.Page.getControl();

Asigna una matriz de todos los controles de la colección Xrm.Page.ui.controls a la variable allControls.

Obtener acceso a todos los controles que cumplen criterios específicos

var optionsetControls = Xrm.Page.getControl(function (control, index) {
return control.getControlType() == "optionset";
});

Asigna una matriz de todos los atributos de la colección Xrm.Page.ui.controls que cumplen los criterios establecidos en la función anónima, que devuelve true cuando el tipo de control es "optionset", a la variable optionsetControls.

Cada sección también contiene una colección de controles que contiene únicamente los controles de esa sección. El siguiente ejemplo de código asigna la variable generalTabAccountInfoSectionControls a una matriz de controles que se encuentra en la sección Dirección de la pestaña General.
var generalTabAccountInfoSectionControls = Xrm.Page.ui.tabs.get("general").sections.get("address").controls.get();

Nota

Cada atributo existe solo una vez en el formulario, pero se puede agregar un campo al formulario de ese atributo varias veces. Cada campo que se agrega crea otro control. Los formularios se pueden seguir personalizando después de escribir los scripts. Los scripts que escribe para los controles del atributo deben asumir que se han incluido en el formulario varias veces. Cualquier acción que desee realizar en un control de un atributo se debería aplicar normalmente a todos los controles de ese atributo. Por ejemplo, si desea deshabilitar un control, pero solo deshabilita uno de ellos, el usuario aún puede especificar datos con un control diferente. Por esta razón, se recomienda usar el siguiente patrón con la colección del método 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach para aplicar la misma lógica a todos los controles de un atributo, incluso si hay un solo control en el momento que escribe el script.

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

En este tema

Acceder a los controles de encabezado

Los controles del encabezado siguen la convención de nomenclatura donde se anexa el prefijo "header_" al nombre del control. Por ejemplo, si el atributo name está el encabezado puede tener acceso a él mediante:
var nameControlInHeader = Xrm.Page.getControl("header_name");

Acceder a controles del flujo de proceso de negocio

Los controles del control del flujo de proceso de negocio siguen la convención de nomenclatura donde se anexa el prefijo "header_process_" al nombre del control. Por ejemplo, si el atributo name está el encabezado puede tener acceso a él mediante:
var nameControlInBPF = Xrm.Page.getControl("header_process_name");

Nota

Sólo los controles de la fase activa aparecen en la colección de Xrm.Page.ui.controls cuando el formulario se carga. Se agregan otros controles del flujo de proceso de negocio cuando se selecciona una fase para la entidad actual.

Métodos de control de formulario

Una vez que tenga acceso a un control, puede llamar a los siguientes métodos.

Tarea

Método

Ejemplo

Determinar si un control está visible

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getVisible

var isNameVisible = Xrm.Page.getControl("name").getVisible();

Asigna un valor Boolean a la variable isNameVisible que representa si el campo Nombre de cuenta está visible.

Ocultar o mostrar un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setVisible

Xrm.Page.getControl("name").setVisible(false);

Oculta el campo Nombre de cuenta.

Obtener una referencia al atributo para el control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getAttribute

var nameAttribute = Xrm.Page.getControl("name").getAttribute();

Asigna el atributo para el control del campo Nombre de cuenta a la variable nameAttribute.

Nota

No todos los controles tienen atributos.

Determinar el tipo del control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getControlType

var optionSetControls = Xrm.Page.getControl(function (control, index) { return control.getControlType() == "optionset"; });

Asigna una matriz de controles optionset a la variable optionSetControls.

Determinar si un control está habilitado

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDisabled

var disabledControls = Xrm.Page.getControl(function(control, index) { return control.getDisabled(); });

Asigna una matriz de controles deshabilitados a la variable disabledControls.

Nota

Los controles de recursos web y subcuadrículas no admiten este método.

Deshabilitar o habilitar un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDisabled

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

Deshabilita cada control para el atributo name.

Sugerencia

Recuerde que cualquier atributo puede tener varios controles.

Obtener la etiqueta de un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getLabel

var nameControlLabel = Xrm.Page.getControl("name").getLabel();

Asigna el valor del control del campo Nombre de cuenta a la variable nameControlLabel.

Cambiar la etiqueta de un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setLabel

Xrm.Page.getControl("name").setLabel("Company Name");

Cambia la etiqueta del campo Nombre de cuenta a Nombre de la compañía.

Obtener el nombre de un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getName

var firstControlName = Xrm.Page.getControl(0).getName();

Asigna el nombre del primer control en la colección Xrm.Page.ui.controls a la variable firstControlName.

Obtener el elemento principal de un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getParent

var parentSection = Xrm.Page.getControl("name").getParent();

Asigna la sección principal del control del campo Nombre de cuenta a la variable parentSection.

Establecer el enfoque en un control

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setFocus

Xrm.Page.getControl("name").setFocus();

Establece el enfoque en el campo Nombre de cuenta.

En este tema

Métodos de control de OptionSet

Los conjuntos de opciones (Optionsets) tienen algunos métodos especiales. Es importante recordar que el atributo define las opciones válidas para un optionset. Cuando trabaja con un control optionset, puede manipular las opciones disponibles pero no puede crear opciones nuevas.

Tarea

Método

Ejemplo

Agregar una opción a un control optionset

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addOption

var addressTypeCodeControl = Xrm.Page.getControl("address1_addresstypecode");
var billToAddressOption = addressTypeCodeControl.getAttribute().getOption(1);
addressTypeCodeControl.clearOptions();
addressTypeCodeControl.addOption(billToAddressOption);

Con una referencia al control del campo Tipo de dirección, obtenga acceso al atributo del control y use el método 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption para establecer la variable billToAddressOption en la opción que representa la opción Facturación.

Use 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions para quitar cualquier opción existente y use addOption para establecer billToAddressOption como la única opción disponible para este control.

Quitar todas las opciones de un control optionset

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions

Xrm.Page.getControl("address1_addresstypecode").clearOptions();

Quite todas las opciones del control del campo Tipo de dirección.

Quitar una sola opción de un control optionset.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_removeOption

Xrm.Page.getControl("address1_addresstypecode").removeOption(1);

Quite la opción Facturación del control del campo Tipo de dirección.

En este tema

Métodos de control de IFRAME y recursos web

Un control IFRAME le permite incluir una página dentro de un formulario al proporcionar una URL. Un recurso web HTML agregado a un formulario se presenta mediante un elemento IFRAME.Silverlight y los recursos web de imagen se incrustan directamente en la página.

Tarea

Método

Ejemplo

Obtener el valor del parámetro de la cadena de consulta de datos pasado un recurso web de Silverlight.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getData

var dataValue = Xrm.Page.getControl("WebResource_SilverLightControl").getData();

Asigna el valor pasado con el parámetro de la cadena de consulta de datos a la variable dataValue.

Obtener la URL del contenido que se muestra actualmente en el IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getSrc

var iframeSource = Xrm.Page.getControl("IFRAME_targetPage").getSrc();

Asigna la cadena que representa el valor del atributo IFRAME.src actual a la variable iframeSource.

Establecer la URL del contenido que se va a mostrar en un IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setSrc

Xrm.Page.getControl("IFRAME_targetPage").setSrc("http://www.bing.com");

Establece una URL para ser el IFRAME.src del control.

Obtener la URL que representa a la URL configurada de manera predeterminada para un IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getUrl

var initialUrl = Xrm.Page.getControl("IFRAME_bing").getInitialUrl();

Asigna la URL inicial configurada para mostrarse en el IFRAME a la variable initialUrl.

Obtener el objeto del formulario que representa el recurso web o IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getObject

var obj = Xrm.Page.getControl("IFRAME_bing").getObject();

Asigna una referencia de objeto a la variable obj. Para un IFRAME, será el elemento de Document Object Model (DOM) IFRAME. Para un recurso web de Silverlight, será el elemento Objeto Objeto que representa el complemento incrustado de Silverlight.

En este tema

Consultar métodos de control

Un requisito común para los controles de búsqueda consiste en especificar la vista predeterminada que se muestra cuando un usuario actualiza el campo.

Tarea

Método

Ejemplo

Agregar una vista personalizada para una búsqueda.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
var viewDisplayName = "SDK Sample View";
var fetchXml = "<fetch version='1.0' " +
"output-format='xml-platform' " +
"mapping='logical'>" +
"<entity name='account'>" +
"<attribute name='name' />" +
"<attribute name='address1_city' />" +
"<order attribute='name' " +
"descending='false' />" +
"<filter type='and'>" +
"<condition attribute='ownerid' " +
"operator='eq-userid' />" +
"<condition attribute='statecode' " +
"operator='eq' " +
"value='0' />" +
"</filter>" +
"<attribute name='primarycontactid' />" +
"<attribute name='telephone1' />" +
"<attribute name='accountid' />" +
"<link-entity "+
"alias='accountprimarycontactidcontactcontactid' " +
"name='contact' " +
"from='contactid' " +
"to='primarycontactid' " +
"link-type='outer' " +
"visible='false'>" +
"<attribute name='emailaddress1' />" +
"</link-entity>" +
"</entity>" +
"</fetch>";
var layoutXml = "<grid name='resultset' " +
"object='1' " +
"jump='name' " +
"select='1' " +
"icon='1' " +
"preview='1'>" +
"<row name='result' " +
"id='accountid'>" +
"<cell name='name' " +
"width='300' />" +
"<cell name='telephone1' " +
"width='100' />" +
"<cell name='address1_city' " +
"width='100' />" +
"<cell name='primarycontactid' " +
"width='150' />" +
"<cell name='accountprimarycontactidcontactcontactid.emailaddress1' " +
"width='150' " +
"disableSorting='1' />" +
"</row>" +
"</grid>";
Xrm.Page.getControl("parentaccountid").addCustomView(viewId, "account", viewDisplayName, fetchXml, layoutXml, true);

Establece las variables viewId, viewDisplayName, fetchXml y layoutXml para pasar como argumentos a fin de que se agregue una vista personalizada como la vista predeterminada al control del campo de búsqueda Cuenta primaria.

Obtener la vista predeterminada para una búsqueda.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDefaultView

var defaultViewId = Xrm.Page.getControl("parentaccountid").getDefaultView();

Asigna el valor id de la vista predeterminada a la variable defaultViewId.

Establecer la vista predeterminada para una búsqueda.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDefaultView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
Xrm.Page.getControl("parentaccountid").setDefaultView(viewId);

Establece la vista predeterminada para el control del campo Cuenta primaria al valor id en la variable viewId.

Filtrar los registros devueltos para un control de búsqueda

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomFilter

El siguiente ejemplo de código es para la búsqueda de Cuenta del formulario de oportunidad (parentaccountid). Cuando la función Sdk.setParentAccountIdFilter se establece en el controlador de eventos de Onload del formulario, la función Sdk.filterCustomAccounts se agrega al evento PreSearch para esa búsqueda. El resultado es que solo se devuelven las cuentas con el valor Categoría (accountcategorycode) de Cliente preferido (1).

  var Sdk = window.Sdk || {};

  Sdk.filterCustomerAccounts = function () {
      //Only show accounts with the type 'Preferred Customer'
      var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
      Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
  }
  //set 'Sdk.setParentAccountIdFilter' in the Opportunity form Onload event handler
  Sdk.setParentAccountIdFilter = function () {
      Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
  }

En este tema

Métodos de control de subcuadrícula

El control SubGrid es una cuadrícula dentro de un formulario. Tiene un método único.

Tarea

Método

Ejemplo

Actualizar los datos que se muestran en la subcuadrícula

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_refresh

Xrm.Page.getControl("accountcontactsgrid").refresh();

Actualizar los Contactossubgrid.

En este tema

Métodos de control de fecha

El control Fecha tiene un método único.

Tarea

Método

Ejemplo

Especificar si un control de fecha debe mostrar la parte de hora de la fecha.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setShowTime

Xrm.Page.getControl("createdon").setShowTime(false);

Establecer el campo Fecha de creación de modo que no se muestre la hora.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

En este tema

Puede usar y manipular los elementos de navegación en el lado izquierdo del formulario. Por lo general, estos elementos de navegación muestran registros relacionados con el registro que se muestra en el formulario.

Puede obtener acceso a los elementos de navegación mediante la colección Xrm.Page.ui.navigation.items. Al igual que en todas las colecciones del formulario, hay un método 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get y 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach.

Tarea

Método

Ejemplo

Obtener el nombre de un elemento de navegación

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getId

var navItemIds = [];
Xrm.Page.ui.navigation.items.forEach(
function (item, index)
{ navItemIds.push(item.getId()) }
);

Crea una matriz navItemIds que contiene los valores id de cada elemento de navegación en la colección Xrm.Page.ui.navigation.items.

Obtener la etiqueta de un elemento de navegación.

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getLabel

var navAddressesLabel = Xrm.Page.ui.navigation.items.get("navAddresses").getLabel();

Asigna la etiqueta del elemento de navegación Más direcciones a la variable navAddressesLabel.

Establecer la etiqueta de un elemento de navegación

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setLabel

Xrm.Page.ui.navigation.items.get("navAddresses").setLabel("Other Addresses");

Cambia la etiqueta del elemento de navegación Más direcciones a Otras direcciones.

Ocultar o mostrar un elemento de navegación

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setVisible

Xrm.Page.ui.navigation.items.get("navAddresses").setVisible(false);

Oculta el elemento de navegación More Addresses.

Determinar si un elemento de navegación está visible

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getVisible

var moreAddressesVisible = Xrm.Page.ui.navigation.items.get("navAddresses").getVisible()

Asigna un valor Boolean a la variable moreAddressesVisible para representar si el elemento de navegación Más direcciones está visible.

Establecer el enfoque en un elemento de navegación.

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setFocus

Xrm.Page.ui.navigation.items.get("navAddresses").setFocus();

Establece el enfoque en el elemento de navegación Más direcciones.

En este tema

Pestañas y secciones

Cada formulario tiene una colección de pestañas. Cada pestaña tiene una colección de secciones. Cada sección tiene una colección de controles. Puede obtener acceso a estos elementos mediante programación y usar sus métodos.

Tarea

Método

Ejemplo

Determinar si una pestaña se expande o contrae

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_getDisplayState

var isGeneralTabExpanded = (Xrm.Page.ui.tabs.get("general").getDisplayState() == "expanded")

Asigna un valor Boolean a la variable isGeneralTabExpanded que indica si la pestaña General se expande.

Expandir o contraer una pestaña

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetDisplayState

Xrm.Page.ui.tabs.get("general").setDisplayState("collapsed");

Contrae la pestaña General.

Determinar si una pestaña está visible

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetVisible

var isGeneralTabVisible = Xrm.Page.ui.tabs.get("general").getVisible();

Asigna un valor Boolean a la variable isGeneralTabVisible que indica si la pestaña General está visible.

Ocultar o mostrar una pestaña

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetVisible

Xrm.Page.ui.tabs.get("general").setVisible(false);

Oculta la pestaña General.

Obtener la etiqueta de una pestaña

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetLabel

var generalTabLabel = Xrm.Page.ui.tabs.get("general").getLabel();

Asigna la etiqueta de la pestaña General a la variable generalTabLabel.

Cambiar la etiqueta de una pestaña

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetLabel

Xrm.Page.ui.tabs.get("general").setLabel("Major");

Cambia la etiqueta de la pestaña General a Principal.

Establecer el enfoque en una pestaña

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetFocus

Xrm.Page.ui.tabs.get("general").setFocus();

Establece el enfoque en la pestaña General.

Obtener el nombre de una pestaña

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetName

var firstTabName = Xrm.Page.ui.tabs.get(0).getName();

Asigna el nombre de la primera pestaña a la variable firstTabName.

Obtener la pestaña principal de una sección

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetParent

Xrm.Page.getControl("industrycode").getParent().getParent().setFocus();

Establece el enfoque en la pestaña que contiene el campo Sector.

Determinar si una sección está visible

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetVisible

var industrySectionVisible = Xrm.Page.getControl("industrycode").getParent().getVisible();

Asigna un valor Boolean a la variable industrySectionVisible que indica si la sección que contiene el campo Sector está visible.

Ocultar o mostrar una sección

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetVisible

Xrm.Page.getControl("industrycode").getParent().setVisible(false);

Oculta la sección que contiene el campo Sector.

Obtener la etiqueta de una sección

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_getLabel

var industryFieldSectionLabel = Xrm.Page.getControl("industrycode").getParent().getLabel();

Asigna la etiqueta de la sección que contiene el campo Sector a la variable industryFieldSectionLabel.

Cambiar la etiqueta de una sección

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetLabel

Xrm.Page.getControl("industrycode").getParent().setLabel("Detailed Information");

Cambia la etiqueta de la sección que contiene el campo Sector a Información detallada.

En este tema

Agregar o quitar controladores de eventos en tiempo de ejecución

Normalmente, los controladores de eventos se configuran con el editor de formularios de la aplicación, pero también puede agregarlos al evento OnSave del formulario y los eventos OnChange del atributo en tiempo de ejecución mediante estas APIs. Los ejemplos de esta sección harán referencia a la siguiente definición de función:
function myFunction() {
//perform action here
}

Aunque puede agregar una función anónima, la función debe tener un nombre para hacer referencia a fin de quitarla.

Tarea

Método

Ejemplo

Agregar una función al evento OnSave.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_addOnSave

Xrm.Page.data.entity.addOnSave(myFunction);

Agregar la función myFunction al evento OnSave.

Quitar una función del evento OnSave.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_removeOnSave

Xrm.Page.data.entity.removeOnSave(myFunction);

Quitar la función myFunction del evento OnSave.

Agregar una función al evento OnChange de un atributo.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_addOnChange

Xrm.Page.getAttribute("name").addOnChange(myFunction);

Agregar la función myFunction al evento OnChange del campo Nombre de cuenta.

Quitar una función del evento OnChange de un atributo.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_removeOnChange

Xrm.Page.getAttribute("name").removeOnChange(myFunction);

Quitar la función myFunction del evento OnChange del campo Nombre de cuenta.

Agregar una función al evento PreSearch de un control de búsqueda.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addPreSearch

El siguiente ejemplo de código es para la búsqueda de Cuenta del formulario de oportunidad (parentaccountid). Cuando la función Sdk.setParentAccountIdFilter se establece en el controlador de eventos de Onload del formulario, la función Sdk.filterCustomAccounts se agrega al evento PreSearch para esa búsqueda. El resultado es que solo se devuelven las cuentas con el valor Categoría (accountcategorycode) de Cliente preferido (1).

  var Sdk = window.Sdk || {};

  Sdk.filterCustomerAccounts = function () {
      //Only show accounts with the type 'Preferred Customer'
      var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
      Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
  }
  //set 'Sdk.setParentAccountIdFilter' in the Opportunity form Onload event handler
  Sdk.setParentAccountIdFilter = function () {
      Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
  }

Use d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange y d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected para eventos que aparecen en el control de flujo de proceso de negocio. Estos eventos solo tienen métodos para agregar o quitar controladores de eventos mediante programación.Más información:Métodos para administrar controladores de eventos.

En este tema

Métodos de información contextual

Use estos métodos para obtener información del usuario, la organización y el cliente. La siguiente tabla proporciona algunos de los métodos de contexto más útiles. Para todos los métodos de contexto, consulte Contexto del lado del cliente (referencia del lado del cliente).

Tarea

Método

Ejemplo

Obtener la URL para conectarse con la organización.

getClientUrl

var serverUrl = Xrm.Page.context.getClientUrl();

Asignar una cadena que represente la URL a la variable serverUrl.

Obtener el identificador único del usuario actual.

getUserId

var userId = Xrm.Page.context.getUserId();

Asignar una cadena que represente el identificador del usuario a la variable userId.

Obtener el nombre del usuario actual.

getUserName

var userName = Xrm.Page.context.getUserName();

Asignar una cadena que represente el nombre del usuario a la variable userName.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Obtener el código de idioma que representa el idioma de interfaz de usuario preferido del usuario.

getUserLcid

var userLCID = Xrm.Page.context.getUserLcid();

Asignar un número que indique el idioma preferido del usuario a la variable userLCID.

Obtener una matriz de cadenas que represente los valores de GUID de cada rol de seguridad asignado al usuario actual y a cualquier equipo al que está asociado el usuario.

getUserRoles

var userRoles = Xrm.Page.context.getUserRoles();

Asignar una matriz de cadenas que represente los roles de seguridad del usuario a la variable userRoles.

Determinar si el script se ejecuta en el cliente de Microsoft Dynamics 365 para Outlook.

cliente.getClient

var isOutlookClient = (Xrm.Page.context.client.getClient() == "Outlook");

Asignar un valor Boolean que represente si el código se ejecuta en el cliente de Dynamics 365 para Outlook a la variable isOutlookClient.

Determinar si el usuario trabaja sin conexión con el cliente de Microsoft Dynamics 365 para Microsoft Office Outlook con acceso sin conexión.

cliente.getClientState

var IsOffline = (Xrm.Page.context.client.getClientState() == "Offline");

Asignar un valor Boolean que represente si el usuario trabaja actualmente sin conexión a la variable IsOffline.

En este tema

Obtener, actualizar, o guardar datos de entidad

La siguiente tabla contiene los métodos que puede usar para obtener información sobre el registro actual o guardar cambios. Para obtener más información, vea Xrm.Page.data.entity (referencia del lado del cliente) y Xrm.Page.data (referencia del lado del cliente).

Tarea

Método

Ejemplo

Obtener el nombre lógico de la entidad actual

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getEntityName

var entityName = Xrm.Page.data.entity.getEntityName();

Asignar el nombre lógico de la entidad a la variable entityName.

Obtener el valor del atributo principal de la entidad actual.
El atributo principal es el valor que se utiliza para identificar el registro. Por ejemplo contact.fullname.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getPrimaryAttributeValue

var primaryAttributeValue = Xrm.Page.data.entity.getPrimaryAttributeValue();

Asignar el valor del atributo principal a la variable primaryAttributeValue .

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Obtener el Id del registro actual

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getId

var recordId = Xrm.Page.data.entity.getId();

Asignar el id del registro a la variable recordId.

Actualizar asincrónicamente los datos del formulario sin volver a cargar la página.

ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_refresh

Xrm.Page.data.refresh();

Actualiza los datos en el formulario.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Guardar el registro actual

Xrm.Page.data.entity.fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_save

Xrm.Page.data.entity.save();

Guarda el registro. Existen argumentos opcionales. Use saveandclose o saveandnew para realizar acciones equivalentes.

Guardar el registro actual asincrónicamente con la opción para configurar
las funciones de devolución de llamada para que se ejecuten una vez finalizada la operación de guardar.

Xrm.Page.data.ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_dataSave

Xrm.Page.data.save().then(
function(){
Xrm.Utility.alertDialog("Record saved");
},
function(error){
Xrm.Utility.alertDialog(error.message);
});

Guarda el registro y muestra un mensaje que indica el estado de la operación de guardar.

Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Determinar si algún dato del registro actual ha cambiado.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getIsDirty

var isDirty = Xrm.Page.data.entity.getIsDirty();

Asignar un valor Boolean que represente si los datos del registro han cambiado a la variable isDirty.

Obtener una cadena que represente los datos que se enviarán al servidor cuando se guarda el registro.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getDataXml

var dataXml = Xrm.Page.data.entity.getDataXml();

Asignar una cadena que represente los datos que se van a guardar a la variable dataXml.

En este tema

Ver también

Use el modelo de objeto Xrm.Page
Escriba código para formularios de Microsoft Dynamics 365
Referencia de programación del lado del cliente

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright