Control Xrm.Page.ui (referencia de cliente)
Publicado: noviembre de 2016
Se aplica a: Dynamics CRM 2015
El objeto de control proporciona métodos para cambiar la presentación o el comportamiento de un control e identificar el atributo correspondiente.
El acceso a los controles se realiza utilizando las colecciones siguientes: Xrm.Page.ui.controles, Xrm.Page.ui Section.controles o Xrm.Page.data.entity Attribute.controles. El método Xrm.Page.getControl es un método abreviado para tener acceso a Xrm.Page.ui.controls.get.
Los ejemplos de sintaxis de este tema muestran el uso del método de Xrm.Page.getControl para tener acceso a un control. El control depende de los argumentos que se han pasado al método. El parámetro args para tener acceso a un único control debe ser el nombre del control o del índice.
Cuando un formulario muestra un control de flujo de proceso de negocio en el encabezado, se agregarán controles adicionales para cada atributo que se muestra en el flujo de proceso de negocio. Estos controles tienen un nombre único similar al ejemplo siguiente: header_process_<attribute name>.
Nota
Sólo se puede acceder a los controles de la fase activa del flujo de proceso de negocio por su nombre de esta forma.
Los controles mostradas en el encabezado del formulario están accesibles y tienen un nombre único como el siguiente: header_<attribute name>.
Para controles que están enlazados a atributos es común acceder a los controles a través de la colección de Xrm.Page.data.entity Attribute.controles.
Propiedades y métodos de controles
Deshabilitado
Detecte el estado y habilite o deshabilite los controles utilizando los métodos getDisabled y setDisabled.getAttribute
Obtenga el atributo con el que está enlazado el control.getControlType
Obtenga información acerca del tipo de control.getName
Obtenga el nombre del control.getParent
Obtenga el objeto de sección en el que está el control.Métodos de control de knowledge base
Estos métodos solo están disponibles para el control búsqueda de knowledge base disponible cuando la organización de Microsoft Dynamics CRM Online está integrada con Parature. Estos métodos se introdujeron con Actualización 1 de Microsoft Dynamics CRM Online 2015.Para obtener información sobre estos controles, consulte Control de búsqueda de knowledge base de Parature (referencia del lado del cliente).
Etiqueta
Obtenga o cambie la etiqueta de un control con los métodos getLabel y setLabel.Métodos y eventos de control de búsqueda
Controle los resultados que se muestran para que un usuario elija cuando establece el valor de un control de búsqueda utilizando los métodos addCustomFilter, addCustomView, getDefaultView, setDefaultView.Puede agregar o quitar controladores de eventos para el Evento PreSearch mediante los métodos addPreSearch y removePreSearch.
Notificación
Muestre y quite notificaciones a los usuarios sobre control utilizando los métodos setNotification y clearNotification.Métodos de control de OptionSet
Modifique las opciones que aparecen en los controles de OptionSet mediante los métodos addOption, clearOptions y removeOption.ShowTime
Use setShowTime para especificar si un control de fecha debe mostrar la parte de hora de la fecha y getShowTime para determinar si se muestra actualmente la parte de hora de la fecha.Métodos de control de subcuadrícula
Para las organizaciones con Actualización 1 de CRM Online 2015 hay nuevas capacidades para trabajar con controles de subcuadrícula.Más información:Objetos y métodos de cuadrícula (referencia del lado del cliente)Para otras organizaciones, el método refresh es el único método disponible para los controles de subcuadrícula. Este método actualizará los datos que se muestran en la subcuadrícula.
Visible
Determine qué controles son visibles y muéstrelos u ocúltelos mediante los métodos getVisible y setVisible.Métodos de controles IFRAME y recursos web
Interactúe con controles de recursos web e IFRAME mediante los métodos getData, setData, getInitialUrl, getObject, setSrc y getSrc.
Deshabilitado
Use getDisabled y setDisabled para detectar si un control está deshabilitado o para habilitarlo o deshabilitarlo.
Tipos de control: estándar, búsqueda, optionset.
getDisabled
Devuelve si el control está deshabilitado.
Xrm.Page.getControl(arg).getDisabled()
- Valor devuelto
Tipo: Booleano. True si el control está deshabilitado; False de lo contrario.
setDisabled
Establece si el control está deshabilitado.
Xrm.Page.getControl(arg).setDisabled(bool)
- Argumentos
Tipo: Booleano. True si el control debe deshabilitarse; False de lo contrario.
getAttribute
Devuelve el atributo con el que está enlazado el control.
Tipos de control: estándar, búsqueda, optionset.
Xrm.Page.getControl(arg).getAttribute()
Nota
Los controles que no están enlazados a un atributo (subcuadrícula, recurso web, e IFRAME) no tienen este método. Se generará un error si intenta usar este método en uno de estos controles.
- Valor devuelto
Tipo: Objeto: Un atributo.
Comentarios
Los controles constituyentes en un control de vista rápida se incluyen en la colección de controles y estos controles tienen el método getAttribute. Sin embargo, el atributo no es parte de la colección de atributos de la entidad. Aunque puede recuperar el valor de ese atributo mediante getValue e incluso cambiar el valor mediante setValue, los cambios realizados no se guardarán con la entidad.
El código siguiente muestra el uso del valor del atributo mobilephone de contacto cuando se muestra en un formulario de entidad de cuenta utilizando un control de vista rápida distintas llamado contactQuickForm. Este código ocultará el control cuando el valor del atributo es null.
var quickViewMobilePhoneControl = Xrm.Page.getControl("contactQuickForm_contactQuickForm_contact_mobilephone");
if (quickViewMobilePhoneControl.getAttribute().getValue() == null)
{
quickViewMobilePhoneControl.setVisible(false);
}
getControlType
Devuelve un valor que categoriza los controles.
Tipos de control: todos.
Xrm.Page.getControl(arg).getControlType()
Valor devuelto
Tipo: CadenaPosibles valores de devolución de getControlType:
Valor de retorno
Descripción
standard
Un control estándar.
iframe
Un control de IFRAME
lookup
Un control de búsqueda.
optionset
Un control de conjunto de opciones.
subgrid
Un control de subcuadrícula.
webresource
Un control de recurso web.
notes
Un control de notas.
timercontrol
Un control de temporizador.
kbsearch
Control de búsqueda de knowledge base.
getName
Devuelve el nombre asignado al control.
Nota
El nombre asignado a un control no se determina hasta que el formulario se carga. Los cambios en el formulario pueden cambiar el nombre asignado a un determinado control.
Tipos de control: todos.
Xrm.Page.getControl(arg).getName()
- Valor devuelto
Tipo: Cadena. El nombre del control.
getParent
Devuelve una referencia al objeto de sección que contiene el control.
Tipos de control: todos.
Xrm.Page.getControl(arg).getParent()
- Valor devuelto
Tipo: Objeto Sección Xrm.Page.ui (referencia del lado del cliente).
Métodos de control de knowledge base
Estos métodos solo están disponibles para el control búsqueda de knowledge base disponible cuando la organización de Microsoft Dynamics CRM Online está integrada con Parature. Estos métodos se introdujeron con Actualización 1 de Microsoft Dynamics CRM Online 2015.
Para obtener información sobre estos controles, consulte Control de búsqueda de knowledge base de Parature (referencia del lado del cliente).
Etiqueta
Obtenga o cambie la etiqueta de un control con los métodos getLabel y setLabel.
Tipos de control: todos.
getLabel
Devuelve la etiqueta del control.
Xrm.Page.getControl(arg).getLabel()
- Valor devuelto
Tipo: Cadena. La etiqueta del control.
setLabel
Establece la etiqueta del control.
Xrm.Page.getControl(arg).setLabel(label)
- Argumentos
Tipo: Cadena. La nueva etiqueta del control.
Métodos y eventos de control de búsqueda
Controle los resultados que se muestran para que un usuario elija cuando establece el valor de un control de búsqueda utilizando los métodos addCustomFilter, addCustomView, getDefaultView y setDefaultView. El control de Lookup también expone el Evento PreSearch para que pueda agregar controladores de eventos mediante programación utilizando los métodos addPreSearch y removePreSearch.
Tipos de Control: búsqueda.
addCustomFilter
Use para agregar filtros a los resultados mostrados en la búsqueda. Cada filtro se combinará con cualquier filtro agregado anteriormente como una condición "AND".
Xrm.Page.getControl(arg).addCustomFilter(filter, entityLogicaName)
Argumentos
filterXml
Tipo: Cadena: El elemento de filtro fetchXml a aplicar. Por ejemplo:<filter type="and"> <condition attribute="address1_city" operator="eq" value="Redmond" /> </filter>
entityLogicalName
Tipo: Cadena: (Opcional) Si se establece, el filtro solo se aplicará a ese tipo de entidad. Si no, se aplicará a todos los tipos de entidades devueltas.
Comentarios
Más información:FetchXML schema.Este método solo está disponible para Entidades actualizadas.
Este método solo se puede usar en una función en un controlador de eventos para el Evento PreSearch de control de búsqueda.
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); }
addCustomView
Agrega una vista nueva para el cuadro de diálogo de búsqueda.
Xrm.Page.getControl(arg).addCustomView(viewId, entityName, viewDisplayName, fetchXml, layoutXml, isDefault)
Argumentos
viewId
Tipo: Cadena: Representación de cadena de un GUID para una vista.Nota
Este valor nunca se guarda y solo debe ser único entre las otras vistas disponibles para la búsqueda. Funcionará una cadena para un GUID no válido, por ejemplo “{00000000-0000-0000-0000-000000000001}”. Se recomienda usar una herramienta como guidgen.exe para generar un GUID válido. La herramienta guidgen.exe se incluye en el Windows SDK.
entityName
Tipo: Cadena: El nombre de la entidad.viewDisplayName
Tipo: Cadena: El nombre de la vista.fetchXml
Cadena: La consulta de fetchXml para la vista.layoutXml
Tipo: Cadena: El XML que define el diseño de la vista.es predeterminada
Tipo: Booleano: Si la vista debe ser la vista predeterminada.
- Comentarios
Este método no funciona en búsquedas Propietario. Las búsquedas de propietario se usan para asignar registros propiedad del usuario.
DefaultView
Puede detectar qué vista es la vista predeterminada que se muestra para permitir a los usuarios seleccionar registros en una búsqueda y cambiar la vista predeterminada mediante getDefaultView y setDefaultView.
getDefaultView
Devuelve el valor de identificador de la vista predeterminada del diálogo de búsqueda.
Xrm.Page.getControl(arg).getDefaultView()
- Valor devuelto
Tipo: Cadena. El valor del identificador de la vista predeterminada.
setDefaultView
Establece la vista predeterminada para el cuadro de diálogo de control de búsqueda.
Xrm.Page.getControl(arg).setDefaultView(viewGuid)
- Argumentos
Tipo: Cadena. El identificador de la vista que se establecerá como vista predeterminada.
Ejemplo: Esta función de setDefaultViewSample establecerá la vista predeterminada de búsqueda de contacto principal del formulario de entidad account en la vista Mis contactos activos.
function setDefaultViewSample() {
Xrm.Page.getControl("primarycontactid").setDefaultView("{00000000-0000-0000-00AA-000010001003}");
}
Evento PreSearch
Puede agregar o quitar controladores de eventos para el Evento PreSearch de control de búsqueda mediante los métodos addPreSearch y removePreSearch.
Use el evento PreSearch para controlar qué resultados se muestran para el control utilizando los datos de formulario actuales mientras el usuario comienza a buscar registros.
Ambos métodos tienen el Contexto de ejecución (referencia del lado del cliente) pasado como primer parámetro.
addPreSearch
Use este método para aplicar cambios a búsquedas basadas en valores actuales mientras el usuario está a punto de ver los resultados de la búsqueda.
Xrm.Page.getControl(arg).addPreSearch(handler)
Argumentos
Tipo: Función a agregar.Comentarios
Este método solo está disponible para Entidades actualizadas.
El argumento es una función que se ejecutará justo antes de que se produzca la búsqueda para proporcionar resultados para una búsqueda. Puede usar este controlador para llamar a una de las otras funciones de control de búsqueda y mejorar los resultados que se mostrarán en la búsqueda.
removePreSearch
Use este método para quitar las funciones del controlador de eventos que se han establecido anteriormente para el evento PreSearch.
Xrm.Page.getControl(arg).removePreSearch(handler)
Argumentos
Tipo: Función a quitar.Comentarios
Este método solo está disponible para Entidades actualizadas.
Notificación
Use setNotification para mostrar una notificación sobre el control y clearNotification para quitarlo.
setNotification
Mostrar un mensaje cerca del control para indicar que los datos no son válidos. Cuando se usa este método en Microsoft Dynamics CRM para tabletas, aparece un icono "X" rojo junto al control. Si pulsa en el icono se mostrará el mensaje.
Xrm.Page.getControl(arg).setNotification(message,uniqueId)
Comentarios
Establecer una notificación en un control impedirá que se guarde el formulario.
Este método solo está disponible para Entidades actualizadas.
Argumentos
mensaje
Tipo: Cadena: El mensaje para mostrar.uniqueId
Tipo: Cadena: El identificador que se usará para borrar sólo este mensaje al usar clearNotification.
Valor devuelto
Tipo: Booleano: Indica si el método se realizó correctamente.
clearNotification
Eliminar un mensaje que ya se muestra para un control.
Xrm.Page.getControl(arg).clearNotification(uniqueId)
Argumentos
uniqueId
Tipo: Cadena: El identificador que se usará para borrar un conjunto de mensajes específicos usando setNotification.Si no se usa el parámetro uniqueId, se quitará la notificación actual mostrada.
Comentarios
Este método solo está disponible para Entidades actualizadas.
Valor devuelto
Tipo: Booleano: Indica si el método se realizó correctamente.
Métodos de control de OptionSet
Use los métodos addOption, clearOptions y removeOption para manipular las opciones disponibles para los controles OptionSet. Para un ejemplo de estas funciones en uso, vea Ejemplo: crear OptionSets (listas desplegables) dependientes.
addOption
Agrega una opción al control de un conjunto de opciones.
Xrm.Page.getControl(arg).addOption(option, [index])
Importante
Este método no comprueba si los valores en las opciones que agregue son válidos. Si agrega opciones no válidas no funcionarán correctamente. Debe agregar sólo las opciones que se han definido para el atributo del conjunto de opciones específico con el que está enlazado el control. Use el atributo getOptions o los métodos getOption para conseguir objetos de opción válidos para agregar mediante este método.
Argumentos
opción
Tipo: Objeto: Un objeto de opción para agregar al OptionSet.index
Tipo: Número: (Opcional) La posición de índice para poner la nueva opción. Si no se proporciona, la opción se agregará al final.
clearOptions
Borra todas las opciones de un control de conjunto de opciones.
Xrm.Page.getControl(arg).clearOptions()
removeOption
Quita una opción de un control de conjunto de opciones.
Xrm.Page.getControl(arg).removeOption(number)
- Argumentos
Tipo: Número: El valor de la opción que desea quitar.
setFocus
Establece el enfoque en el control.
Xrm.Page.getControl(arg).setFocus()
ShowTime
Use setShowTime para especificar si un control de fecha debe mostrar la parte de hora de la fecha y con Actualización 1 de Microsoft Dynamics CRM Online 2015 o posterior, use getShowTime para determinar si se muestra actualmente la parte de hora de la fecha.
getShowTime
Obtenga si un control de fecha muestra la parte de hora de la fecha.
Tipos de control: control estándar para los atributos datetime.
var showsTime = Xrm.Page.getControl(arg).getShowTime();
Comentarios
Este método se introdujo con Actualización 1 de Microsoft Dynamics CRM Online 2015.
setShowTime
Especifique si un control de fecha debe mostrar la parte de hora de la fecha.
Tipos de control: control estándar para los atributos datetime.
Xrm.Page.getControl(arg).setShowTime(bool)
Comentarios
Este método solo está disponible para Entidades actualizadas. Este método mostrarán u ocultará el componente de hora de un control de fecha donde el atributo usa el formato DateAndTime. Este método no tendrán efecto cuando se use el formato de DateOnly.
Métodos de control de subcuadrícula
Para los versiones anteriores a Actualización 1 de Microsoft Dynamics CRM Online 2015 el único método disponible para un control de subcuadrícula es refresh. Con Actualización 1 de CRM Online 2015 hay nuevas funciones que puede usar.Más información:Objetos y métodos de cuadrícula (referencia del lado del cliente)
refresh
Actualiza los datos mostrados en una subcuadrícula.
Xrm.Page.getControl(arg).refresh()
Nota
El método de actualización no está disponibles en el formulario Evento OnLoad porque las subcuadrículas se cargan asincrónicamente. Con la subcuadrícula Evento OnLoad introducida en Actualización 1 de CRM Online 2015 ahora puede detectar cuando la subcuadrícula se carga y usar este método con los controladores de eventos para ese evento.
Visible
Determine qué controles son visibles y muéstrelos u ocúltelos mediante los métodos getVisible y setVisible.
getVisible
Devuelve un valor que indica si el control está visible actualmente.
Nota
Si la sección o la pestaña que contiene este control no está visible, este método aún puede devolver true. Para asegurarse de que el control realmente sea visible; también debe comprobar la visibilidad de los elementos que contiene.
Xrm.Page.getControl(arg).getVisible()
- Valor devuelto
Tipo: Booleano.True si el control está visible; false de lo contrario.
setVisible
Establece un valor que indica si el control está visible.
Xrm.Page.getControl(arg).setVisible(bool)
- Argumentos
Tipo: Booleano.True si el control debe ser visible; false de lo contrario.
Nota
Cuando muestra selectivamente campos a los usuarios en código que se ejecuta en el evento Onload, se recomienda configurar los campos para que no sean visibles de forma predeterminada y luego usar setVisible(true) para mostrar los campos cuando se dan las condiciones. El uso de setVisible(false) para ocultar campos en el evento Onload puede provocar que el campo aparezca brevemente al usuario antes de ocultarse.
Si está ocultando un mayor número de campos mediante setVisible(false), piense si puede agruparlos en pestañas o secciones y ocultar la pestaña o la sección en lugar de los campos de manera independiente. Esto puede mejorar el rendimiento.
Métodos de controles IFRAME y recursos web
Utilice estos métodos para interactuar con controles de recursos web e IFRAME.
Nota
Estos métodos no funcionan con Microsoft Dynamics CRM para tabletas.
Datos
Los recursos Web tienen un parámetro de cadena de consulta especial llamado data para transmitir datos personalizados. Los métodos getData y setData funcionan sólo para los recursos web de Silverlight agregados a un formulario.Más información:Paso de datos de un formulario a un recurso web de Silverlight incrustado
Para los recursos web de página web (HTML), el parámetro de datos puede extraerse desde el método getSrc o establecerse mediante el método setSrc.
getData
Devuelve el valor del parámetro de la cadena de consulta de datos pasado un recurso web de Silverlight.
Xrm.Page.getControl(arg).getData()
- Valor devuelto
Tipo: Cadena. El valor de datos pasado al recurso web de Silverlight.
setData
Establece el valor del parámetro de la cadena de consulta de datos pasado un recurso web de Silverlight.
Xrm.Page.getControl(arg).setData(string)
- Argumentos
Tipo: Cadena. El valor de datos para pasar al recurso web de Silverlight.
getInitialUrl
Devuelve la dirección URL predeterminada que un control de IFRAME está configurado para mostrar. Este método no está disponible para recursos web.
Xrm.Page.getControl(arg).getInitialUrl()
- Valor devuelto
Tipo: Cadena. La dirección URL inicial.
getObject
Devuelve el objeto del formulario que representa el recurso web o I-frame.
Xrm.Page.getControl(arg).getObject()
Valor devuelto
Tipo: Objeto. El objeto depende del tipo de control.Un IFRAME devuelve el elemento IFrame del Document Object Model (DOM).
Un recurso web de Silverlight devolverá el elemento Objeto del DOM que representa el complemento Silverlight incrustado.
Src
Los IFRAMEs o recursos web tienen una propiedad src para definir qué mostrar en la ventana incrustada. Puede obtener o cambiar la propiedad src con los métodos getSrc y setSrc.
getSrc
Devuelve la dirección URL actual que se muestra en un recurso web o IFRAME.
Xrm.Page.getControl(arg).getSrc()
- Valor devuelto
Tipo: Cadena. Una dirección URL que representa la propiedad src del recursos web o IFRAME.
setSrc
Establece la dirección URL que se muestra en un recurso web o IFRAME.
Xrm.Page.getControl(arg).setSrc(string)
- Argumentos
Tipo: Cadena: La dirección URL.
Ver también
Referencia de programación del lado del cliente
Referencia de scripting de formularios
Xrm.Page.ui (referencia del lado del cliente)
Escriba código para formularios de Microsoft Dynamics CRM 2015
Use el modelo de objeto Xrm.Page
© 2017 Microsoft. Todos los derechos reservados. Copyright