Tooltip

TsgcHTMLComponent_Tooltip: tooltips do Bootstrap nos elementos da página, como botões de barra de ferramentas e campos de formulário, a partir de uma lista de itens que nomeiam cada um um alvo e um texto. Os tooltips abrem ao passar o mouse e no foco do teclado, fecham com Esc, e funcionam em conteúdo que o htmx insere, em Delphi, C++ Builder e .NET.

Visão geral

Adicione um item por tooltip e sirva o HTML na mesma página que os alvos. O componente não renderiza marcação visível: um bloco JSON lista os tooltips, e um pequeno script cria um tooltip do Bootstrap 5 em cada elemento alvo quando a página carrega.

Classe do componente

TsgcHTMLComponent_Tooltip, com um TsgcHTMLTooltipItem por tooltip em Items

Renderiza

Um bloco JSON e um pequeno script, sobre o bundle do Bootstrap que o motor sgcHTML serve a partir de um recurso embutido, portanto nenhum CDN é necessário

Família

Sobreposições e Feedback

Linguagens

Delphi, C++ Builder, .NET

QuickStart

Placement, Trigger, Delay, Variant e MaxWidth no componente são os padrões de cada item, e um item pode substituir qualquer um deles com o seu próprio valor. Add define um alvo e um texto em uma só chamada.

uses
  sgcHTML_Component_Tooltip;

var
  oTip: TsgcHTMLComponent_Tooltip;
  oItem: TsgcHTMLTooltipItem;
begin
  oTip := TsgcHTMLComponent_Tooltip.Create(nil);
  try
    oTip.Placement := ttpBottom;
    oTip.Delay := 100;
    oTip.Add('#btnSave', 'Save the record');
    oTip.Add('#btnExport', 'Export the grid to Excel');

    oItem := oTip.Items.Add;
    oItem.TargetComponent := edtEmail;   // its EditID is set
    oItem.Title := 'Email';
    oItem.Text := 'The invoice is sent to this address.';
    oItem.Placement := ttpRight;

    Result := oTip.HTML;   // serve it in the page of the targets
  finally
    oTip.Free;
  end;
end;

@* The parent attributes are the defaults of every item *@
<sgc-tooltip placement="bottom" delay="100" variant="dark" max-width="18rem">
  <sgc-tooltip-item target="#btnSave" text="Save the record" />
  <sgc-tooltip-item target="#email" title="Email" text="The invoice is sent to this address."
                    placement="right" trigger="focus" variant="light" />
  <sgc-tooltip-item target=".btn-danger" text="&lt;b&gt;Cannot be undone&lt;/b&gt;" html="true"
                    trigger="click" variant="danger" />
</sgc-tooltip>

using esegece.sgcWebSockets;

var tip = new TsgcHTMLComponent_Tooltip();
tip.Placement = TsgcHTMLTooltipPlacement.ttpBottom;
tip.Delay = 100;
tip.Add("#btnSave", "Save the record");
tip.Add("#btnExport", "Export the grid to Excel");

var item = tip.Items.Add();
item.TargetComponent = edtEmail;   // its EditID is set
item.Title = "Email";
item.Text = "The invoice is sent to this address.";
item.Placement = TsgcHTMLTooltipPlacement.ttpRight;

string html = tip.HTML;

Recursos

O que seus usuários recebem

Dicas curtas que chegam a todos os usuários, com o mouse, com o teclado ou com um leitor de tela.

Passar o mouse e foco do teclado

Com o gatilho padrão, um usuário de teclado recebe o tooltip quando o alvo recebe o foco. Alvos que não podem receber o foco, como um span ou um ícone, recebem tabindex="0", removido de novo quando o tooltip é descartado.

Dispensável, sobrevoável, persistente

Os tooltips seguem o critério de sucesso 1.4.13 das WCAG 2.2. Esc fecha todos os tooltips abertos sem mover o ponteiro nem o foco, o ponteiro pode ir para cima do tooltip sem fechá-lo, e o tooltip permanece aberto até que o ponteiro ou o foco saia. Ele nunca fecha por um temporizador.

Lido por leitores de tela

aria-describedby liga o tooltip ao elemento com foco, de modo que os leitores de tela leem o texto depois do seu nome. Um aria-describedby que o alvo já tinha é mantido ao lado e restaurado quando o tooltip fecha.

Posicionamento que cabe

Auto, acima, abaixo, esquerda ou direita. O tooltip mantém o lado pedido sempre que couber na área visível, e só passa para outro lado quando aquele não tem espaço.

Variantes de cor

Variant escolhe o visual do Bootstrap, claro, escuro ou uma cor do tema: primary, secondary, success, danger, warning ou info. MaxWidth aceita um comprimento CSS, e vazio mantém 200px.

Título e texto rico

O texto simples é codificado em HTML e as suas quebras de linha viram <br>. Title adiciona uma primeira linha em negrito. Com HTML True o texto é marcação que passa por sgcHTMLSanitizeHTML, que mantém a formatação e as imagens e remove scripts, atributos de manipuladores de eventos e URLs inseguras.

Referência

Principais propriedades, métodos & eventos

Os membros que você mais usa.

Items e Add

Add(aTarget, aText) adiciona um tooltip em uma só chamada, e Items.Add devolve um item para definir o resto. Cada item tem Target, TargetComponent, Text, Title e HTML, mais as cinco opções do componente com um valor de herança: ttpInherit, tttInherit, Delay -1, ttvInherit e um MaxWidth vazio.

Alvo

Um seletor CSS, e todo elemento que corresponder recebe o tooltip, de modo que um item pode descrever todos os botões de uma classe, como .toolbar .btn-danger ou [name="email"]. Um item sem alvo é deixado de fora.

TargetComponent

Vincula um componente da mesma página, e o tooltip vai no elemento cujo id é a propriedade de id desse componente: EditID para um Edit, CheckBoxID para um CheckBox, PopoverID para um Popover, senão o seu ElementID. Só resolve quando esse id está definido; caso contrário o item usa Target.

Gatilho e atraso

Trigger abre o tooltip ao passar o mouse e no foco (o padrão), no clique, no foco, ou manualmente. Delay é o número de milissegundos antes de um tooltip abrir. Em um alvo botão com o gatilho de clique, Enter e Espaço o abrem ou fecham.

Conteúdo inserido pelo htmx

Após cada htmx:afterSwap e htmx:load o script examina a página de novo. Os novos elementos que correspondem a um item recebem o seu tooltip, e os tooltips cujo elemento ou bloco JSON saiu da página são descartados. O script executa uma vez por página, não importa quantos componentes a página tenha.

Saída

HTML devolve o bloco JSON seguido do script dos tooltips, ou uma string vazia quando nenhum item tem ao mesmo tempo um alvo e um texto. Sirva-o com o bundle do Bootstrap, por exemplo no BodyContent de um TsgcHTMLTemplate_Bootstrap. Sua posição na página não importa, e o script espera o bundle.

Dicas, não diálogos

Mantenha os tooltips curtos: eles não podem conter controles que o usuário precise alcançar. Para conteúdo interativo, use um Popover ou um Modal.

ASP.NET Core

Em uma view Razor, o Tag Helper <sgc-tooltip> renderiza o componente, com um filho <sgc-tooltip-item /> por item. Os atributos do pai são os padrões de cada item. Os tooltips não precisam de eventos de servidor, então o componente é criado a cada renderização. Não há atributo para TargetComponent: use target com o id do elemento.

A demo

Demos\60.HTML\01.RunTime\29.Tour é o sgc Cloud Console na porta 8131, um painel SaaS com tooltips nos botões da barra de ferramentas, nos cartões de estatísticas e nos campos de formulário, ao lado de um tour guiado do produto na primeira execução. As versões em design time, Lazarus e .NET a espelham.