Button - Criar especificação do componente
Button
Elemento HTML:
<br-button></br-button>
Estrutura HTML do Componente
A estrutura HTML se baseia na anatomia do componente, detalhada na documentação GovBR-DS e visa atender comportamentos, estados, e funcionalidades previstos para o componente, bem como permitir a flexibilidade no uso do componente.
Anatomia | Estrutura HTML | Descrição |
---|---|---|
Superfície | Tag host do elemento |
A superfície é implementada por meio de CSS. No HTML corresponde a tag raiz do elemento |
Ícone | Slot com conteúdo padrão | O ícone pode ser informado por meio de propriedade ou passando um conteúdo por slot |
Rótulo | Slot com conteúdo padrão | O rótulo pode ser informado por meio de propriedade ou passando um conteúdo por slot |
O rótulo não estará presente no botão de formato circular.
Flexibilidade na Composição do Componente
Os critérios utilizados para dar flexibilidade de uso ao componente button
são:
- As áreas de conteúdo "ícone" e "rótulo" foram definidas como slots
- O slots das áreas de conteúdo possuem implementação default caso não recebam nenhum conteúdo externo
- Os dados da implementação default dos slots são passados por atributos HTML ou propriedades JavaScript.
Atributos HTML e Propriedades JavaScript
O componente button
possui os seguintes atributos HTML e respectivas propriedades JavaScript:
Atributo HTML | Propriedade JS | Restrição | Descrição | Tipo | Valores Aceitos | Padrão |
---|---|---|---|---|---|---|
label |
label |
OBRIGATÓRIO | O rótulo é um elemento obrigatório. A exceção ocorre na versão tipo circular uma vez que não existe rótulo. Consulte mais em Tipografia | string |
Qualquer sequência de caracteres | null |
active |
active |
OPCIONAL | Utilizado para enfatizar o estado ativo do botão | boolean |
Padrão do atributo boolean (HTML) | Ausência do atributo (false ) |
color-mode |
colorMode |
OPCIONAL | Indica qual esquema de cores o botão está usando | string |
dark |
undefined |
density |
density |
OPCIONAL | O ajuste da densidade consiste em aumentar ou reduzir os espaçamentos internos do botão de forma a deixá-los mais compactos ou mais expandidos em seu formato | string |
large middle small
|
middle |
disabled |
disabled |
OPCIONAL | Desabilita o botão | boolean |
Padrão do atributo boolean (HTML) | Ausência do atributo (false ) |
emphasis |
emphasis |
OPCIONAL | Ênfase do botão, com finalidade de proporcionar hierarquia visual a esses elementos e ações. Os botões mudam de aparência conforme a ênfase utilizada | string |
primary secondary tertiary
|
tertiary |
icon |
icon |
OPCIONAL | Usado quando houver uma necessidade de enfatizar visualmente a ideia da ação. Nos botões do tipo circular a utilização é obrigatória, visto que a mensagem da ação é transmitida apenas pelo ícone | string |
Nome de um ícone do fontawesome | null |
icon-position |
iconPosition |
OPCIONAL | Indica a posição do ícone na área de conteúdo do botão | string |
left right
|
left |
inverted |
inverted |
OPCIONAL | Utilizado quando o background possui cores escuras | boolean |
Padrão do atributo boolean (HTML) | Ausência do atributo (false ) |
loading |
loading |
OPCIONAL | Aplica o estado "progresso" | boolean |
Padrão do atributo boolean (HTML) | Ausência do atributo (false ) |
shape |
shape |
OPCIONAL | Indica o formato do botão | string |
circle block pill
|
pill |
type |
type |
OPCIONAL | Indica o tipo do botão | string |
button reset submit
|
button |
value |
value |
OPCIONAL | Valor do botão | string |
Qualquer sequência de caracteres | null |
SOBRE O TIPO BOOLEAN: Segue a recomendação padrão do atributo Boolean (HTML).
SOBRE AS PROPRIEDADES JS: Podem ser acessadas por meio do objeto HTMLElement que representa o elemento.
Slots
O componente button
possui os seguintes slots:
Slot | Descrição |
---|---|
icon |
Área de conteúdo para o ícone ilustrativo |
label default
|
Área de conteúdo para o texto descritivo |
A inserção de conteúdo exteno nos slots pode causar quebra visual e comportamental no componente. Cabe ao desenvolvedor tratar esses casos.
Estados
O componente button
possui os seguintes estados:
Estado | Descrição | Uso |
---|---|---|
Interativo | Exibido naturalmente | Nativo |
Hover | Exibido quando o cursor do mouse está sobre o botão | Nativo |
Pressionado | Exibido quando se clica no botão ou se mantém o clique | Nativo |
Desabilitado | Exibido quando o botão está inacessível no momento | Atributo |
Ativado | Exibido quando o botão, de um conjunto de botões, é ativado. Assim o botão se mantém "marcado" | Atributo |
Progresso | Exibido para indicar que uma ação ainda está acontecendo | Atributo |
Eventos
O componente button
emite os seguintes eventos:
Evento | Descrição | Tipo |
---|---|---|
brComponentDidLoad |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brComponentDidRender |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brComponentDidUpdate |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brComponentShouldUpdate |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brComponentWillLoad |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brComponentWillRender |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brComponentWillUpdate |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brConnectedCallback |
Consulte a documentação do StencilJS. | CustomEvent<this> |
brDisconnectedCallback |
Consulte a documentação do StencilJS. | CustomEvent<this> |
click |
O componente recebeu a ação de click | CustomEvent<this> |
change |
O componente teve algum conteúdo alterado | CustomEvent<this> |
Acessibilidade
O componente button
possui os requisitos de acessibilidade definidos em: https://www.gov.br/ds/components/button?tab=acessibilidade
Tecla | Função |
---|---|
Tab |
Navegação |
Space |
Acionamento |
Enter |
Acionamento |
Dependências ( internas x externas )
O componente button
possui dependência com os seguintes componentes:
Dependência | Tipo | Descrição |
---|---|---|
Icon | Componente | Ícones do Font Awesome |
O componente button
possui as seguintes dependências externas:
Dependência | Uso |
---|---|
CSS do projeto @GOVBR-DS/Core | Incluído nativamente no componente |
Breaking Changes
Breaking changes em relação à versão 1
Atributos HTML descontinuados na V1
Atributo HTML | Descrição |
---|---|
type |
usado para definir a ênfase do botão |
block |
usado para dar o formato de block ao botão |
circle |
usado para dar o formato de círculo ao botão |
Novos Atributos HTML V2
Atributo HTML | Descrição |
---|---|
type |
Informa o tipo do botão |
emphasis |
Informa a ênfase do botão |
icon-position |
Informa a posição do ícone dentro do botão |
shape |
Informa o formato do botão |