componente de selector de Personas en Microsoft Graph Toolkit
Puede usar el mgt-people-picker componente web para buscar personas o grupos. De forma predeterminada, el componente buscará a todas las personas y usuarios de la organización, pero puede cambiar el comportamiento para buscar también grupos o solo grupos. También puede filtrar la búsqueda a un grupo específico. Además, puede permitir que el usuario escriba y seleccione cualquier dirección de correo electrónico.
Ejemplo:
En el ejemplo siguiente se muestra el mgt-people-picker componente . Empiece a buscar un nombre para ver la representación de los resultados y use el editor de código para ver cómo cambian las propiedades el comportamiento del componente.
Propiedades
De forma predeterminada, el mgt-people-picker componente captura personas de los /me/people puntos de conexión y /users . Use los atributos siguientes para cambiar este comportamiento.
| Atributo | Propiedad | Descripción |
|---|---|---|
| show-max | showMax | Valor numérico que indica el número máximo de personas que se van a mostrar. el valor predeterminado es 6. |
| group-id | groupId | Valor de cadena que pertenece a un grupo definido por Microsoft Graph para filtrar aún más los resultados de la búsqueda. |
| transitive-search | transitiveSearch | Valor booleano para realizar una búsqueda transitiva que devuelve una lista plana de todos los miembros anidados; de forma predeterminada, no se usa la búsqueda transitiva. |
| type | type | Tipo de entidades que se van a buscar. Las opciones disponibles son: person, group, any. El valor predeterminado es person. Este atributo no tiene ningún efecto si group-id se establece la propiedad . |
| tipo de usuario | userType | Tipo de usuario que se va a buscar. Las opciones disponibles son: any, user para usuarios de la organización o contact para contactos. El valor predeterminado es any. |
| group-type | groupType | Tipo de grupo que se va a buscar. Las opciones disponibles son : unified, security, mailenabledsecurity, , distribution. any El valor predeterminado es any. Este atributo no tiene ningún efecto si la type propiedad está establecida en person. |
| personas seleccionadas | selectedPeople | Matriz de personas seleccionadas. Establezca este valor para seleccionar personas mediante programación. |
| people | people | Matriz de personas encontradas y representadas en el resultado de la búsqueda |
| Marcador | Marcador | Texto predeterminado que parece explicar cómo usar el componente. El valor predeterminado es Start typing a name. |
| default-selected-user-ids | defaultSelectedUserIds | Cuando se proporciona una cadena de identificadores de usuario de Microsoft Graph separados por comas, el componente representa los usuarios respectivos como seleccionados tras la inicialización. |
| default-selected-group-ids | defaultSelectedGroupIds | De forma similar a default-selected-user-ids, cuando se proporciona una cadena de identificadores de grupo de Microsoft Graph separados por comas, el componente representa los grupos respectivos como seleccionados tras la inicialización. |
| modo de selección | selectionMode | Se usa para indicar si se permite seleccionar varios elementos (usuarios o grupos) o solo un solo elemento. Las opciones disponibles son: single, multiple. El valor predeterminado es multiple. |
| deshabilitado | deshabilitado | Establece si el selector de personas está deshabilitado. Cuando está deshabilitado, el usuario no puede buscar ni seleccionar personas. |
| disable-images | disableImages | Establece si se va a deshabilitar la captura y la visualización de imágenes de personas. Cuando se establece en true, se muestran las iniciales de usuario en su lugar. |
| allow-any-email | allowAnyEmail | Indica si el selector de personas puede aceptar direcciones de correo electrónico sin seleccionar una persona. El valor predeterminado es false. Cuando termine de escribir una dirección de correo electrónico, puede presionar coma (,), punto y coma (;), tabulador o escribir teclas para agregarla. |
| user-ids | userIds | Cadena de identificadores de usuario separados por comas. Solo aparecerán en el menú desplegable o en los resultados de la búsqueda cuando escriba una consulta. Por ejemplo 48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d , solo se mostrarán los dos usuarios en la lista desplegable cuando se centre la entrada. Al escribir un texto de búsqueda, devolverá resultados que coincidan solo con los usuarios de los dos identificadores de usuario. |
| filtros de usuario | userFilters | Especifica los criterios de filtro que se usarán al consultar el punto de conexión de los usuarios. Requiere que user-type se establezca user en o contact. De forma predeterminada, es user-typeany y esto lleva a que la consulta tenga lugar en el bloque de people puntos de conexión. Ejemplo: user-filters="startsWith(displayName,'a')". Este atributo es opcional. Obtenga más información sobre la compatibilidad con el filtro en las propiedades de usuario de los objetos de directorio de Azure AD. |
| group-filters | groupFilters | Especifica los criterios de filtro que se usarán al consultar el groups punto de conexión. Requiere que se establezca en typegroup. Ejemplo: group-filters="startsWith(displayName,'a')". Este atributo es opcional. |
| people-filters | peopleFilters | Especifica los criterios de filtro que se usarán al consultar el people punto de conexión. Se usa tal y como está. Ejemplo: people-filters="jobTitle eq 'Web Marketing Manager'". Este atributo es opcional. Obtenga más información sobre el filtrado y las funcionalidades admitidas en el recurso people. |
| group-ids | groupIds | Cadena de identificadores de grupo separados por comas. Los resultados disponibles deben limitarse a los grupos especificados. Los usuarios que aparecerán en el menú desplegable y a través de la experiencia de búsqueda solo deben proceder de los identificadores de grupo especificados. Por ejemplo, 02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23 solo mostrará los usuarios que pertenecen a estos grupos. Al escribir un texto de búsqueda, devolverá resultados que coincidan solo con los usuarios de los dos identificadores de grupo. Esta propiedad no se usa si group-id está definida. Si se establece la propiedad , es group de type forma predeterminada y transitive-search es true de forma predeterminada. group-type Si se establece con la propiedad , type puede ser any o group. type Si es person, no se usa la propiedad . |
| aria-label | ariaLabel | Cadena proporcionada para ayudar a las tecnologías asimilativas a proporcionar contexto para el selector de personas. |
A continuación se muestra un show-max ejemplo.
<mgt-people-picker show-max="4"> </mgt-people-picker>
Personas seleccionadas
La sección personas seleccionadas del componente representa cada persona elegida por el desarrollador o usuario.
Para rellenar los datos de personas seleccionados, realice una de las siguientes acciones:
Establecer la
selectedPeoplepropiedad directamente, como se muestra en el ejemplo siguiente.// personObject = User or Person from Microsoft Graph document.querySelector('mgt-people-picker').selectedPeople.push(personObject);Mediante el
selectUsersById()método , que acepta una matriz de identificadores de usuario de Microsoft Graph para buscar los detalles de usuario asociados para la selección.Nota: Si no se encuentra ningún usuario para ,
idno se representarán datos para eseid.// id = Microsoft graph User "id" document.querySelector('mgt-people-picker').selectUsersById(["id","id"])Mediante el
selectGroupsById()método , que acepta una matriz de identificadores de grupo de Microsoft Graph para buscar los grupos con los usuarios asociados.// groupid = Microsoft graph group "id" document.querySelector('mgt-people-picker').selectGroupsById(["groupid","groupid"])
Eventos
Los siguientes eventos se desencadenan desde el componente.
| Evento | Cuándo se emite | Datos personalizados | Cancelable | Burbujas | Funciona con una plantilla personalizada |
|---|---|---|---|---|---|
selectionChanged |
El usuario agregó o quitó una persona de la lista de personas seleccionadas o seleccionadas. | Matriz de personas seleccionadas, donde una persona puede ser un usuario de Graph, una persona o un contacto con una propiedad adicional personImage que contiene la dirección URL de la foto del usuario. |
No | No | Sí, a menos que invalide la plantilla predeterminada. |
Para obtener más información sobre el control de eventos, vea eventos.
Propiedades personalizadas css
El mgt-people-picker componente define las siguientes propiedades personalizadas CSS.
mgt-people-picker {
--input-border: 2px rgba(255, 255, 255, 0.5) solid; /* sets all input area border */
/* OR individual input border sides */
--input-border-bottom: 2px rgba(255, 255, 255, 0.5) solid;
--input-border-right: 2px rgba(255, 255, 255, 0.5) solid;
--input-border-left: 2px rgba(255, 255, 255, 0.5) solid;
--input-border-top: 2px rgba(255, 255, 255, 0.5) solid;
--input-background-color: #1f1f1f; /* input area background color */
--input-border-color--hover: #008394; /* input area border hover color */
--input-border-color--focus: #0f78d4; /* input area border focus color */
--dropdown-background-color: #ca00ca; /* selection area background color */
--dropdown-item-hover-background: purple; /* person background color on hover */
--dropdown-item-text-color: white; /* person item text color */
--dropdown-item-text-hover-color: gold; /* person item text color on hover */
--selected-person-background-color: #f1f1f1; /* person item background color */
--color: white; /* input area border focus color */
--placeholder-color: #f1f1f1; /* placeholder text color */
--placeholder-color--focus: rgba(255, 255, 255, 0.8); /* placeholder text focus color */
}
Plantillas
mgt-people-picker admite varias plantillas que puede usar para reemplazar ciertas partes del componente. Para especificar una plantilla, incluya un <template> elemento dentro de un componente y establezca el data-type valor en uno de los siguientes.
| Tipo de datos | Contexto de datos | Descripción |
|---|---|---|
| Es el valor predeterminado. | null: sin datos | Plantilla usada para invalidar la representación de todo el componente. |
| Carga | null: sin datos | Plantilla usada para representar el estado del selector mientras se realiza la solicitud al gráfico. |
| error | null: sin datos | Plantilla usada si la búsqueda de usuarios no devuelve ningún usuario. |
| sin datos | null: sin datos | Una plantilla alternativa que se usa si la búsqueda de usuarios no devuelve ningún usuario. |
| selected-person | person: objeto de detalles de la persona | Plantilla para representar personas seleccionadas. |
| Persona | person: objeto de detalles de la persona | Plantilla para representar personas en la lista desplegable. |
En los ejemplos siguientes se muestra cómo usar la error plantilla.
<mgt-people-picker>
<template data-type="error">
<p>Sorry, no people were found</p>
</template>
</mgt-people-picker>
Permisos de Microsoft Graph
Este componente usa las siguientes API y permisos de Microsoft Graph.
| Configuración | Permiso | API |
|---|---|---|
group-id Establecer |
Personas. Read, User.Read.All, GroupMember.Read.All | /groups/${groupId}/members |
type establecido en Person o any |
People.Read | /me/people |
type establecer en Group o buscar usuarios y type establecer en Group o any |
Group.Read.All | /Grupos |
default-selected-user-ids Establecer |
User.ReadBasic.All | /Usuarios |
buscar usuarios y type establecer en Person o any |
Personas. Read, User.ReadBasic.All | /me/people, /users |
Autenticación
El control usa el proveedor de autenticación global descrito en la documentación de autenticación.
Caché
| Almacén de objetos | Datos almacenados en caché | Comentarios |
|---|---|---|
groups |
Lista de grupos | Se usa cuando type se establece en PersonType.group |
people |
Lista de personas | Se usa cuando type se establece en PersonType.person o PersonType.any |
users |
Lista de usuarios | Se usa cuando groupId se especifica |
Consulte Almacenamiento en caché para obtener más información sobre cómo configurar la memoria caché.
Ampliar para obtener más control
Para escenarios más complejos o una experiencia de usuario realmente personalizada, este componente expone varios protected render* métodos para invalidar en extensiones de componente.
| Método | Descripción |
|---|---|
| renderInput | Representa el cuadro de texto de entrada. |
| renderSelectedPeople | Representa los tokens de personas seleccionados. |
| renderSelectedPerson | Representa un token de persona individual. |
| renderFlyout | Representa el cromo del control flotante. |
| renderFlyoutContent | Representa el estado adecuado en el control flotante de resultados. |
| renderLoading | Representa el estado de carga. |
| renderNoData | Representa el estado cuando no se encuentra ningún resultado para la consulta de búsqueda. |
| renderSearchResults | Representa la lista de resultados de búsqueda. |
| renderPersonResult | Representa un resultado de búsqueda de persona individual. |