Control Xrm.Page.ui (referencia de cliente)

  • Artículo

 

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: Cadena

    Posibles 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()

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