Popovers

Documentación y ejemplos para agregar elementos emergentes de Bootstrap, como los que se encuentran en iOS, a cualquier elemento de su sitio.

Visión general

Cosas que debe saber al usar el complemento popover:

Los popovers se basan en la biblioteca de terceros Popper.js para el posicionamiento. ¡Debe incluir popper.min.js antes de bootstrap.js o usar bootstrap.bundle.min.js / bootstrap.bundle.js que contiene Popper.js para que los popovers funcionen!
Los popovers requieren el complemento de información sobre herramientas como una dependencia.
Si está construyendo nuestro JavaScript desde la fuente, requiere util.js .
Los popovers son opcionales por razones de rendimiento, por lo que debe inicializarlos usted mismo.
La longitud cero title y los content valores nunca mostrarán una ventana emergente.
Especifique container: 'body' para evitar problemas de representación en componentes más complejos (como nuestros grupos de entrada, grupos de botones, etc.).
No funcionará la activación de elementos emergentes en elementos ocultos.
Los elementos emergentes de .disabled o disabled deben activarse en un elemento contenedor.
Cuando se activan desde anclajes que se envuelven en varias líneas, los elementos emergentes se centrarán entre el ancho total de los anclajes. Úselo .text-nowrap en sus <a> s para evitar este comportamiento.
Los popovers deben estar ocultos antes de que sus elementos correspondientes se hayan eliminado del DOM.
Los popovers se pueden activar gracias a un elemento dentro de un DOM de sombra.

El efecto de animación de este componente depende de la prefers-reduced-motion consulta de medios. Consulte la sección de movimiento reducido de nuestra documentación de accesibilidad .

Sigue leyendo para ver cómo funcionan los popovers con algunos ejemplos.

Ejemplo: habilitar popovers en todas partes

Una forma de inicializar todos los elementos emergentes de una página sería seleccionarlos por su data-toggle atributo:


  $(function () {
    $('[data-toggle="popover"]').popover()
  })

Ejemplo: usar la `container` opción

Cuando tiene algunos estilos en un elemento padre que interfieren con un popover, querrá especificar un personalizado container para que el HTML del popover aparezca dentro de ese elemento.


  $(function () {
    $('.example-popover').popover({
      container: 'body'
    })
  })

Ejemplo


  <button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Cuatro direcciones

Hay cuatro opciones disponibles: alineación superior, derecha, inferior e izquierda.


  <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
    Popover on top
  </button>
  
  <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
    Popover on right
  </button>
  
  <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
  sagittis lacus vel augue laoreet rutrum faucibus.">
    Popover on bottom
  </button>
  
  <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
    Popover on left
  </button>

Descartar en el siguiente clic

Utilice el focus disparador para descartar los elementos emergentes en el siguiente clic del usuario en un elemento diferente al elemento de alternancia.

Se requiere un marcado específico para descartar en el siguiente clic

Para un comportamiento adecuado entre navegadores y plataformas, debe usar la <a> etiqueta, no la <button> etiqueta, y también debe incluir un tabindex atributo.

Dismissible popover


  <a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>


  $('.popover-dismiss').popover({
    trigger: 'focus'
  })

Elementos deshabilitados

Los elementos con el disabled atributo no son interactivos, lo que significa que los usuarios no pueden desplazarse o hacer clic en ellos para activar una ventana emergente (o información sobre herramientas). Como solución alternativa, querrá activar el popover desde un contenedor <div> o <span> anular el pointer-events elemento deshabilitado.

Para los activadores de popover deshabilitados, también puede preferir data-trigger="hover" que el popover aparezca como una retroalimentación visual inmediata para sus usuarios, ya que es posible que no esperen hacer clic en un elemento deshabilitado.


  <span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
    <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
  </span>

Uso

Habilitar popovers a través de JavaScript:


  $('#example').popover(options)

Aceleración de GPU

Los popovers a veces aparecen borrosos en dispositivos con Windows 10 debido a la aceleración de la GPU y un DPI del sistema modificado. La solución para esto en v4 es deshabilitar la aceleración de GPU según sea necesario en sus popovers.

Solución sugerida:


    Popper.Defaults.modifiers.computeStyle.gpuAcceleration = !(window.devicePixelRatio < 1.5 && /Win/.test(navigator.platform))

Hacer que los popovers funcionen para los usuarios de teclados y tecnologías de asistencia

Para permitir que los usuarios del teclado activen sus popovers, solo debe agregarlos a elementos HTML que tradicionalmente se pueden enfocar con el teclado e interactivos (como enlaces o controles de formulario). Aunque los elementos HTML arbitrarios (como <span> s) se pueden enfocar agregando el tabindex="0" atributo, esto agregará tabulaciones potencialmente molestas y confusas en elementos no interactivos para los usuarios del teclado, y la mayoría de las tecnologías de asistencia actualmente no anuncian el contenido del popover en esta situación . Además, no confíe únicamente en hover como disparador de sus popovers, ya que esto hará que sea imposible activarlos para los usuarios del teclado.

Si bien puede insertar HTML rico y estructurado en ventanas emergentes con la html opción, le recomendamos encarecidamente que evite agregar una cantidad excesiva de contenido. La forma en que funcionan actualmente los popovers es que, una vez mostrados, su contenido está vinculado al elemento disparador con el aria-describedby atributo. Como resultado, la totalidad del contenido del popover se anunciará a los usuarios de tecnología de asistencia como una transmisión larga e ininterrumpida.

Además, aunque también es posible incluir controles interactivos (como elementos de formulario o enlaces) en su ventana emergente (agregando estos elementos a los whiteList atributos y etiquetas permitidos), tenga en cuenta que actualmente la ventana emergente no administra el orden de enfoque del teclado. Cuando un usuario de teclado abre una ventana emergente, el foco permanece en el elemento disparador, y como la ventana emergente generalmente no sigue inmediatamente al disparador en la estructura del documento, no hay garantía de que avanzar / presionar TAB moverá al usuario del teclado al panel emergente. En resumen, es probable que simplemente agregar controles interactivos a un panel emergente haga que estos controles sean inalcanzables / inutilizables para los usuarios de teclado y de tecnologías de asistencia, o al menos crear un orden de enfoque general ilógico. En estos casos, considere usar un diálogo modal en su lugar.

Opciones

Las opciones se pueden pasar a través de atributos de datos o JavaScript. Para los atributos de datos, agregue el nombre de la opción a data- , como en data-animation="".

Tenga en cuenta que, por razones de seguridad sanitize , las opciones , sanitizeFn y whiteList no se pueden proporcionar utilizando atributos de datos.

Nombre	Tipo	Defecto	Descripción
animación	booleano	cierto	Aplicar una transición de atenuación CSS a la ventana emergente
envase	cadena \| elemento \| falso	falso	Agrega el popover a un elemento específico. Ejemplo: `container: 'body'` . Esta opción es particularmente útil porque le permite colocar la ventana emergente en el flujo del documento cerca del elemento de activación, lo que evitará que la ventana emergente flote lejos del elemento de activación durante un cambio de tamaño de la ventana.
contenido	cadena \| elemento \| función	''	Valor de contenido predeterminado si el `data-content` atributo no está presente. Si se proporciona una función, se llamará con su `this` referencia establecida al elemento al que está adjunto el popover.
retrasar	numero \| objeto	0	Retraso para mostrar y ocultar el popover (ms): no se aplica al tipo de disparo manual Si se proporciona un número, se aplica un retraso tanto para ocultar / mostrar La estructura del objeto es: `delay: { "show": 500, "hide": 100 }`
html	booleano	falso	Inserte HTML en el popover. Si es falso, se `text` usará el método de jQuery para insertar contenido en el DOM. Utilice texto si le preocupan los ataques XSS.
colocación	cadena \| función	'derecho'	Cómo colocar el popover - auto \| arriba \| abajo \| izquierda \| derecho. Cuando `auto` se especifica, reorientará dinámicamente el popover. Cuando se utiliza una función para determinar la ubicación, se llama con el nodo DOM de popover como primer argumento y el nodo DOM del elemento desencadenante como segundo. El `this` contexto se establece en la instancia de popover.
selector	cadena \| falso	falso	Si se proporciona un selector, los objetos popover se delegarán a los destinos especificados. En la práctica, esto se utiliza para permitir que se agreguen ventanas emergentes al contenido HTML dinámico. Vea esto y un ejemplo informativo .
modelo	cuerda	`'<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'`	HTML base para usar al crear el popover. Los popover `title` se inyectarán en el `.popover-header`. Los popover `content` se inyectarán en el `.popover-body`. `.arrow` se convertirá en la flecha del popover. El elemento contenedor más externo debe tener la `.popover` clase.
título	cadena \| elemento \| función	''	Valor de título predeterminado si el `title` atributo no está presente. Si se proporciona una función, se llamará con su `this` referencia establecida al elemento al que está adjunto el popover.
desencadenar	cuerda	'hacer clic'	Cómo se activa el popover: haga clic en \| flotar \| enfoque \| manual. Puede pasar varios factores desencadenantes; sepárelos con un espacio. `manual` no se puede combinar con ningún otro disparador.
compensar	numero \| cuerda	0	Desplazamiento del popover en relación con su objetivo. Para obtener más información, consulte los documentos de compensación de Popper.js.
fallbackPlacement	cadena \| formación	'dar la vuelta'	Permitir especificar qué posición utilizará Popper en la reserva. Para obtener más información, consulte los documentos de comportamiento de Popper.js
Perímetro	cadena \| elemento	'scrollParent'	Límite de restricción de desbordamiento del popover. Acepta los valores de `'viewport'`, `'window'`, `'scrollParent'` , o una referencia de HTMLElement (JavaScript solamente). Para obtener más información, consulte los documentos de preventOverflow de Popper.js .
desinfectar	booleano	cierto	Habilite o deshabilite la desinfección. Si se activa `'template'`, `'content'`y `'title'`se desinfectan opciones.
whiteList	objeto	Valor por defecto	Objeto que contiene atributos y etiquetas permitidos
sanitizeFn	nulo \| función	nulo	Aquí puede proporcionar su propia función de desinfección. Esto puede resultar útil si prefiere utilizar una biblioteca dedicada para realizar la desinfección.
popperConfig	nulo \| objeto	nulo	Para cambiar la configuración predeterminada de Popper.js de Bootstrap, consulte la configuración de Popper.js

Atributos de datos para popovers individuales

Las opciones para popovers individuales se pueden especificar alternativamente mediante el uso de atributos de datos, como se explicó anteriormente.

Métodos

Transiciones y métodos asincrónicos

Todos los métodos API son asincrónicos e inician una transición . Vuelven a la persona que llama tan pronto como se inicia la transición, pero antes de que finalice . Además, se ignorará una llamada a un método en un componente en transición .

Consulte nuestra documentación de JavaScript para obtener más información .

`$().popover(options)`

Inicializa popovers para una colección de elementos.

`.popover('show')`

Revela el popover de un elemento. Vuelve a la persona que llama antes de que se haya mostrado realmente el popover (es decir, antes de shown.bs.popover que ocurra el evento). Esto se considera una activación "manual" del popover. Los elementos emergentes cuyo título y contenido son de longitud cero nunca se muestran.


  $('#element').popover('show')

`.popover('hide')`

Oculta la ventana emergente de un elemento. Vuelve a la persona que llama antes de que la ventana emergente se haya ocultado (es decir, antes de hidden.bs.popover que ocurra el evento). Esto se considera una activación "manual" del popover.


  $('#element').popover('hide')

`.popover('toggle')`

Alterna la ventana emergente de un elemento. Vuelve a la persona que llama antes de que la ventana emergente se haya mostrado u oculta (es decir, antes de que ocurra el evento shown.bs.popover o hidden.bs.popover ). Esto se considera una activación "manual" del popover.


  $('#element').popover('toggle')

`.popover('dispose')`

Oculta y destruye el popover de un elemento. Los popovers que usan la delegación (que se crean usando la selector opción ) no se pueden destruir individualmente en elementos desencadenantes descendientes.


  $('#element').popover('dispose')

`.popover('enable')`

Da al popover de un elemento la capacidad de mostrarse. Los popovers están habilitados de forma predeterminada.


  $('#element').popover('enable')

`.popover('disable')`

Elimina la capacidad de mostrar la ventana emergente de un elemento. El popover solo se podrá mostrar si se vuelve a habilitar.


  $('#element').popover('disable')

`.popover('toggleEnabled')`

Alterna la capacidad de mostrar u ocultar la ventana emergente de un elemento.


  $('#element').popover('toggleEnabled')

`.popover('update')`

Actualiza la posición de la ventana emergente de un elemento.


  $('#element').popover('update')

Eventos

Tipo de evento	Descripción
show.bs.popover	Este evento se activa inmediatamente cuando `show` se llama al método de instancia.
show.bs.popover	Este evento se activa cuando el popover se ha hecho visible para el usuario (esperará a que se completen las transiciones CSS).
hide.bs.popover	Este evento se activa inmediatamente cuando `hide` se llama al método de instancia.
hidden.bs.popover	Este evento se activa cuando el popover ha terminado de ocultarse al usuario (esperará a que se completen las transiciones CSS).
insert.bs.popover	Este evento se activa después del `show.bs.popover` evento cuando la plantilla popover se ha agregado al DOM.


  $('#myPopover').on('hidden.bs.popover', function () {
    // do something...
  })