Status na matriz: Experimental.
Web components (<dsgovbr-header>, -menu, -footer, -breadcrumb)
JS opcional que encapsula as composições do
exemplo de painel (Header, Menu, Footer e Breadcrumb do GOV.BR DS)
em custom elements. Eles geram as mesmas classes Bootstrap documentadas nas outras páginas,
em light DOM (sem Shadow DOM): o CSS do tema e o seu continuam valendo. O JS do Bootstrap
(bootstrap.bundle) segue sendo quem abre o menu, os dropdowns e a busca.
Uso
Carregue o arquivo com defer (ou no fim do <body>), para os filhos já
existirem quando o componente monta. O skip link e o <main id="conteudo"> ficam no HTML
da página, antes do header.
<link rel="stylesheet" href="dist/dsgovbr-bootstrapped.min.css">
<script src="dist/dsgovbr-bootstrapped-modo.js"></script> <!-- opcional: botão de modo escuro -->
<script src="dist/dsgovbr-bootstrapped-componentes.js" defer></script>
<script src="bootstrap.bundle.min.js" defer></script>
Cada componente lê os filhos e os atributos uma vez, ao conectar, e troca o conteúdo pelo HTML final: o que você escreve é só a declaração. Mudar um atributo depois remonta o componente. Os valores viram texto e atributos, nunca HTML.
Elementos filhos
As partes internas também são elementos. Eles só carregam atributos e conteúdo para o componente
pai, que os troca pelo HTML final; sozinhos, fora de um pai, não aparecem. Onde se espera um
<dsgovbr-item>, um <a href> comum também vale.
| Elemento | Atributos | Onde |
|---|---|---|
<dsgovbr-item> | href, icone (classes do ícone), atual (página atual), externo (ícone de link externo), icone-cor (.text-<cor> no ícone), badge, badge-cor (pílula à direita no menu; cor do Bootstrap, padrão primary), metodo="post" (vira um <form method="post" action="href"> com um botão e os <dsgovbr-campo-oculto> filhos, como o "Sair"); o texto é o rótulo | menu, pasta, coluna do footer, acesso rápido, funcionalidades, menu do usuário, breadcrumb, rodapé do menu |
<dsgovbr-campo-oculto> | nome, valor; vira <input type="hidden"> no form do item com metodo="post" (ex.: o token CSRF) | item |
<dsgovbr-pasta> | rotulo, icone, icone-cor, aberta, id (do Collapse); filhos: itens e outras pastas (vários níveis; a filha ganha id <pai>-<n> se não tiver) | menu |
<dsgovbr-menu-rodape> | rotulo-redes; filhos: dsgovbr-logo, itens (externo), dsgovbr-rede, dsgovbr-aviso | menu |
<dsgovbr-coluna> | titulo; filhos: itens | footer |
<dsgovbr-rede> | href, icone; o texto é o nome acessível | footer, rodapé do menu |
<dsgovbr-logo> | src, alt | rodapé do menu |
<dsgovbr-aviso> | conteúdo livre (aceita HTML) | footer, rodapé do menu |
<dsgovbr-acesso-rapido>, <dsgovbr-funcionalidades> | filhos: itens (icone nas funcionalidades; o texto vira o nome acessível) | header |
<dsgovbr-usuario-menu>, <dsgovbr-divisor> | filhos: itens e divisores | header |
<dsgovbr-acoes> | conteúdo livre (ex.: botões da página) | header |
Breadcrumb (<dsgovbr-breadcrumb>)
<dsgovbr-breadcrumb rotulo="Trilha de navegação">
<dsgovbr-item href="/">Início</dsgovbr-item>
<dsgovbr-item href="/cadastros">Cadastros</dsgovbr-item>
<dsgovbr-item>Usuários</dsgovbr-item> <!-- o último é a página atual (aria-current="page") -->
</dsgovbr-breadcrumb>
Atributos: rotulo (aria-label do <nav>; padrão "Trilha de navegação") e
compacto (margem inferior reduzida, aplicada automaticamente dentro do header).
Header (<dsgovbr-header>)
Abaixo, com estatico para não grudar no topo desta página. No exemplo de painel ele fica fixo
(.sticky-top), junto com o breadcrumb, o título e as ações da página; ao rolar, a linha de cima
(logo, assinatura e ações) e o subtítulo somem e fica só o título e a busca (atributo data-dsgovbr-rolado no host).
<dsgovbr-header logo="logo.svg" logo-alt="Página inicial" href="/"
assinatura="Ministério Exemplo"
titulo="Sistema" subtitulo="Gestão de usuários"
menu="menu-principal" busca modo cookies usuario="Maria Silva" pagina="Usuários">
<dsgovbr-acesso-rapido>
<dsgovbr-item href="/docs">Documentação</dsgovbr-item>
</dsgovbr-acesso-rapido>
<dsgovbr-funcionalidades>
<dsgovbr-item href="#" icone="fas fa-headset">Suporte</dsgovbr-item>
</dsgovbr-funcionalidades>
<dsgovbr-usuario-menu>
<dsgovbr-item href="/perfil">Meu perfil</dsgovbr-item>
<dsgovbr-divisor></dsgovbr-divisor>
<dsgovbr-item href="/sair">Sair</dsgovbr-item>
</dsgovbr-usuario-menu>
<dsgovbr-breadcrumb>…</dsgovbr-breadcrumb>
<dsgovbr-acoes>
<button class="btn btn-primary">Adicionar</button>
</dsgovbr-acoes>
</dsgovbr-header>
| Atributo | Efeito |
|---|---|
logo, logo-alt, href, logo-href | Logo (link para href, padrão #) e o texto alternativo dele. href também é o link do título; logo-href dá ao logo outro destino (ex.: o portal do órgão). |
assinatura | Texto ao lado do logo, depois de um divisor (a partir de sm). |
titulo, subtitulo | Segunda linha: título do sistema (.navbar-brand) e subtítulo. |
menu | id de um <dsgovbr-menu>: mostra o botão que abre o menu. |
busca | Campo de busca (recolhido por Collapse abaixo de lg). |
busca-acao, busca-nome, busca-valor, busca-id | Para aplicações renderizadas no servidor: URL do <form method="get"> da busca, name do campo (padrão q quando há busca-acao), valor inicial e id do campo (para atalhos como "Ir para a busca"). Sem busca-acao o formulário não envia a lugar nenhum, como antes. |
busca-autocomplete | URL (caminho local, da mesma origem) de um endpoint JSON que recebe ?<busca-nome>=termo e devolve ["a", "b"] ou [{"label": "A", "value": "a"}]. A lista aparece abaixo do campo depois de 300 ms e 2 ou mais caracteres, como um combobox ARIA: setas movem a opção ativa, Enter escolhe e envia, Esc fecha. O texto das sugestões nunca vira HTML. |
modo | Botão de modo claro/escuro (data-dsgovbr-modo); exige dsgovbr-bootstrapped-modo.js. |
modo-rotulo, modo-icone | Texto (nome acessível e title no desktop, texto do item no celular) e classes do ícone do botão de modo. Padrões: Modo escuro e fas fa-adjust. |
cookies | Botão de ação rápida (ícone de cookie) que abre as configurações do <dsgovbr-cookiebar> (data-dsgovbr-cookies-abrir); exige dsgovbr-bootstrapped-cookies.js. Use sem-botao no cookiebar para não duplicar o botão flutuante. |
usuario | Nome do usuário autenticado; abre o dropdown com os itens de <dsgovbr-usuario-menu> (<dsgovbr-divisor> vira divisor). |
usuario-avatar, usuario-inicial, usuario-papel | Foto (URL, decorativa: alt vazio) ou inicial (1 ou 2 letras) no botão do usuário, no lugar do ícone; e o papel (perfil, cargo) em texto pequeno abaixo do nome completo, no topo do dropdown. |
entrar, entrar-rotulo | Sem usuario: botão "Entrar" (ou o rótulo dado) que leva à URL de entrar. |
pagina | Título da página (<h1>), na barra logo abaixo do <header> (fora dele, como no GOV.BR DS), que gruda no topo junto com ele. |
estatico | Não fixa o header no topo (e não recolhe a linha de cima ao rolar). |
Filhos: <dsgovbr-acesso-rapido> (itens; viram menu em telas menores que xl),
<dsgovbr-funcionalidades> (itens com icone; o texto vira o nome acessível),
<dsgovbr-usuario-menu>, <dsgovbr-breadcrumb> e
<dsgovbr-acoes> (HTML livre, ex.: botões da página).
Menu (<dsgovbr-menu>)
O próprio elemento é o .offcanvas.offcanvas-start: o id dele é o alvo do botão do header.
<dsgovbr-menu id="menu-principal" titulo="Sistema" logo="logo.svg">
<dsgovbr-item href="/" icone="fas fa-home">Início</dsgovbr-item>
<dsgovbr-pasta rotulo="Cadastros" icone="fas fa-users" aberta id="menu-cadastros"> <!-- Collapse -->
<dsgovbr-item href="/usuarios" icone="fas fa-user" atual>Usuários</dsgovbr-item>
</dsgovbr-pasta>
<dsgovbr-menu-rodape rotulo-redes="Redes sociais">
<dsgovbr-logo src="orgao.svg" alt="Logo do órgão"></dsgovbr-logo>
<dsgovbr-item href="https://…" externo>Portal do órgão</dsgovbr-item>
<dsgovbr-rede href="https://…" icone="fab fa-youtube">YouTube</dsgovbr-rede>
<dsgovbr-aviso>Licença <strong>CC BY 4.0</strong>.</dsgovbr-aviso>
</dsgovbr-menu-rodape>
</dsgovbr-menu>
Atributos: titulo, logo, rotulo (aria-label do <nav>; padrão "Menu principal") e
rotulo-fechar (padrão "Fechar o menu"). atual marca o item da página (.active e
aria-current="page"); aberta na pasta a deixa aberta; o id dela, se houver,
vira o do Collapse. O <dsgovbr-menu-rodape> mostra, nesta ordem, logos, itens externos, redes e aviso.
Footer (<dsgovbr-footer>)
<dsgovbr-footer logo="logo-negativo.svg" logo-alt="Logo do sistema"
assinatura="assinatura.svg" assinatura-alt="Assinatura do órgão">
<dsgovbr-coluna titulo="Sistema">
<dsgovbr-item href="/sobre">Sobre</dsgovbr-item>
</dsgovbr-coluna>
<dsgovbr-rede href="…" icone="fab fa-facebook-f">Facebook</dsgovbr-rede>
<dsgovbr-aviso>Texto legal (aceita HTML)</dsgovbr-aviso>
</dsgovbr-footer>
Sempre no modo escuro (data-bs-theme="dark" no <footer>), com fundo --background-dark.
Atributos: logo, logo-alt, assinatura, assinatura-alt e
rotulo-redes (padrão "Redes sociais"). Cada <dsgovbr-coluna> vira um <nav> com o
titulo como <h2> e aria-label; o nome acessível de cada rede é o texto dela.
Acessibilidade
- O host de
<dsgovbr-header>,-footere-breadcrumbusadisplay: contents: os landmarks<header>,<footer>e<nav>reais é que existem na árvore. - Botões só com ícone têm
aria-label; o ícone éaria-hidden. Menu, dropdowns e busca usam os atributosdata-bs-*do Bootstrap (foco, Escape earia-expandedvêm do plugin). - Antes de montar, o CSS esconde o componente (
visibility: hiddenaté o atributodata-dsgovbr-montado), para a declaração crua não "piscar". Sem o JS, ele fica oculto.
Diferenças conhecidas em relação ao GOV.BR DS
- Não usam as classes
.br-*nem o JS do GOV.BR DS: o resultado é o das composições Bootstrap documentadas em Navbar, Offcanvas, List group e Breadcrumb. - O recolhimento de níveis do breadcrumb e a anatomia completa do
.br-header(menu de links, mais de uma linha de ações) não são reproduzidos; o que não está nos atributos e elementos acima pode ser feito com HTML livre em<dsgovbr-acoes>e<dsgovbr-aviso>. - O conteúdo é lido uma vez: adicionar filhos depois de montado não atualiza o componente (altere um atributo ou recrie o elemento).
- Experimental: a API (atributos e elementos) pode mudar antes da 1.0.