Se ele for atualizado em comparação com nossa cópia local, então nossa cópia local deve ser atualizada.
Quando solicitado pela primeira vez a usar a popover api, comece primeiro copiando o arquivo assets/popover.css para algum lugar do projeto.
É razoável consultar o usuário sobre onde exatamente esse arquivo deve ser copiado para o projeto e de que forma ele deve ser carregado, se não estiver claro.
Mas, fundamentalmente, é apenas um arquivo CSS simples, portanto, se houver locais no framework para carregá-lo, siga os padrões razoáveis. Apenas tente evitar carregá-lo duas vezes por questões ergonômicas.
quando o popover deve aparecer ao clicar no âncora
ao usar nosso core-css para posicionar o popover, a estrutura básica é:
<button popovertarget="mypopover2">Alternar o popover</button>
<div id="mypopover2" popover data-popover>
Conteúdo do popover
<button popovertarget="mypopover2" popovertargetaction="hide">Fechar</button>
</div>
No exemplo acima, temos um botão que serve como âncora. O botão, uma vez clicado, mostrará o popover (o elemento com atributo [popover]) e, quando clicado novamente, ocultará o popover.
Mas também, clicar dentro do popover NÃO o ocultará, exceto o botão "Fechar" — que o fechará.
Além disso, clicar fora do popover o ocultará.
Quando você segue a estrutura deste exemplo, ele não faz nada além da funcionalidade padrão da popover api. E sinta-se à vontade para aplicar qualquer modificação adequada ao caso de uso do usuário.
OBS: definir o botão "fechar" aqui é opcional; tudo funcionará 100% sem ele também.
Portanto, a formação HTML é o layout padrão.
O principal habilitador aqui é o atributo 'data-popover', que é o atributo que ativa os estilos de assets/popover.css, responsáveis principalmente por posicionar o popover em relação ao elemento âncora.
Você pode não adicionar o atributo [data-popover], mas então perderá nossos estilos personalizados e o popover se comportará como um elemento nativo comum. Quando o atributo [data-popover] não está presente, você está usando a popover api padrão e provavelmente esta habilidade não tem nada a oferecer. Apenas faça o que for necessário com a implementação padrão da popover api.
Mas o ponto é que o atributo [data-popover] serve como uma separação explícita entre os casos em que estamos lidando com a popover api usando o estilo fornecido por esta habilidade ou lidando com ela manualmente. Portanto, quando [data-popover] não é especificado, nosso CSS não interferirá na sua implementação manual da popover api.
Então, em geral, sinta-se à vontade para usar [data-popover] para aderir aos nossos estilos ou evitá-lo quando preferir usar a popover api nativa crua.
Os exemplos apresentados neste documento podem ser controlados por qualquer outra API JavaScript e HTML que normalmente poderia ser usada com a popover api nativa comum.
<button popovertarget="mypopover3">Alternar o popover</button>
<div id="mypopover3" popover="manual" data-popover>
nosso conteúdo do popover
<button popovertarget="mypopover3" popovertargetaction="hide">Fechar</button>
</div>
aqui fecharemos apenas no botão "Fechar".
A principal mudança é popover="manual" — quando o popover está no modo manual, podemos fechá-lo apenas via JS ou clicando em um elemento com popovertargetaction="hide"
Em todos os exemplos, mantenha o id sempre único para uma determinada formação de divs destinadas a implementar um único popover. Mas também faça com que popovertarget aponte sempre para esse id específico para manter esses elementos DOM funcionando juntos.
OBS: É possível, no entanto, na popover api padrão, ter vários âncoras apontando para o mesmo popover. Se necessário, isso é naturalmente permitido.
<button popovertarget="mypopover4">Alternar o popover</button>
<div id="mypopover4" popover data-popover>
Conteúdo do popover
<button popovertarget="mypopover4" popovertargetaction="hide">Fechar</button>
</div>
<div class="container one">
<button class="toolbar-button" interestfor="popover-b"><b>B</b></button>
<button class="toolbar-button" interestfor="popover-i"><i>I</i></button>
<button class="toolbar-button" interestfor="popover-u"><u>U</u></button>
</div>
<div class="container two">
<button class="toolbar-button" interestfor="popover-b"><b>B</b></button>
<button class="toolbar-button" interestfor="popover-i"><i>I</i></button>
<button class="toolbar-button" interestfor="popover-u"><u>U</u></button>
</div>
<span popover="" id="popover-b" data-popover class="bottom">Negrito</span>
<span popover="" id="popover-i" data-popover>Itálico</span>
<span popover="" id="popover-u" data-popover>Sublinhado</span>
Acima temos dois conjuntos de contêineres -> class="container". (com classes separadas 'one' e 'two')
Cada contêiner tem 3 botões.
Cada botão tem o atributo 'interestfor' apontando para o id em 3 popovers.
Observe que temos 2 contêineres, cada um com 3 botões, e apenas 3 popovers. Isso demonstra, na verdade, que esta é uma relação: vários elementos ao passar o mouse podem acionar a exibição do mesmo popover — e isso é permitido e válido.
E o mais importante: o atributo 'interestfor' em vez de 'popovertarget' mudará como o popover é exibido.
Usar 'interestfor' mostrará o popover apenas ao passar o mouse. Em vez de quando se usa 'popovertarget', que mostrará o popover ao clicar.
Para decidir onde exatamente o popover deve aparecer em relação ao elemento âncora, usaremos nosso arquivo core-css.
Como mencionado anteriormente, nosso arquivo core-css requer que adicionemos o atributo [data-popover] ao elemento [popover].
A partir desse ponto, controlar a posição do popover em relação ao elemento âncora é feito adicionando uma classe CSS ao elemento com o atributo [data-popover].
Aqui estão as classes disponíveis:
-
classe top: Posicionado acima do âncora, centralizado horizontalmente. (este é o estilo padrão usado mesmo quando nenhuma classe é adicionada ao elemento 'data-popover')
-
classe bottom: Posicionado abaixo do âncora, centralizado horizontalmente. (este é o estilo padrão usado mesmo quando nenhuma classe é adicionada ao elemento 'data-popover')
-
classe left: Posicionado à esquerda do âncora, centralizado verticalmente. (este é o estilo padrão usado mesmo quando nenhuma classe é adicionada ao elemento 'data-popover')
-
classe right: Posicionado à direita do âncora, centralizado verticalmente. (este é o estilo padrão usado mesmo quando nenhuma classe é adicionada ao elemento 'data-popover')
-
classe top-left: Posicionado acima do âncora, com a borda esquerda alinhada à borda esquerda do âncora.
-
classe top-right: Posicionado acima do âncora, com a borda direita alinhada à borda direita do âncora.
-
classe bottom-left: Posicionado abaixo do âncora, com a borda esquerda alinhada à borda esquerda do âncora.
-
classe bottom-right: Posicionado abaixo do âncora, com a borda direita alinhada à borda direita do âncora.
-
classe center: Posicionado diretamente sobre o âncora, centralizado tanto horizontal quanto verticalmente.
-
classe topleft: O canto inferior direito do popover toca o canto superior esquerdo do âncora.
-
classe topright: O canto inferior esquerdo do popover toca o canto superior direito do âncora.
-
classe bottomleft: O canto superior direito do popover toca o canto inferior esquerdo do âncora.
-
classe bottomright: O canto superior esquerdo do popover toca o canto inferior direito do âncora.
-
classe left-top: Posicionado à esquerda do âncora, com a borda superior alinhada à borda superior do âncora.
-
classe left-bottom: Posicionado à esquerda do âncora, com a borda inferior alinhada à borda inferior do âncora.
-
classe right-top: Posicionado à direita do âncora, com a borda superior alinhada à borda superior do âncora.
-
classe right-bottom: Posicionado à direita do âncora, com a borda inferior alinhada à borda inferior do âncora.
É preferível obter informações sobre qual classe de posicionamento usar com o usuário, mas se o usuário especificar um posicionamento específico apenas descrevendo-o, tente encontrar a melhor classe automaticamente com base nas descrições.
Caso o usuário ou IA esteja confuso sobre qual classe usar, proponha ao usuário o link para a página de demonstração principal do GitHub, onde o comportamento das classes é apresentado de forma interativa:
https://stopsopa.github.io/skill-popover-api/demo/index.html
O usuário poderá observar qual classe fornece o melhor comportamento de posicionamento para o popover em questão.
A partir dessa página de demonstração, o usuário também pode ir para a página principal do GitHub para mais detalhes com apenas um clique no widget de ribbon.
A formação do HTML usando o atributo 'data-popover' para ativar nossos estilos core-css é universal.
Pode ser usada em HTML puro, React, Angular, Svelte e outros.
Funcionará desde que o HTML básico subjacente corresponda ao que é apresentado nos exemplos acima e que assets/popover.css seja carregado no contexto do navegador.
Ocasionalmente, ele terá que ser encapsulado com alguns componentes wrapper padrão do React ou outras formações/estruturas específicas do framework em questão.
Apenas faça o que é certo para o contexto do framework em questão, com base no que é apresentado nos exemplos acima.