in English

Popovers

Documentación e exemplos para engadir popovers Bootstrap, como os que se atopan en iOS, a calquera elemento do teu sitio.

Visión xeral

Cousas que debes saber ao usar o complemento popover:

  • Os popovers confían na biblioteca de terceiros Popper para o posicionamento. Debes incluír popper.min.js antes de bootstrap.js ou usar bootstrap.bundle.min.js/ bootstrap.bundle.jsque contén Popper para que funcionen.
  • Os popovers requiren o complemento de información sobre ferramentas como dependencia.
  • Se estás construíndo o noso JavaScript desde a orixe, requireutil.js .
  • Os popovers están activados por motivos de rendemento, polo que debes inicializalos vostede mesmo .
  • A lonxitude cero titlee contentos valores nunca mostrarán un popover.
  • Especifique container: 'body'para evitar problemas de renderizado en compoñentes máis complexos (como os nosos grupos de entrada, grupos de botóns, etc.).
  • Non funcionará activar popovers en elementos ocultos.
  • Os popovers para .disabledou disabledelementos deben activarse nun elemento de envoltura.
  • Cando se activan desde áncoras que envolven varias liñas, os popovers centraranse entre o ancho total das áncoras. Use .text-nowrapno seu <a>s para evitar este comportamento.
  • Os popovers deben ocultarse antes de que se eliminen do DOM os seus elementos correspondentes.
  • Os popovers pódense activar grazas a un elemento dentro dun DOM en sombra.
De forma predeterminada, este compoñente usa o desinfectante de contido integrado, que elimina todos os elementos HTML que non están permitidos de forma explícita. Consulta a sección de desinfectantes na nosa documentación de JavaScript para obter máis detalles.
O efecto de animación deste compoñente depende da prefers-reduced-motionconsulta multimedia. Consulta a sección de movemento reducido da nosa documentación de accesibilidade .

Continúa lendo para ver como funcionan os popovers con algúns exemplos.

Exemplo: activa os popovers en todas partes

Unha forma de inicializar todos os popovers nunha páxina sería seleccionalos polo seu data-toggleatributo:

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

Exemplo: Usando a containeropción

Cando teñas algúns estilos nun elemento principal que interfiran cun popover, quererás especificar un personalizado containerpara que o HTML do popover apareza nese elemento.

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

Exemplo

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

Catro direccións

Hai catro opcións dispoñibles: arriba, dereita, inferior e aliñada á esquerda.

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Left popover">
  Popover on left
</button>

Descartar no seguinte clic

Use o focusdisparador para descartar popovers no seguinte clic do usuario nun elemento diferente do elemento de alternancia.

Requírese un marcado específico para descartar ao facer clic ao seguinte

Para un comportamento adecuado entre navegadores e plataformas, debes usar a <a>etiqueta, non a <button>etiqueta, e tamén debes incluír un tabindexatributo.

Popover descartable 
<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 desactivados

Os elementos co disabledatributo non son interactivos, o que significa que os usuarios non poden pasar o rato nin facer clic neles para activar un popover (ou información sobre ferramentas). Como solución alternativa, quererá activar o popover desde un envoltorio <div>ou <span>e anular o pointer-eventselemento desactivado.

Para os activadores de popover desactivados, tamén podes preferir data-trigger="hover"que o popover apareza como un feedback visual inmediato para os teus usuarios, xa que quizais non esperen facer clic nun elemento desactivado.

<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

Activar popovers mediante JavaScript:

$('#example').popover(options)
Aceleración de GPU

Os popovers ás veces aparecen borrosos nos dispositivos Windows 10 debido á aceleración da GPU e a un DPI modificado do sistema. A solución para isto na v4 é desactivar a aceleración da GPU segundo sexa necesario nos teus popovers.

Corrección suxerida:

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

Facendo que os popovers funcionen para os usuarios de teclado e tecnoloxía de asistencia

Para permitir que os usuarios do teclado activen os teus popovers, só debes engadilos aos elementos HTML tradicionalmente interactivos e enfocados ao teclado (como ligazóns ou controis de formulario). Aínda que os elementos HTML arbitrarios (como <span>s) pódense enfocar engadindo o tabindex="0"atributo, isto engadirá tabulacións potencialmente molestas e confusas en elementos non interactivos para os usuarios de teclado, e a maioría das tecnoloxías de asistencia actualmente non anuncian o contido do popover nesta situación. . Ademais, non confíes únicamente no hoveractivador dos teus popovers, xa que isto fará que sexan imposibles de activar para os usuarios do teclado.

Aínda que pode inserir HTML enriquecido e estruturado nas ventás emerxentes coa htmlopción, recomendamos encarecidamente que evite engadir unha cantidade excesiva de contido. A forma en que funcionan os popovers actualmente é que, unha vez mostrados, o seu contido está ligado ao elemento disparador co aria-describedbyatributo. Como resultado, a totalidade do contido do popover anunciarase aos usuarios de tecnoloxía de asistencia como un fluxo longo e ininterrompido.

Ademais, aínda que tamén é posible incluír controis interactivos (como elementos de formulario ou ligazóns) no teu popover (engadindo estes elementos aos whiteListatributos e etiquetas permitidos), teña en conta que actualmente o popover non xestiona a orde de enfoque do teclado. Cando un usuario de teclado abre un popover, o foco permanece no elemento activador e, como o popover normalmente non segue inmediatamente o disparador na estrutura do documento, non hai garantía de que avance/preme.TABmoverá un usuario de teclado ao propio popover. En resumo, é probable que simplemente engadir controis interactivos a un popover faga que estes controis sexan inalcanzables/inutilizables para os usuarios de teclado e os usuarios de tecnoloxías de asistencia, ou polo menos faga unha orde global de enfoque ilóxica. Nestes casos, considere usar un diálogo modal no seu lugar.

Opcións

As opcións pódense pasar a través de atributos de datos ou JavaScript. Para os atributos de datos, engada o nome da opción a data-, como en data-animation="".

Teña en conta que, por razóns de seguridade, as opcións sanitize, sanitizeFne whiteListnon se poden proporcionar mediante atributos de datos.
Nome Tipo Por defecto Descrición
animación booleano verdade Aplique unha transición de fundido CSS ao popover
envase cadea | elemento | falso falso

Engade o popover a un elemento específico. Exemplo: container: 'body'. Esta opción é particularmente útil porque permite situar o popover no fluxo do documento preto do elemento activador, o que evitará que o popover flote lonxe do elemento activador durante un cambio de tamaño da xanela.
contido cadea | elemento | función ''

Valor de contido predeterminado se data-contento atributo non está presente.

Se se dá unha función, chamarase coa súa thisreferencia definida ao elemento ao que está unido o popover.
atraso número | obxecto 0

Atraso para mostrar e ocultar o popover (ms): non se aplica ao tipo de activación manual

Se se proporciona un número, aplícase un atraso tanto para ocultar como para mostrar

A estrutura do obxecto é:delay: { "show": 500, "hide": 100 }
html booleano falso Insira HTML no popover. textSe é falso, empregarase o método de jQuery para inserir contido no DOM. Usa texto se estás preocupado polos ataques XSS.
colocación cadea | función 'correcto'

Como colocar o popover - auto | arriba | inferior | esquerda | certo.
Cando autose especifica, reorientará dinámicamente o popover.

Cando se usa unha función para determinar a colocación, chámase co nodo DOM popover como primeiro argumento e o nodo DOM do elemento desencadeante como segundo. O thiscontexto establécese na instancia de popover.
selector cadea | falso falso Se se proporciona un selector, os obxectos popover delegaranse nos obxectivos especificados. Na práctica, isto úsase para permitir que o contido HTML dinámico teña aparellos emergentes engadidos. Vexa isto e un exemplo informativo .
modelo corda '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

HTML base para usar ao crear o popover.

Os popovers titleinxectaranse no .popover-header.

Os popovers contentinxectaranse no .popover-body.

.arrowconverterase na frecha do popover.

O elemento de envoltura máis externo debería ter a .popoverclase.
título cadea | elemento | función ''

Valor predeterminado do título se titleo atributo non está presente.

Se se dá unha función, chamarase coa súa thisreferencia definida ao elemento ao que está unido o popover.
disparador corda 'click' Como se activa o popover: fai clic en | pasar o rato | foco | manual. Podes pasar varios disparadores; separalos cun espazo. manualnon se pode combinar con ningún outro disparador.
compensar número | corda 0 Desfase do popover en relación ao seu obxectivo. Para obter máis información, consulte os documentos de offset de Popper .
colocación de reserva cadea | matriz 'flip' Permitir especificar a posición que utilizará Popper no respaldo. Para obter máis información, consulte os documentos de comportamento de Popper
clase personalizada cadea | función ''

Engade clases ao popover cando se mostra. Teña en conta que estas clases engadiranse ademais de todas as clases especificadas no modelo. Para engadir varias clases, sepáraas con espazos: 'a b'.

Tamén pode pasar unha función que debería devolver unha única cadea que conteña nomes de clases adicionais.
límite cadea | elemento 'scrollParent' Límite de restricción de desbordamento do popover. Acepta os valores de 'viewport', 'window', 'scrollParent', ou unha referencia HTMLElement (só JavaScript). Para obter máis información, consulte os documentos preventOverflow de Popper .
desinfectar booleano verdade Activa ou desactiva a desinfección. Se está activado 'template', 'content'e 'title'as opcións serán desinfectadas. Consulte a sección de desinfectantes na nosa documentación de JavaScript .
lista branca obxecto Valor predeterminado Obxecto que contén atributos e etiquetas permitidos
desinfectarFn nulo | función nulo Aquí podes proporcionar a túa propia función de desinfección. Isto pode ser útil se prefires usar unha biblioteca dedicada para realizar a desinfección.
popperConfig nulo | obxecto nulo Para cambiar a configuración de Popper predeterminada de Bootstrap, consulte a configuración de Popper

Atributos de datos para popovers individuais

As opcións para popovers individuais pódense especificar alternativamente mediante o uso de atributos de datos, como se explicou anteriormente.

Métodos

Métodos asíncronos e transicións

Todos os métodos da API son asíncronos e inician unha transición . Volven ao interlocutor en canto se inicia a transición pero antes de que remate . Ademais, ignorarase unha chamada de método nun compoñente en transición .

Consulte a nosa documentación de JavaScript para obter máis información .

$().popover(options)

Inicia os popovers para unha colección de elementos.

.popover('show')

Revela o popover dun elemento. Volve ao interlocutor antes de que se amosase o popover (é dicir, antes de shown.bs.popoverque se produza o evento). Isto considérase un desencadeamento "manual" do popover. Nunca se amosan os popovers cuxo título e contido sexan de lonxitude cero.

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

.popover('hide')

Oculta o popover dun elemento. Volve ao interlocutor antes de que se ocultase o popover (é dicir, antes de hidden.bs.popoverque ocorra o evento). Isto considérase un desencadeamento "manual" do popover.

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

.popover('toggle')

Alterna o popover dun elemento. Volve ao interlocutor antes de que se amosase ou ocultase o popover (é dicir, antes de que se produza o evento shown.bs.popoverou ). hidden.bs.popoverIsto considérase un desencadeamento "manual" do popover.

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

.popover('dispose')

Oculta e destrúe o popover dun elemento. Os popovers que usan a delegación (que se crean mediante a selectoropción ) non se poden destruír individualmente nos elementos desencadeantes descendentes.

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

.popover('enable')

Dá a posibilidade de mostrar o popover dun elemento. Os popovers están activados por defecto.

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

.popover('disable')

Elimina a posibilidade de mostrar o popover dun elemento. O popover só se poderá mostrar se se volve activar.

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

.popover('toggleEnabled')

Alterna a posibilidade de mostrar ou ocultar o popover dun elemento.

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

.popover('update')

Actualiza a posición do popover dun elemento.

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

Eventos

Tipo de evento Descrición
mostrar.bs.popover Este evento desenvólvese inmediatamente cando showse chama ao método de instancia.
mostrado.bs.popover Este evento desenvólvese cando o popover se fixo visible para o usuario (esperará a que se completen as transicións CSS).
ocultar.bs.popover Este evento desenvólvese inmediatamente cando hidese chamou ao método de instancia.
hidden.bs.popover Este evento desenvólvese cando o popover rematou de ocultarse ao usuario (esperará a que se completen as transicións CSS).
inserido.bs.popover Este evento desenvólvese despois do show.bs.popoverevento cando o modelo popover foi engadido ao DOM. 
$('#myPopover').on('hidden.bs.popover', function () {
  // do something...
})